visisipy.optiland.backend#

Optiland backend for Visisipy.

Classes#

`OptilandSettings`	Backend settings that are specific to the Optiland backend.
`OptilandBackend`	Optiland backend.

Module Contents#

class visisipy.optiland.backend.OptilandSettings#

Bases: visisipy.backend.BackendSettings

Backend settings that are specific to the Optiland backend.

computation_backend: ComputationBackend#

Backend used for numerical operations. Must be one of ‘numpy’ or ‘torch’. See https://optiland.readthedocs.io/en/latest/developers_guide/configurable_backend.html for more details.

When using ‘torch’, the ‘torch’ package must be installed manually.

torch_device: TorchDevice#: Device to use for torch backend. Must be one of ‘cpu’ or ‘cuda’. Only used if computation_backend is ‘torch’.

torch_precision: TorchPrecision#: Precision to use for torch backend. Must be one of ‘float32’ or ‘float64’. Only used if computation_backend is ‘torch’.

torch_use_grad_mode: bool#: Globally enable or disable autodifferentiation for the ‘torch’ backend. Only used if computation_backend is ‘torch’.

ray_aiming: visisipy.types.OptilandRayAimingType#: The ray aiming method to be used in the optic. Must be one of ‘paraxial’, ‘robust’, or ‘iterative’.

ray_aiming_max_iterations: int#: The maximum number of iterations for the ‘iterative’ ray aiming method. Only used if ray_aiming is set to ‘iterative’.

ray_aiming_tolerance: float#: The tolerance for convergence for the ‘iterative’ ray aiming method. Only used if ray_aiming is set to ‘iterative’.

class visisipy.optiland.backend.OptilandBackend(**settings: visisipy.backend.Unpack[OptilandSettings])#

Bases: visisipy.backend.BaseBackend[OptilandSettings]

Optiland backend.

property optic: optiland.optic.Optic#

The active Optiland optic instance.

Raises:

BackendAccessError: If the backend has not been initialized with an optic.

property model: visisipy.optiland.models.OptilandEye | None#: Currently loaded Optiland eye model.

property settings: OptilandSettings#: Optiland backend settings.

property analysis: visisipy.optiland.analysis.OptilandAnalysisRegistry#: Optiland analysis registry.

update_settings(**settings: visisipy.backend.Unpack[OptilandSettings]) → None#

Apply the provided settings to the Optiland backend.

This method applies the provided settings to the Optiland backend.

new_model(*, save_old_model: bool = False, save_filename: os.PathLike | str | None = None) → None#

Initialize a new optical system.

This method initializes a new, empty optical system.

build_model(model: visisipy.EyeModel, *, start_from_index: int = 0, replace_existing: bool = False, object_distance: float = float('inf'), **kwargs) → visisipy.optiland.models.OptilandEye#

Build an optical system based on the provided eye model.

This method creates an OptilandEye instance from the provided eye model and builds the optical system. If replace_existing is True, any existing model is updated instead of building a completely new system.

Parameters:

modelEyeModel: The eye model to be used for building the optical system model.
start_from_indexint, optional: The index of the surface after which the eye model will be built. The cornea front surface will be located at start_from_index + 1.
replace_existingbool, optional: Whether to replace any existing model before building the new one. Defaults to False.
object_distancefloat: Distance between the cornea front and the surface preceding the eye model.
**kwargs: Additional keyword arguments to be passed to the OptilandEye build method.

Returns:

OptilandEye: The built optical system model.

clear_model() → None#

Clear the current optical system model.

This method initializes a new optical system, discarding any existing model.

save_model(path: str | os.PathLike | None = None) → None#

Save the current optical system model.

This method saves the current optical system model to the specified path. If no path is provided, it saves the model to the current working directory with the default name (model.json).

Parameters:

pathstr | PathLike | None, optional: The path where the model should be saved. If None, the model is saved in the current working directory. The file extension must be .json.

Raises:

ValueError: If the file extension of the provided path is not .json.

load_model(filename: str | os.PathLike, *, apply_settings: bool = False) → None#

Load an Optiland model from a JSON file.

Raises:

FileNotFoundError: If filename does not exist.
ValueError: If filename does not have a .json extension.

get_aperture() → tuple[visisipy.types.ApertureType, float]#

Get the current aperture type and value.

Returns:

tuple[str, float]: A tuple containing the aperture type and value.

Raises:

ValueError: If the aperture type in the optical system is not recognized.

set_aperture()#

Set the optic aperture from the current backend settings.

Raises:

ValueError: If the configured aperture type is unknown.
NotImplementedError: If the configured aperture type is not available in Optiland.

set_ray_aiming(ray_aiming: visisipy.types.OptilandRayAimingType, ray_aiming_max_iterations: int, ray_aiming_tolerance: float) → None#

Set the ray aiming method for the optic.

Parameters:

ray_aimingOptilandRayAimingType: The ray aiming method to be used in the optic. Must be one of ‘paraxial’, ‘robust’, or ‘iterative’.
ray_aiming_max_iterationsint: The maximum number of iterations for the ‘iterative’ ray aiming method. Only used if ray_aiming is set to ‘iterative’.
ray_aiming_tolerancefloat: The tolerance for convergence for the ‘iterative’ ray aiming method. Only used if ray_aiming is set to ‘iterative’.

Raises:

ValueError: If an invalid ray aiming method is provided. If ray_aiming_max_iterations is not a positive integer. If ray_aiming_tolerance is not a positive float.

get_fields() → list[tuple[float, float]]#

Get the fields in the optical system.

Returns:

list[tuple[float, float]]: List of field coordinates.

get_field_type() → visisipy.types.FieldType#

Get the current field type.

Returns:

FieldType: The current field type, either “angle” or “object_height”.

Raises:

ValueError: If the field type in the optical system is not recognized.

set_field_type(field_type: visisipy.types.FieldType)#

Set the field type for the optical system.

Parameters:

field_typeFieldType: The type of field to be used in the optical system. Can be either “angle” or “object_height”.

Raises:

ValueError: If an invalid field type is provided.

set_fields(coordinates: collections.abc.Iterable[tuple[float, float]], field_type: visisipy.types.FieldType = 'angle')#

Set the fields for the optical system.

This method removes any existing fields and adds the new ones provided.

Parameters:

coordinatesIterable[tuple[float, float]]: An iterable of tuples representing the coordinates for the fields.
field_typeFieldType, optional: The type of field to be used in the optical system. Can be either “angle” or “object_height”. Defaults to “angle”.

add_field(coordinate: tuple[float, float]) → int#

Add a single field to the optical system.

Parameters:

coordinatetuple[float, float]: A tuple representing the coordinates for the field.

Returns:

int: The index of the newly added field.

get_wavelengths() → list[float]#

Get the wavelengths in the optical system.

Returns:

list[float]: List of wavelengths.

set_wavelengths(wavelengths: collections.abc.Sequence[float])#

Set the wavelengths for the optical system.

This method removes any existing wavelengths and adds the new ones provided. The weight for each wavelength is set to 1.0.

Parameters:

wavelengthsSequence[float]: A sequence of wavelengths to be set for the optical system.

Raises:

ValueError: If no wavelengths are provided.

add_wavelength(wavelength: float) → int#

Add a single wavelength to the optical system.

Parameters:

wavelengthfloat: The wavelength to be added.

Returns:

int: The index of the newly added wavelength.

iter_fields() → collections.abc.Generator[tuple[int, tuple[float, float]], Any, None]#

Iterate over the fields in the optical system.

Yields:

int: Field index.
tuple[float, float]: Field X and Y coordinates.

iter_wavelengths() → collections.abc.Generator[tuple[int, float], Any, None]#

Iterate over the wavelengths in the optical system.

Yields:

int: Wavelength index.
float: Wavelength value.

set_computation_backend(backend: ComputationBackend, *, torch_device: TorchDevice = 'cpu', torch_precision: TorchPrecision = 'float32', torch_use_grad_mode: bool = False) → None#

Set the computation backend for Optiland.

Parameters:

backendComputationBackend: The computation backend to use. Must be one of ‘numpy’ or ‘torch’.
torch_devicestr, optional: The device to use for the ‘torch’ backend. Must be one of ‘cpu’ or ‘cuda’. Defaults to ‘cpu’.
torch_precisionstr, optional: The precision to use for the ‘torch’ backend. Must be one of ‘float32’ or ‘float64’. Defaults to ‘float32’.
torch_use_grad_modebool, optional: Whether to enable gradient mode for the ‘torch’ backend. Defaults to False.

Raises:

ValueError: If an invalid backend is provided. If an invalid torch_device is provided. If an invalid torch_precision is provided.

update_pupil(new_value: float) → None#

Update the pupil size in the optical system.

Parameters:

new_valuefloat: The new pupil size to be set.