zospy.analyses.base.BaseAnalysisWrapper

class zospy.analyses.base.BaseAnalysisWrapper

Bases: ABC, Generic[AnalysisData, AnalysisSettings]

Base class for analysis wrappers.

This class provides a common interface for all analysis wrappers. It defines the methods and properties that all analysis wrappers should implement.

Attributes:

TYPEstr

The type of the analysis. This should match the AnalysisIDM constant in OpticStudio.

_needs_config_filebool

Flag to indicate if the analysis requires a configuration file.

_needs_text_output_filebool

Flag to indicate if the analysis requires a text output file.

Methods

__call__(oss, *args, **kwargs)	Run the analysis and return the results.
get_data_grid([cell_origin])	Get the data grids from the analysis result.
get_data_series()	Get the data series from the analysis result.
get_text_output()	Get the text output of the analysis.
parse_output(grammar, transformer[, result_type])	Parse the text output of the analysis.
run(oss[, config_file, text_output_file, ...])	Run the analysis and return the results.
run_analysis(*args, **kwargs)	Run the analysis and return the results.
update_settings(*[, settings, settings_kws])	Update the settings of the analysis using a settings object or keyword arguments.
with_settings(settings)	Create a new analysis with the specified settings.

__init__(*, settings_kws: dict[str, Any] | None = None)

Create a new analysis wrapper.

Settings can be changed by passing the settings as keyword arguments. Use the with_settings method to specify the settings using a settings object.

Parameters:

settings_kwsdict[str, Any]

Arguments to set the settings of the analysis.

Raises:

ValueError

If settings is not a dataclass.

property analysis: Analysis

The OpticStudio analysis object. This property is set when the analysis is run.

property config_file: Path | None

Path to the temporary configuration file.

This file is used to store the settings of the analysis and can only be set from the run method.

Returns:

Path | None

Path to the temporary configuration file.

Raises:

ValueError

If the analysis does not require a configuration file.

get_data_grid(cell_origin: Literal['bottom_left', 'center'] = 'bottom_left') → DataFrame | None

Get the data grids from the analysis result.

Parameters:

cell_originLiteral[“bottom_left”, “center”]

Defines how minx and miny are handled to determine coordinates. Either ‘bottom_left’ indicating that they are defining the bottom left of the grd cell, or ‘center’, indicating that they provide the center of the grid cell. Defaults to ‘bottom_left’.

Returns:

pd.DataFrame | None

The data grids from the analysis result, or None if there are no data grids.

get_data_series() → DataFrame | None

Get the data series from the analysis result.

Returns:

pd.Series | None

The data series from the analysis result, or None if there are no data series.

get_text_output() → str

Get the text output of the analysis.

property oss: OpticStudioSystem

The OpticStudio system. This property is set when the analysis is run.

parse_output(grammar: str, transformer: type[Transformer], result_type: type[AnalysisData] | None = None) → AnalysisData

Parse the text output of the analysis.

run(oss: OpticStudioSystem, config_file: str | Path | None = None, text_output_file: str | Path | None = None, oncomplete: OnComplete | Literal['Close', 'Release', 'Sustain'] = 'Close') → AnalysisResult[AnalysisData, AnalysisSettings]

Run the analysis and return the results.

This method opens the analysis in OpticStudio and creates temporary files if needed. After running the analysis, the temporary files are removed and the analysis is closed, released, or sustained based on oncomplete.

The config_file is ignored if self._needs_config_file is False. The text_output_file is ignored if self._needs_text_output_file is False.

Parameters:

ossOpticStudioSystem

The OpticStudio system.

config_filestr | Path | None

Path to the configuration file. If None, a temporary file will be created.

text_output_filestr | Path | None

Path to the text output file. If None, a temporary file will be created.

oncompleteOnComplete | Literal[“Close”, “Release”, “Sustain”]

Action to perform after running the analysis. If “Close”, the analysis will be closed. If “Release”, the analysis will be kept open but not active. If “Sustain”, the analysis will be kept open and active.

Returns:

AnalysisResult

The analysis results.

abstractmethod run_analysis(*args, **kwargs) → AnalysisData

Run the analysis and return the results.

property settings: AnalysisSettings

Settings of the analysis.

property text_output_file: Path | None

Path to the temporary text output file.

This file is used to store the text output of the analysis and can only be set from the run method.

Returns:

Path | None

Path to the temporary text output file.

Raises:

ValueError

If the analysis does not require a text output file.

update_settings(*, settings: AnalysisSettings | None = None, settings_kws: dict[str, Any] | None = None) → None

Update the settings of the analysis using a settings object or keyword arguments.

Settings can be specified as an object and as keyword arguments. If both are specified, the keyword arguments take precedence. If no settings are specified, the default settings are used. Furthermore, instead of using a reference to the settings object, a new settings object is created with the specified parameters. This is done to avoid modifying the original settings object.

Parameters:

settingsAnalysisSettings

Analysis settings object.

settings_kws

Dictionary with the settings parameters.

Raises:

ValueError

If settings is not a dataclass.

classmethod with_settings(settings: AnalysisSettings)

Create a new analysis with the specified settings.

Parameters:

settingsAnalysisSettings

Settings of the analysis.

Returns:

BaseAnalysisWrapper

The analysis wrapper.