optic.optic

Optic Module

This is the core module of Optiland, which provides the class to define generic optical systems. The Optic class encapsulates the core properties of an optical system, such as the aperture, fields, surfaces, and wavelengths. It also provides methods to draw the optical system, trace rays, and perform paraxial and aberration analyses. Instances of the Optic class are used as arguments to various analysis, optimization, and visualization functions in Optiland.

Optic holds and coordinates:

• surfaces (SurfaceGroup)

• aperture, fields, wavelengths, polarization, apodization

• paraxial analysis (Paraxial)

• aberration analysis (Aberrations)

• real ray tracing (RealRayTracer)

• pickup and solve managers

Kramer Harrison, 2024

Classes

Optic([name])

A class for defining and manipulating optical systems.

class Optic(name: str | None = None)

A class for defining and manipulating optical systems.

The Optic class is central to the Optiland library, providing a comprehensive framework for representing optical systems. It encapsulates essential properties such as aperture, fields of view, constituent surfaces, and operating wavelengths. This class also offers a suite of methods for visualizing the optical system, performing ray tracing, and conducting paraxial and aberration analyses. Instances of Optic are fundamental objects passed to various analysis, optimization, and visualization functions throughout Optiland.

Parameters:

name (str, optional) – An optional name for the optical system. Defaults to None.

Variables:

• name (str | None) – An optional name for the optical system.

• aperture (Aperture | None) – The aperture of the optical system.

• fields (FieldGroup) – The group of fields defined for the system.

• wavelengths (WavelengthGroup) – The group of wavelengths used for analysis.

• surfaces (SurfaceGroup) – The group of surfaces that make up the optical system.

• paraxial (Paraxial) – A helper class for paraxial analysis of the optical system.

• aberrations (Aberrations) – A helper class for analyzing aberrations.

• ray_tracer (RealRayTracer) – The ray tracer for performing real ray traces.

• polarization (PolarizationState | Literal['ignore']) – The polarization state of the light. Defaults to ‘ignore’.

• apodization (BaseApodization | None) – The apodization function applied to the entrance pupil.

• pickups (PickupManager) – Manages pickups, which link properties of one surface to another.

• solves (SolveManager) – Manages solves, which automatically adjust surface properties to meet certain constraints.

• obj_space_telecentric (bool) – If True, the system is object-space telecentric. Defaults to False.

add_field(y: float, x: float = 0.0, vx: float = 0.0, vy: float = 0.0)

Add a field to the optical system.

Deprecated since version Use: optic.fields.add() instead.

Parameters:

• y – The y-coordinate of the field.

• x – The x-coordinate of the field. Defaults to 0.0.

• vx – The x-component of the field’s vignetting factor. Defaults to 0.0.

• vy – The y-component of the field’s vignetting factor. Defaults to 0.0.

add_sequence(name: str, steps: list[RawStep]) → SequencedOptic

Define a named sub-sequence over this optic’s own surfaces.

A sub-sequence is an alternative traversal order over the same surface objects (ghost paths, reverse traces, sub-component views). Geometry and materials are shared by reference with the base optic, so editing a surface here is immediately visible in every sequence. Ray definition (conjugates, aperture stop, aiming) always comes from this optic’s own nominal sequence; the sub-sequence defines traversal only.

Parameters:

• name – A name for the sequence, unique within this optic.

• steps – The raw step list, e.g. [0, 1, 2, (3, "reflect"), (2, "reflect"), 3, 4]. See optiland.sequences.steps.parse_steps().

Returns:

The resolved sequence, also stored in self.sequences[name].

Return type:

SequencedOptic

Raises:

• ValueError – If steps is empty, malformed, or references an out-of-range surface index.

• SequenceValidationError – If adjacent steps are not physically consistent.

add_surface(new_surface: Surface | None = None, surface_type: SurfaceType = 'standard', comment: str = '', index: int | None = None, is_stop: bool = False, material: str | BaseMaterial = 'air', **kwargs: Unpack[SurfaceParameters])

Adds a new surface to the optic.

Deprecated since version Use: optic.surfaces.add() instead.

Parameters:

• new_surface (Surface, optional) – The new surface to add. If not provided, a new surface will be created based on the other arguments.

• surface_type (str, optional) – The type of surface to create.

• index (int, optional) – The index at which to insert the new surface. If not provided, the surface will be appended to the end of the list.

• is_stop (bool, optional) – Indicates if the surface is the aperture.

• material (str, optional) – The material of the surface. Default is ‘air’.

• **kwargs – Additional keyword arguments for surface-specific parameters such as radius, conic, dx, dy, rx, ry, aperture.

Raises:

• ValueError – If a new surface is provided and no index is given.

• IndexError – If the index is out of bounds for insertion, or negative.

add_wavelength(value: float, is_primary: bool = False, unit: WavelengthUnit = 'um', weight: float = 1.0)

Add a wavelength to the optical system.

Deprecated since version Use: optic.wavelengths.add() instead.

Parameters:

• value (float) – The value of the wavelength.

• is_primary (bool, optional) – If True, this wavelength is set as the primary wavelength. Defaults to False.

• unit (WavelengthUnit, optional) – The unit of the wavelength. Defaults to ‘um’.

• weight (float, optional) – The weight of the wavelength for polychromatic analysis. Defaults to 1.0.

draw(fields: list[tuple[float, float]] | Literal['all'] = 'all', wavelengths: list[float] | Literal['primary'] = 'primary', num_rays: int = 3, distribution: DistributionType | None = None, show_apertures: bool = True, hide_vignetted: bool = False, figsize: tuple[float, float] = (10, 4), xlim: tuple[float, float] | None = None, ylim: tuple[float, float] | None = None, title: str | None = None, reference: ReferenceRay | None = None, projection: Literal['XY', 'XZ', 'YZ'] = 'YZ', ax: Axes | None = None) → tuple[Figure, Axes]

Draw a 2D representation of the optical system.

Parameters:

• fields (list[tuple[float, float]] | Literal['all'], optional) – The fields to be displayed, specified by their indices. Defaults to ‘all’.

• wavelengths (list[float] | Literal['primary'], optional) – The wavelengths to be displayed, specified by their indices. Defaults to ‘primary’.

• num_rays (int, optional) – The number of rays to trace for each field and wavelength. Defaults to 3.

• distribution (str | None, optional) – The distribution of rays. Defaults to None, which selects a default based on projection.

• show_apertures (bool, optional) – If True, overlays aperture graphics on the system view. Defaults to True.

• hide_vignetted (bool, optional) – If True, rays that vignette at any surface are not shown. Defaults to False.

• figsize (tuple[float, float], optional) – The size of the figure. Defaults to (10, 4).

• xlim (tuple[float, float] | None, optional) – The x-axis limits of the plot. Defaults to None.

• ylim (tuple[float, float] | None, optional) – The y-axis limits of the plot. Defaults to None.

• title (str | None, optional) – The title of the plot. Defaults to None.

• reference (ReferenceRay | None, optional) – The reference rays to plot, e.g., ‘chief’ or ‘marginal’. Defaults to None.

• projection (Literal["XY", "XZ", "YZ"], optional) – The projection plane. Defaults to “YZ”.

• ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created. Defaults to None.

Returns:

A tuple containing the matplotlib Figure and Axes objects of the plot.

Return type:

tuple[Figure, Axes]

draw3D(fields: list[tuple[float, float]] | Literal['all'] = 'all', wavelengths: list[float] | Literal['primary'] = 'primary', num_rays: int = 24, distribution: DistributionType = 'ring', figsize: tuple[float, float] = (1200, 800), dark_mode: bool = False, reference: ReferenceRay | None = None, hide_vignetted: bool = False)

Draw a 3D representation of the optical system.

Parameters:

• fields (list[tuple[float, float]] | Literal['all'], optional) – The fields to be displayed, specified by their indices. Defaults to ‘all’.

• wavelengths (list[int] | Literal['primary'], optional) – The wavelengths to be displayed, specified by their indices. Defaults to ‘primary’.

• num_rays (int, optional) – The number of rays to trace for each field and wavelength. Defaults to 24.

• distribution (DistributionType, optional) – The distribution of rays to trace. Defaults to ‘ring’.

• figsize (tuple[float, float], optional) – The size of the figure. Defaults to (1200, 800).

• dark_mode (bool, optional) – If True, use a dark theme for the plot. Defaults to False.

• reference (ReferenceRay | None, optional) – The reference rays to plot, e.g., ‘chief’ or ‘marginal’. Defaults to None.

• hide_vignetted (bool, optional) – If True, rays that vignette at any surface are not shown. Defaults to False.

flip()

Flips the optical system.

Deprecated since version Use: optic.updater.flip() instead.

This reverses the order of surfaces (excluding object and image planes), their geometries, and materials. Pickups and solves referencing surface indices are updated accordingly. The coordinate system is adjusted such that the new first optical surface (originally the last one in the flipped segment) is placed at z=0.0.

classmethod from_dict(data: dict[str, Any]) → Optic

Create an optical system from a dictionary.

Parameters:

data – The dictionary representation of the optical system.

Returns:

The optical system.

image_solve()

Update the image position such that the marginal ray crosses the optical axis at the image location.

Deprecated since version Use: optic.updater.image_solve() instead.

property image_surface: Surface

The image surface instance.

info()

Display the optical system information.

n(wavelength: float | Literal['primary'] = 'primary') → BEArray

Get the refractive indices of materials at a given wavelength.

Deprecated since version Use: optic.surfaces.n(wavelength) instead. To resolve the primary wavelength use optic.primary_wavelength.

Parameters:

wavelength (float | Literal['primary'], optional) – The wavelength in microns for which to calculate the refractive indices. Can be a float value or ‘primary’ to use the system’s primary wavelength. Defaults to ‘primary’.

Returns:

An array of refractive indices for each space.

Return type:

be.ndarray

property object_surface: ObjectSurface | None

The object surface instance (ObjectSurface or None).

plot_surface_sag(surface_index: int, y_cross_section: float = 0, x_cross_section: float = 0, fig_to_plot_on: Figure | None = None, max_extent: float | None = None, num_points_grid: int = 50, buffer_factor: float = 1.1)

Analyzes and visualizes the sag of a given lens surface.

Parameters:

• surface_index – The index of the surface to analyze.

• y_cross_section – The y-coordinate for the x-sag plot. Defaults to 0.

• x_cross_section – The x-coordinate for the y-sag plot. Defaults to 0.

property polarization_state: PolarizationState | None

The polarization state of the optic.

Returns:

The PolarizationState object if polarization is considered, otherwise None.

Return type:

PolarizationState | None

Raises:

ValueError – If the polarization state is invalid.

property primary_wavelength: float

The primary wavelength in microns.

remove_surface(index: int)

Removes a surface from the optic.

Deprecated since version Use: optic.surfaces.remove() instead.

Parameters:

index (int, optional) – The index of the surface to remove.

reset()

Reset the optical system to its initial state.

scale_system(scale_factor: float)

Scales the optical system by a given scale factor.

Deprecated since version Use: optic.updater.scale_system() instead.

Parameters:

scale_factor (float) – The factor by which to scale the system.

set_aperture(aperture_type: ApertureType, value: float)

Set the aperture of the optical system.

Parameters:

• aperture_type (ApertureType) – The type of the aperture. Must be one of ‘EPD’, ‘imageFNO’, or ‘objectNA’.

• value (float) – The value of the aperture.

set_apodization(apodization: BaseApodization | str | dict = None, **kwargs)

Sets the apodization for the optical system.

Deprecated since version Use: optic.updater.set_apodization() instead.

Parameters:

• apodization (BaseApodization | str | dict, optional) – The apodization to apply. Defaults to None.

• **kwargs – Additional keyword arguments used to initialize the apodization class when apodization is a string.

set_asphere_coeff(value: float, surface_number: int, aspher_coeff_idx: int)

Set an aspheric coefficient on a surface.

Deprecated since version Use: optic.updater.set_asphere_coeff() instead.

Parameters:

• value (float) – The value of the aspheric coefficient.

• surface_number (int) – The index of the surface.

• aspher_coeff_idx (int) – The index of the aspheric coefficient to set.

set_conic(value: float, surface_number: int)

Set the conic constant of a surface.

Deprecated since version Use: optic.updater.set_conic() instead.

Parameters:

• value (float) – The value of the conic constant.

• surface_number (int) – The index of the surface.

set_field_type(field_type: FieldType)

Set the type of field used in the optical system.

Deprecated since version Use: optic.fields.set_type() instead.

Parameters:

field_type (FieldType) – The type of field, e.g., ‘angle’, ‘object_height’, or ‘paraxial_image_height’.

Raises:

ValueError – If the field type is invalid.

set_index(value: float, surface_number: int)

Set the index of refraction of a surface.

Deprecated since version Use: optic.updater.set_index() instead.

Parameters:

• value (float) – The value of the index of refraction.

• surface_number (int) – The index of the surface.

set_material(material: BaseMaterial, surface_number: int)

Set the material of a surface.

Deprecated since version Use: optic.updater.set_material() instead.

Parameters:

• material (BaseMaterial) – The material.

• surface_number (int) – The index of the surface.

set_norm_radius(value: float, surface_number: int, is_fixed: bool = True)

Set the normalization radius of a surface.

Deprecated since version Use: optic.updater.set_norm_radius() instead.

Parameters:

• value (float) – The value of the normalization radius.

• surface_number (int) – The index of the surface.

• is_fixed (bool, optional) – Whether to lock the normalization radius from automatic paraxial updates. Defaults to True.

set_polarization(polarization: PolarizationState | Literal['ignore'])

Set the polarization state of the optic.

Deprecated since version Use: optic.updater.set_polarization() instead.

Parameters:

polarization (PolarizationState | Literal['ignore']) – The polarization state to set. It can be either a PolarizationState object or ‘ignore’.

set_radius(value: float, surface_number: int)

Set the radius of curvature of a surface.

Deprecated since version Use: optic.updater.set_radius() instead.

Parameters:

• value (float) – The value of the radius.

• surface_number (int) – The index of the surface.

set_ray_aiming(mode: str, max_iter: int = 10, tol: float = 1e-06, **kwargs)

Configure the ray aiming strategy.

Deprecated since version Use: optic.ray_tracer.set_aiming() instead.

Parameters:

• mode – The aiming mode (“paraxial”, “iterative”, “robust”).

• max_iter – Maximum iterations for iterative solvers.

• tol – Convergence tolerance for iterative solvers.

• **kwargs – Additional configuration parameters.

set_thickness(value: float, surface_number: int)

Set the thickness of a surface.

Deprecated since version Use: optic.updater.set_thickness() instead.

Parameters:

• value (float) – The value of the thickness.

• surface_number (int) – The index of the surface.

property surface_group: SurfaceGroup

to_dict() → dict

Convert the optical system to a dictionary.

Returns:

The dictionary representation of the optical system.

property total_track: float

The total track length of the system.

trace(Hx: ScalarOrArray, Hy: ScalarOrArray, wavelength: float, num_rays: int | None = 100, distribution: DistributionType | BaseDistribution | None = 'hexapolar', record: bool = True) → RealRays

Trace a distribution of rays through the optical system.

Parameters:

• Hx – The normalized x field coordinate(s).

• Hy – The normalized y field coordinate(s).

• wavelength (float) – The wavelength of the rays in microns.

• num_rays – The number of rays to trace. Defaults to 100.

• distribution – The distribution of rays. Can be a string identifier (e.g., ‘hexapolar’, ‘uniform’) or a BaseDistribution object. Defaults to ‘hexapolar’.

• record – Whether to store per-surface snapshots of the traced rays, which analyses and visualization read afterwards. Passing False roughly halves peak memory and is recommended for very large GPU traces where only the returned rays are needed. Defaults to True.

Returns:

A RealRays object containing the traced rays.

Return type:

RealRays

trace_generic(Hx: ScalarOrArray, Hy: ScalarOrArray, Px: ScalarOrArray, Py: ScalarOrArray, wavelength: float)

Trace generic rays through the optical system.

Parameters:

• Hx – The normalized x field coordinate(s).

• Hy – The normalized y field coordinate(s).

• Px – The normalized x pupil coordinate(s).

• Py – The normalized y pupil coordinate(s).

• wavelength (float) – The wavelength of the rays in microns.

Returns:

A RealRays object containing the traced rays.

Return type:

RealRays

update() → None

Update the surface properties (pickups, solves, paraxial properties).

Deprecated since version Use: optic.updater.update() instead.

update_normalization(surface: Surface) → None

Update the normalization radius of surfaces.

Deprecated since version Use: optic.updater.update_normalization() instead.

update_paraxial()

Update the semi-aperture of the surfaces based on paraxial analysis.

Deprecated since version Use: optic.updater.update_paraxial() instead.