zospy.analyses.physicaloptics.physical_optics_propagation

zospy.analyses.physicaloptics.physical_optics_propagation(oss: OpticStudioSystem, wavelength: Literal['All'] | int = 'All', field: int = 1, start_surface: Literal['Ent. Pupil'] | int = 1, end_surface: Literal['Image'] | int = 'Image', surface_to_beam: float = 0.0, use_polarization: bool = False, separate_xy: bool = False, use_disk_storage: bool = False, beam_type: constants.Analysis.PhysicalOptics.POPBeamTypes | str = 'GaussianWaist', beam_file: str = '', beam_parameters: dict | None = None, x_sampling: constants.Analysis.SampleSizes | str | int = 32, y_sampling: constants.Analysis.SampleSizes | str | int = 32, x_width: float = 1.0, y_width: float = 1.0, use_total_power: bool = False, total_power: float = 1.0, use_peak_irradiance: bool = True, peak_irradiance: float = 1.0, show_as: constants.Analysis.PhysicalOptics.POPShowAsTypes | str = 'FalseColor', data_type: constants.Analysis.PhysicalOptics.POPDataTypes | str = 'Irradiance', project: constants.Analysis.PhysicalOptics.POPProjectionTypes | str = 'AlongBeam', contour_format: str = '', plot_scale: float = 0, scale_type: constants.Analysis.PhysicalOptics.POPScaleTypes | str = 'Linear', zoom_in: constants.Analysis.PhysicalOptics.POPZoomTypes | str = 'NoZoom', row_or_column: int | Literal['Center'] = 'Center', zero_phase_level: float = 0.001, save_output_beam: bool = False, output_beam_file: str = '', save_beam_at_all_surfaces: bool = False, compute_fiber_coupling_integral: bool = False, ignore_fibre_polarization: bool = True, fiber_type: constants.Analysis.PhysicalOptics.POPFiberTypes | str = 'GaussianWaist', fiber_position: constants.Analysis.PhysicalOptics.POPFiberPositions | str = 'ChiefRay', tilt_about_x: float = 0.0, tilt_about_y: float = 0.0, fiber_type_file: str = '', fiber_parameters: dict | None = None, auto_calculate_beam_sampling: bool = False, oncomplete: OnComplete | str = OnComplete.Close) → AnalysisResult

Physical Optics Propagation analysis.

See the OpticStudio documentation for a more in depth description of most parameters.

Parameters:

osszospy.zpcore.OpticStudioSystem

A ZOSPy OpticStudioSystem instance. Should be sequential.

wavelengthstr | int

The wavelength to use in the analysis. Either ‘All’ or an integer specifying the wavelength number. Defaults to ‘All’.

fieldint

The field number of the chief ray used to align the beam for the analysis. Should be an integer specifying the field number. Defaults to 1.

start_surfacestr | int

The surface that is to be analyzed. Either ‘Ent. Pupil’ or an integer specifying the surface number. Defaults to

end_surfacestr | int

The surface that is to be analyzed. Either ‘Image’ or an integer specifying the surface number. Defaults to ‘Image’.

surface_to_beamfloat

Distance from starting surface to starting beam position. Defaults to 0.0.

use_polarizationbool

Use polarization. Defaults to False.

separate_xybool

Separate propagation in X Y direction. Defaults to False.

use_disk_storagebool

Use disk storage. Defaults to False.

beam_typeconstants.Analysis.PhysicalOptics.POPBeamTypes | str

The beam type. Defaults to ‘GaussianWaist’.

beam_file:

The beam file used for the beam definition. Should include the .ZBF extension. The beam files have to be located in the OpticStudio <pop> folder. Only used when beam_type is set to ‘File’, ‘DLL’ or ‘Multimode’. Defaults to ‘’.

beam_parametersdict | None

The beam parameters. Either a dictionary containing the beam parameters settings or None. Only the parameters that are defined in the dictionary will be set, the other parameters will remain their default value. Note that the accepted beam parameters vary per beam type. The accepted parameters for a specific beam type and their default values can be obtained through zospy.analysis.physicaloptics.pop_create_beam_parameter_dict(), which can then be adjusted and parsed to beam_parameters. When set to None, the default beam parameters will be used. Defaults to None.

x_samplingconstants.Analysis.SampleSizes | str | int

The number of points used to sample the beam in the x direction. Either specified using constants.Analysis.SampleSizes, a string (e.g. ‘32x32’) or integer (e.g. 32). Note that the string or integer should match one of the sample sizes in constants.Analysis.SampleSizes (32 or ‘32x32’ for ‘S_32x32’ etc.). Defaults to 32.

y_samplingconstants.Analysis.SampleSizes | str | int

The number of points used to sample the beam in the y direction. Either specified using constants.Analysis.SampleSizes, a string (e.g. ‘32x32’) or integer (e.g. 32). Note that the string or integer should match one of the sample sizes in constants.Analysis.SampleSizes (32 or ‘32x32’ for ‘S_32x32’ etc.). Defaults to 32.

x_widthfloat

The original with of the region represented by the array in OpticStudio lens units. Defaults to 1.0.

y_widthfloat

The original with of the region represented by the array in OpticStudio lens units. Defaults to 1.0.

use_total_powerbool

Use total power. Note that either use_total_power or use_peak_irradiance has to be True. Defaults to False.

total_powerfloat

The total power. Only used when use_total_power is True. Defaults to 1.0.

use_peak_irradiancebool

Use peak irradiance. Note that either use_total_power or use_peak_irradiance has to be True. Defaults to True.

peak_irradiancefloat

The peak irradiance. Only used when use_peak_irradiance is True. Defaults to 1.0.

show_asconstants.Analysis.PhysicalOptics.POPShowAsTypes | str

Defines the default graph in OpticStudio. Defaults to ‘FalseColor’.

data_typeconstants.Analysis.PhysicalOptics.POPDataTypes | str

Defines the type of output data. Defaults to ‘Irradiance’.

projectconstants.Analysis.PhysicalOptics.POPProjectionTypes | str

Defines the perspective from which the beam is viewed. Defaults to ‘AlongBeam’.

contour_formatstr

The contour format string. An empty string means no formatting. Only used when show_as is set to ‘Contour’. Defaults to ‘’.

plot_scalefloat

The plot scale. Defaults to 0.

scale_typeconstants.Analysis.PhysicalOptics.POPScaleTypes | str

The scale type for the plot. Defaults to ‘Linear’.

zoom_inconstants.Analysis.PhysicalOptics.POPZoomTypes | str

The zoom factor for the plot. Defaults to ‘NoZoom’.

row_or_columnint | str

An integer defining the row or column number used when show_as is either ‘CrossX’ or ‘CrossY’. Also accepts ‘Center’. Defaults to ‘Center’.

zero_phase_levelfloat

The lower limit on the relative irradiance. Data points below this threshold have a phase value of 0. Defaults to 0.001.

save_output_beambool

Defines whether the output beam should be saved. Defaults to False.

output_beam_filestr

The filename to which the output beam should be saved. Should NOT include the .ZBF extension. The file will be saved in the OpticStudio <pop> folder.

save_beam_at_all_surfacesbool

Defines whether the beam should be saved at all surfaces. Only used when save_output_beam is set to True. Defaults to False.

compute_fiber_coupling_integralbool

Defines whether the fibre coupling is computed. Defaults to False.

ignore_fibre_polarization

Defines whether polarization is considered. Defaults to True.

fiber_typeconstants.Analysis.PhysicalOptics.POPFiberTypes | str

The fiber type. Defaults to ‘GaussianWaist’.

fiber_positionconstants.Analysis.PhysicalOptics.POPFiberPositions | str

The reference for the center of the receiving fiber. Defaults t ‘ChiefRay’.

tilt_about_x

The tilt of the fiber around the x-axis in degrees with respect to the beam. Defaults to 0.0.

tilt_about_y

The tilt of the fiber around the y-axis in degrees with respect to the beam. Defaults to 0.0.

fiber_type_file

The file containing the fiber description. Only used is fiber_type is set to ‘File’ or ‘DLL’.

fiber_parametersdict | None

The fiber parameters. Either a dictionary containing the fiber parameters settings or None. Only the parameters that are defined in the dictionary will be set, the other parameters will remain their default value. Note that the accepted beam parameters vary per fiber type. The accepted parameters for a specific fiber type and their default values can be obtained through zospy.analysis.physicaloptics.pop_create_fiber_parameter_dict(), which can then be adjusted and parsed to fiber_parameters. When set to None, the default fiber parameters will be used. Defaults to None.

auto_calculate_beam_samplingbool

Defines whether the beam sampling should be automatically calculated. Will adjust x_width and y_width. This calculation is done just before the analysis is run. Only used when beam_type is not one of (‘File’, ‘DLL’, ‘Multimode’). Defaults to False.

oncompleteOnComplete | str

Defines behaviour upon completion of the analysis. Should be one of [‘Close’, ‘Release’, ‘Sustain’]. If ‘Close’, the analysis will be closed after completion. If ‘Release’, the analysis will remain open in OpticStudio, but the link with python will be destroyed. If ‘Sustain’ the analysis will be kept open in OpticStudio and the link with python will be sustained. To enable interaction when oncomplete == ‘Sustain’, the OpticStudio Analysis instance will be available in the returned AnalysisResult through AnalysisResult.Analysis. Defaults to ‘Close’.

Returns:

AnalysisResult

A Physical Optics Propagation analysis result.