Basic method of performing system analysis in ZOS-API

Also available in 日本語, 简体中文

This article gives what command to use to run an analysis in the ZOS-API and how to extract the results in a meaningful way after the analysis.

Authored By Alexandra Culler

Calling system analysis in ZOS-API

OpticStudio contains extensive help documentation for the ZOS-API which you can find under the Programming tab:

Within that documentation, all analysis enumerators can be found by navigating to the ZOSAPI.Analysis Namespace Reference:

Running an analysis

Although there are analysis-specific methods available for running certain analyses, the general method New_Analysis() can be used to open any analysis type. This method requires the analysis enumeration as the input. Once the appropriate enumeration type is located, you can run the analysis using an adaptation of the following:

my_analysis = TheSystem.Analyses.New_Analysis(ZOSAPI.Analysis.AnalysisIDM.ANALYSIS_ENUMERATOR_HERE);

Once opened, there are in general 2 ways that analysis settings can be adjusted. Firstly, some commonly-used analyses have analysis-specific settings interfaces available. An example is IAS_FftMtf. All the analysis settings interfaces are located in the ZOSAPI.Analysis.Settings Namespace.

Analysis settings

You can also check if your analysis has a settings interface using the HasAnalysisSpecificSettings property:

my_analysis.HasAnalysisSpecificSettings

If the command returns “0”, the analysis does not have a fully-implemented settings interface available. This means that the analysis settings cannot be edited via the API but have to be changed through the second option, which is via the IAS_ModifySettings command, which modifies the settings file for the analysis (.cfg file) directly:

The ModifySettings command works very similarly to the ZPL MODIFYSETTINGS keyword. Once you’ve opened your analysis and adjusted the settings, you need to re-run the analysis and retrieve the results. You can do so with the following commands:

my_analysis.ApplyAndWaitForCompletion()

my_analysis.GetResults()

You’ll also need a call to LoadFrom() if ModifySettings() was used (see API syntax example file 11 for a full demonstration).

Analysis results

As for the object returned by the GetResults() method, an analysis function may have one or more of the following types of results available:

Using GetResults() will return an object with all of the possible Public Member Functions listed, but only those that correspond to your analysis will be populated. If you’re unsure what data types are available for your analysis and want to know before starting, check out the Knowledgebase article “Generating a list of output data types for each analysis in the ZOS-API”.

For analysis types which support text output, the GetTextFile() command may also be utilized so that the user can save and manually parse through their data.

More information on the API can be found in the Knowledgebase article “ZOS-API.NET: An Overview”.

Sample files using analyses

And the ZOS-API Syntax Help which contains sample files that demonstrate how to perform analysis of a system using the ZOS-API.

For example, the sample codes 11 and 15 modify the settings of an analysis using IAS_ModifySettings.

• 11 modifies the settings of the Universal Plot.
• 15 modifies the settings of the Shaded Model.

The sample codes 10 and 24 modify the settings of a fully implemented analysis.

• 10 and 24 modify the settings of the Detector Viewer.

For more information about the sample codes, see the “Sample code for ZOS-API users” article.