Configuring the backend#

Visisipy performs all optical simulations in a backend, which uses existing optical simulation software to perform the calculations. Multiple backends are available:

OpticStudio: commercial ray tracing software. Visisipy uses ZOSPy to connect with OpticStudio.
Optiland: an open-source Python library for optical simulations.

Backends are ‘stateful’: they keep track of the current state of the optical system, including the current field and wavelength. This allows for efficient calculations and reduces the need to repeatedly set up the optical system. Various optical system properties, for example the fields and wavelengths, are also stored in the backend.

Tip

As a rule of thumb, settings that would be configured in OpticStudio’s System Explorer should be configured in the backend.

Warning

Backends may give different results for the same optical system. Always check if results are consistent with the expected behavior of the optical system. See Comparison between the OpticStudio and Optiland backends for a comparison of the backends.

Setting the backend#

The preferred backend can be selected using visisipy.set_backend:

import visisipy

visisipy.set_backend("optiland")  # or "opticstudio"

Updating settings#

Settings can be updated using visisipy.update_settings. Supported parameters are specified by visisipy.backend.BackendSettings. Furthermore, some parameters are backend-specific. For example, the OpticStudio and Optiland backends use different names for the ray aiming method and its parameters, so they have different parameters for configuring ray aiming.

visisipy.update_settings(
    field_type="angle",
    fields=[(0, 0), (0, 30)],
    wavelengths=[0.400, 0.500, 0.600],
    aperture_type="entrance_pupil_diameter",
    aperture_value=1.348,
)

The following settings can be changed:

Setting	Description	Backends	Default
`fields`	The fields to be used in the optical system, in degrees for ‘angle’ fields and millimeters for ‘object_height’ fields.	All	`[(0, 0)]`
`field_type`	The type of fields to be used in the optical system.	All	`'angle'`
`wavelengths`	The wavelengths to be used in the optical system, in microns.	All	`[0.543]`
`aperture_type`	The type of aperture to be used in the optical system.	All	`'float_by_stop_size'`
`aperture_value`	The value (e.g. diameter) of the aperture to be used in the optical system.	All	`2`
`ray_aiming`	The ray aiming method to be used in the optical system. Note: allowed values depend on the backend.	All	`'off'` for OpticStudio, `'paraxial'` for Optiland
`ray_aiming_max_iterations`	The maximum number of iterations for ray aiming, when using the `'iterative'` method.	Optiland	`10`
`ray_aiming_tolerance`	The tolerance for ray aiming, when using the `'iterative'` method.	Optiland	`1e-6`
`mode`	The OpticStudio connection mode.	OpticStudio	`'standalone'`
`zosapi_nethelper`	The path to `ZOSAPI_NetHelper.dll` for connecting to OpticStudio.	OpticStudio	`None` (automatic detection)
`opticstudio_directory`	The path to the OpticStudio installation directory.	OpticStudio	`None` (automatic detection)
`computation_backend`	The computation backend to be used for ray tracing calculations.	Optiland	`'numpy'`
`torch_device`	The device to be used for ray tracing calculations when using the ‘torch’ computation backend.	Optiland	`'cpu'`
`torch_precision`	The precision to be used for ray tracing calculations when using the ‘torch’ computation backend.	Optiland	`'float64'`
`torch_use_grad_mode`	Use PyTorch’s gradient mode for ray tracing calculations when using the ‘torch’ computation backend.	Optiland	`False`

For an overview of all settings, see:

BackendSettings for settings that are common to all backends.
OpticStudioSettings for OpticStudio-specific settings.
OptilandSettings for Optiland-specific settings.

Running Visisipy and OpticStudio side-by-side#

OpticStudio has two connection modes, standalone and extension. By default, Visisipy connects to OpticStudio in standalone mode, which launches an invisible instance of OpticStudio that is entirely controlled by Visisipy. In extension mode, Visisipy connects to an already running instance of OpticStudio. This mode can be activated by setting the mode parameter to extension when initializing the OpticStudio backend:

visisipy.set_backend("opticstudio", mode="extension")

You can read more about OpticStudio’s connection modes in the ZOSPy documentation.

Performing ray tracing on a GPU#

Optiland allows to configure the backend for numerical computations. This backend is also managed through the Optiland backend settings. By default, all computations are performed using numpy. To use GPU acceleration, the torch computation backend can be selected:

visisipy.set_backend(
    "optiland",
    computation_backend="torch",
    torch_device="cuda",  # or "cpu"
)

Getting the backend#

In some advanced cases, it may be necessary to access the backend directly. The backend can be accessed using visisipy.get_backend. Note that this function will initialize the default backend if no backend is set.

backend = visisipy.get_backend()

print("Field type:", backend.get_setting("field_type"))  # Get the field type

Field type: angle

Getting the optical system#

It may also be necessary to access the optical system directly, for example to put a camera or a lens in front of the eye model. Visisipy provides various functions to access the optical system, depending on the backend:

When using OpticStudio, the optical system can be accessed using visisipy.get_oss.
When using Optiland, the optical system can be accessed using visisipy.get_optic.

You can read more about this in backend_direct.ipynb.

# Create an eye model and draw it
model = visisipy.EyeModel()
model.build()

visisipy.get_optic().draw()

(<Figure size 1000x400 with 1 Axes>, <Axes: xlabel='Z [mm]', ylabel='Y [mm]'>)

../_images/8d1a370404d88d7fac8767b50e8088bd98027ecc5a079478971596119b526122.png