System Functions

These functions pertain to broad Zemax system properties of a lens file.

skZemax.skZemax_subfunctions._system_functions.System_AddMaterialCatalog(self, catalog: str = 'SCHOTT') → None

Adds a catalog to the current Zemax system.

See System_GetNamesOfAllMaterialCatalogs() to extract the names in python.

If more than one catalog could match the specified string, the first one sorted by ascending length, then alphabet, is taken

Parameters:

catalog (str, optional) – Name of a catalog to add, defaults to ‘SCHOTT’

skZemax.skZemax_subfunctions._system_functions.System_ConvertSequentialToNonSequential(self, first_surface: int | ZOSAPI_Editors_LDE_ILDERow = 1, last_surface: int | ZOSAPI_Editors_LDE_ILDERow = None, ignore_errors: bool = True, create_source_and_detector: bool = False, convert_global_coordinates: bool = False, convert_stop_to_nsc_aperture: bool = True, stop_mechanical_half_width: float | None = None, high_fidelity_conversion: bool = True, high_fidelity_resolution: int = 65)

Converts a sequential Zemax file to a non-sequential Zemax file.

It is recommended that you also consider running System_Lockdown() before running this function.

Parameters:

• first_surface (Union[int, ZOSAPI_Editors_LDE_ILDERow], optional) – The location of the first surface to convert. Specified by either an index or a surface object, defaults to 1

• last_surface (Union[int, ZOSAPI_Editors_LDE_ILDERow], optional) – The location of the last surface to convert. Specified by either an index or a surface object, defaults to None (last/image surface)

• ignore_errors (bool, optional) – If conversion should try to ignore errors, defaults to True

• create_source_and_detector (bool, optional) – Ignores surface indices and converts the whole system - attempting to make source and image objects too, defaults to False

• convert_global_coordinates (bool, optional) – If should convert to global coordinates, defaults to False

• convert_stop_to_nsc_aperture (bool, optional) – If should convert the stop to an non-sequential aperture, defaults to True

• stop_mechanical_half_width (float, optional) – The mechanical half width of the stop, defaults to None (uses sequential mode value)

• high_fidelity_conversion (bool, optional) – If true, any sequential surfaces that convert to grid sag representations will use bicubic interpolation instead of linear and the resolution will be set to the value specified in high_fidelity_resolution, defaults to True

• high_fidelity_resolution (str, optional) – IF high_fidelity_conversion is set to true, this sets the resolution used in the Grid Sag surface after conversion. Input is treated as ##x## with ## being one of: ‘33’, ‘65’, ‘129’, ‘257’, ‘513’, ‘1025’, ‘2049’, ‘4097’, ‘8193’, defaults to None

skZemax.skZemax_subfunctions._system_functions.System_GetIfInNonSequentialMode(self) → bool

Checks if the system is in Non-Sequential mode.

Returns:

if True the system is in Non-Sequential mode.

Return type:

bool

skZemax.skZemax_subfunctions._system_functions.System_GetIfInSequentialMode(self) → bool

Checks if the system is in Sequential mode.

Returns:

if True the system is in Sequential mode.

Return type:

bool

skZemax.skZemax_subfunctions._system_functions.System_GetMode(self) → str

Checks if in Sequential or Non-Sequential mode. returns the name of the mode.

Returns:

A string of “Sequential” or “NonSequential” indicating the current mode.

Return type:

str

skZemax.skZemax_subfunctions._system_functions.System_GetNamesOfAllApertureSettings(self, print_to_console: bool = False) → list

This function builds a list of all the system aperture settings in Zemax. This can be useful to look up what one may want to code as input to functions like System_SetApertureProperty(). This is only applicable in Sequential mode.

Parameters:

print_to_console (bool, optional) – If True will print to console, defaults to False

Returns:

A list of the names of all system apertures in Zemax.

Return type:

list

skZemax.skZemax_subfunctions._system_functions.System_GetNamesOfAllMaterialCatalogs(self, print_to_console: bool = False) → list

This function builds a list of all the material catalogs that Zemax is aware of. This can be useful to look up what one may want to code as input to functions like System_AddMaterialCatalog().

Parameters:

print_to_console (bool, optional) – If True will print to console, defaults to False

Returns:

A list of the names of all catalogs the ZOS-API knows.

Return type:

list

skZemax.skZemax_subfunctions._system_functions.System_Lockdown(self, decimalPrecision: int | None = None, excludePickups: bool | None = None, usePrecisionRounding: bool | None = None, fixModelGlasses: bool | None = None, convertSDtoMaxApertures: bool | None = None) → None

Runs the system lock-down tool to fix diameters, remove solves, and validating a sequential design prior to manufacturing or conversion to non-sequential, etc.

Parameters:

• decimalPrecision (int, optional) – Controls how many decimal places are included when UsePrecisionRounding is turned on, defaults to None

• excludePickups (bool, optional) – If true, pickup solves will be retained in the converted system; otherwise all solves will be removed including pickups, defaults to None

• usePrecisionRounding (bool, optional) – Controls whether or not editor values will be rounded in the output system, defaults to None

• fixModelGlasses (bool, optional) – Controls whether any model glass solves will be converted to the nearest material in the selected catalogs, defaults to None

• convertSDtoMaxApertures (bool, optional) – Controls whether floating semi-diameters will be treating as if they have a Maximum solve attached, defaults to None

skZemax.skZemax_subfunctions._system_functions.System_SetAdvancedProperty(self, advancedProperty: str = 'ReferenceOPD', advancedValue: float | int | str | bool = 'ExitPupil') → True

This function sets any advanced system properties. This is mostly applicable to Sequential mode, but there are some options for Non-Sequential mode which can be set here too.

Sequential and Non-Sequential Mode:

• “TurnOffThreading”: If True will not split calculations into multiple threads of execution. The only reason to turn off threading is if insufficient memory exists to break calculations into separate threads.

• “IncludeCalculatedDataInSessionFile”: If True, then calculated data for all open analysis windows (sequential mode) and/or all detectors (non-sequential mode) will be cached in the current session file.

• “IncludeToleranceDataInSessionFile”: If True, then tolerance data will be cached in the current session file.

Sequential Mode Only:

• “ReferenceOPD”: the OPD represents the phase error of the wavefront forming an image. Any deviations from zero OPD contribute to a degradation of the diffraction image formed by the optical system. Options are:

  • “ExitPupil”: (Zemax default) OPD is computed for a given ray, the ray is traced through the optical system, all the way to the image surface, and then is traced backward to the “reference sphere” which lies in the exit pupil.

  • “Infinity”: The reference to “Infinity” makes the assumption that the exit pupil is very far away and that the OPD correction term is given strictly by the angular error in the ray.

  • “Absolute”: The reference to “Absolute” and “Absolute 2” means that OpticStudio does not add any correction term to the OPD computation: the OPD is the difference of optical path length up to a reference plane between the chief ray and the ray being considered.

  • “Absolute2”: Very similar to “Absolute”, see Zemax help pdf for detail.

• “ParaxialRays”:

  • “IgnoreCoordinateBreaks”: (Zemax default) By ignoring tilts and decenters, OpticStudio can compute the paraxial properties of an equivalent centered system, which is generally the correct approach even for systems without symmetry.

  • “ConsiderCoordinateBreaks”: For ray tracing through gratings, coordinate breaks may be required even for paraxial rays, otherwise, the rays may not be able to satisfy the grating equation. Ray tracing through non-sequential objects may also require that paraxial rays consider coordinate breaks.

• “FNumMethod”:

  • “TracingRays”: (Zemax default) computes the paraxial and working F/# of a system using ray tracing.

  • “PupilSizePosition”: The preferred method of modeling systems with very large F/#s is to use afocal mode.

• “HuygensIntegralMethod”: The selection for this option determines what phase reference is used in the exit pupil for computing the Huygens Integral

  • “Auto”: (Zemax default) Allow Zemax to control which phase reference is used to compute the Huygens Integral.

  • “Planar”: always use a planar phase reference.

  • “Spherical”: always use a spherical phase reference.

• “DontPrintCoordinateBreakData”: If True, selected data will not be printed for coordinate break surfaces.

• “OPDModulo2PI”: If True, all OPD data will be computed as the fractional part of the total OPD. All OPD computations will return results that are between -π and +π, or -0.5 and +0.5 waves.

One should read 2.1.1.6. Advanced Options (System Explorer) of the Zemax help pdf file for more information on all of the above.

Parameters:

• polarizationProperty (str, optional) – The name of the polarization property to set, defaults to “ReferenceOPD”

• polarizationValue (Union[float,int,str,bool], optional) – The value to set the property to, defaults to “ExitPupil”

skZemax.skZemax_subfunctions._system_functions.System_SetApertureProperty(self, apertureProperty: str = 'ApertureValue', apertureValue: float | int | str | bool = 10.0) → None

Sets the system aperture in Zemax. This is only applicable in Sequential mode. Properties are: - “ApertureType”: The type of aperture to use. See 2.1.1.1. Aperture (System Explorer). - “ApertureValue”: The system aperture value meaning depends upon the system aperture type selected. See 2.1.1.1. Aperture (System Explorer). - “ApodizationType”: The type of anodization to apply. See 2.1.1.1. Aperture (System Explorer). - “ApodizationFactor”: The apodization factor determines how fast the amplitude decays in the pupil. Used only for Gaussian apodization. - “AFocalImageSpace”: If this box is checked, Zemax will perform most analysis features in a manner appropriate for optical systems with output beams in image space that are nominally collimated. - “FastSemiDiameters”: computes “automatic” clear semi-diameter or semi-diameters to estimate the clear aperture required on each surface to pass all rays at all field points and wavelengths. - “CheckGRINApertures”: If True, this setting instructs Zemax to check all gradient index ray traces for surface aperture vignetting. - “SemiDiameterMargin”: The clear semi-diameter or semi-diameter of every surface in “automatic” mode, is computed to be the radial aperture required to pass all rays without clipping. - “SemiDiameterMarginPct”: This semi diameter margin control allows specification of an additional amount of radial aperture as a percentage. - “TelecentricObjectSpace”: If True,Zemax will assume the entrance pupil is located at infinity, regardless of the location of the stop surface. - “IterateSolvesWhenUpdating”: Solves placed on parameters in the Lens Data Editor sometimes require iteration to compute accurately.

See 2.1.1.1. Aperture (System Explorer) in the help pdf for more detail.

Parameters:

• apertureProperty (str, optional) – The name of the aperture property to set, defaults to “ApertureValue”

• apertureValue (Union[float,int,str,bool], optional) – The value to set the property to, defaults to 10.0

skZemax.skZemax_subfunctions._system_functions.System_SetEnvironmentProperty(self, environmentProperty: str = 'AdjustIndexToEnvironment', environmentValue: float | int | bool = False) → None

Sets if the index of refractions are adjusted to the environment (temperature and pressure). This should work for both Sequential and Non-Sequential modes.

Properties are:

• “AdjustIndexToEnvironment”: Enables/disables the adjustment to the environment properties

• “Temperature”: If adjust_index_data_to_environment, then this is the temperature in celsius to use

• “Pressure”: If adjust_index_data_to_environment, then this is the pressure in atmospheres to use

Parameters:

• environmentProperty (str, optional) – The property of the environment to set. Options are: “AdjustIndexToEnvironment”, “Temperature” (in degrees C), and “Pressure” (in ATM), defaults to “AdjustIndexToEnvironment”

• environmentValue (Union[float,int,bool], optional) – Value to set the environment property to, defaults to False

skZemax.skZemax_subfunctions._system_functions.System_SetGlobalCoordinateReferenceSurface(self, reference_surface: int | str = 1) → None

Sets the Global Coordinate Reference Surface. This is a special property under the Aperture properties. Local coordinate systems are defined (with rotation and translation matrices) from this global reference surface.

This is only applicable in Sequential mode.

Usually this is specified with an index indicating the surface of either your sequential or non-sequential system. However, Zemax supports some general default options:

• Image

• Object

• Stop

These can be given as strings to specify one of these as the global reference.

Parameters:

reference_surface (Union[int,str], optional) – The surface to set as the global - either an index or a string as described above., defaults to 1

skZemax.skZemax_subfunctions._system_functions.System_SetNonSequentialMode(self) → bool

Sets/ensures the current system to be in Non-Sequential mode.

Returns:

An error checking boolean. True if the mode was set correctly.

Return type:

bool

skZemax.skZemax_subfunctions._system_functions.System_SetPolarizationProperty(self, polarizationProperty: str = 'ConvertThinFilmPhaseToRayEquivalent', polarizationValue: float | int | str | bool = True) → True

The default input polarization state for many Sequential analysis computations which use polarization ray tracing. For Non-Sequential mode, most polarization settings are controlled by the sources, but two settings can still be controlled here.

Sequential and Non-Sequential Mode:

• “ConvertThinFilmPhaseToRayEquivalent”: converts the polarization phase computed using thin film conventions to phase along the ray. If unselected, the ray coefficients will not be converted from the field coefficients. The recommended and default setting is to convert the field thin film phase to ray phase.

• “Method”: selects the method used to determine the S and P vectors based on the ray vector. Values are:

  • “XAxis”: The P vector is determined from K cross X, and S = P cross K. This method is the default.

  • “YAxis”: The S vector is determined from Y cross K, and P = K cross S

  • “ZAxis”: The S vector is determined from K cross Z, and P = K cross S

Sequential Mode Only:

• “Unpolarized”: If True, then the polarization values Jx, Jy, X-Phase, and Y-Phase are ignored, and an unpolarized computation is done.

• If Unpolarized == False:

  • “Jx”: the magnitude of the electric field in X

  • “Jy”: the magnitude of the electric field in Y

  • “XPhase”: the phase X angle in degrees

  • “YPhase”: the phase Y angle in degrees

One should read 2.1.1.5.7. Defining the Initial Polarization of the Zemax help pdf file for more information.

Parameters:

• polarizationProperty (str, optional) – The name of the polarization property to set, defaults to “ConvertThinFilmPhaseToRayEquivalent”

• polarizationValue (Union[float,int,str,bool], optional) – The value to set the property to, defaults to True

skZemax.skZemax_subfunctions._system_functions.System_SetSequentialMode(self) → bool

Sets/ensures the current system to be in Sequential mode.

Returns:

An error checking boolean. True if the mode was set correctly.

Return type:

bool