There are two primary resources for API help: firstly, there are several various articles available on the Knowledgebase which provide examples and tutorials. Secondly, there’s a help document dedicated only to API syntax, which is accessible through The Help Tab…ZOS-API Syntax Help or in your OpticStudio install folder. That document provides the properties, methods, and inheritances of each object type, as well as around two dozen example scripts which demonstrate general functionality in the 4 programming languages we primarily support (MATLAB, Python, C#, and C++).

When reading the ZOS-API Syntax document, the important thing to remember is that methods return objects which are members of the displayed interface (or type). Similarly, the type of a property is also given to the left of the property name. For example (in pseudo-code), using the method GetSurfaceAt() the user might make the assignment:

Surface1 = TheApplication.PrimarySystem.LDE.GetSurfaceAt(1)

Here, the newly assigned item named “Surface1” is a member of the interface ILDERow. We know that because in the ZOS-API Syntax Help document, the method GetSurfaceAt() is shown to return an object of type ILDERow:

In the API Syntax Help, we can now click on the above-highlighted “ILDERow” (the interface to which the Surface1 object belongs) to see all of the properties, methods, etc. available to the Surface1 object. For example, in the ILDERow interface, we can see there’s a property “Thickness”, which is a sget/set] property. The type is double, which we know because the API Syntax Help says “double” next to the property name. So, we can then change the thickness of surface 1 with:

Surface1.Thickness = 50

Or, we could have done this with a single assignment, using:

TheApplication.PrimarySystem.LDE.GetSurfaceAt(1).Thickness = 50

Are there any good tools for searching for syntax?  I would really like to load a fairly complex merit function but can't seem to find the correct syntax

Hi Barbara,

Thanks for your question here!

In order to load a Merit Function, you should use the LoadMeritFunction or the InsertMeritFunction member function of the ZOSAPI.Editors.MFE.IMeritFunctionEditor Interface Reference. LoadMeritFunction replaces the entire Merit Function, while InsertMeritFunction loads a merit function from the file and inserts it at the specified location:

For further reference on the correct syntax, you may check the sample codes of Examples Open File and Optimize, and Sequential Optimization.

Finally, I would like to reccomend to check out the following knowledgebase articles to familiarize with the ZOS-API structure and syntax:

Understanding the basics of ZOS-API structure

Navigating the ZOS-API Syntax Help document

Sample code for ZOS-API users

If you have further questions, please let us know and we will be happy to help!

Best,

Csilla

The sample codes and knowledge base are helpful, but they don't address the challenge of searching and finding correct syntax.  I find it very cumbersome to find what I am looking for if its not the same as the examples.

I'm currently trying to modify the sampling frequency in the GMTA operand in the merit function

Hi Barbara,

I highly recommend taking a look at these two articles that Csilla posted:

• 
  
  

  Understanding the basics of ZOS-API structure

  
  
  



• 
  
  

  Navigating the ZOS-API Syntax Help document

  
  
  

These resources provide step-by-step instruction on how to interpret the ZOS-API language which makes navigating the syntax guide much smoother. In general, I usually navigate through the syntax guide in the same way I navigate through the OS user interface. For example, if I need a Merit Function operand's value (without including it in the Merit Function itself), I know that it will be related to the Merit Function Editor. The Merit Function Editor is a type of Editor so it will be in the Editors namespace. Here is a path to that point:

Is GMTA in your Merit Function currently? In that case, you will use the IMFERow Class instead. In that class, we see that we can get access to any cell of a particular operand with GetOperandCell. This accepts an enumerated value as an input which is given by clicking on the enumerated variable's name:

The sampling for GMTA is parameter #1, so the syntax is as follows: TheMFE.GetOperandAt(1).GetOperandCell(ZOSAPI.Editors.MFE.MeritColumn.Param1).IntegerValue = 8;

You may wonder how I knew to add 'IntegerValue' to the end. This is because the GetOperandCell public member function is part of the IEditorCell interface. If we click there, we see all of the properties which allow us to SET a new value. In the Merit Function, the sampling is given by an integer, so we can assume that the IntegerValue property is the one we need:

Again, most of this is discussed in those articles Csilla and I have shared! I recommend watching the videos there to see this navigation technique in action. 

Let me know if you have any other questions about this!

Best,

Allie