ZPL is very extensive, and one of its biggest benefits is the ability to automate tedious or repetitive tasks. 

For example, imagine that you want observe the effects of the irradiance distribution due to a tilt of one or multiple elements in a complex optical system.  Since it is possible for some non-sequential (NS) ray traces to take many hours to complete, this could take considerable time to evaluate.  Without ZPL, you would have to start the initial ray trace, wait for it to finish, save the data, make the changes to the tilt of the desired object, re-run the ray trace, and repeat the process for each incremental tilt of the element.

With ZPL, you can run the macro and leave your computer until the entire process has been completed.

For demonstration purposes, we will qualitatively observe the fringe patterns in a Twyman-Green interferometer as a function of tilt of the test surface.  The macro language will be used to automate the process of adjusting the tilt of the test plate, re-tracing the rays, and saving the fringe patterns to metafiles for later viewing and post-analysis.
 

 

How was this animation created?  Find out here.

Begin by opening the sample file, “Twyman-Green_2.ZMX,” which is available via download on the very last page of this article.

FILE: "Twyman-Green_2.ZMX"

Note: This file is a slight modification of the Twyman-Green.ZMX sample file located in the ZEMAX>Samples>Non-Sequential>Ray Splitting directory.

As the file currently exists, the TEST SURFACE (Object 4) is perfectly aligned, and the resulting fringes on the screen are exclusively indicative of spherical aberration.  In this demonstration, we would like to see how the interference fringes at the detector screen change as we slightly tilt the test surface.  We may automate the process by constructing a straightforward macro in ZEMAX.



Macros can be created/edited using any ASCII text editor (such as the NOTEPAD editor).  Sometimes, it is probably easiest to start with an existing macro that performs a task similar to the one you want to achieve.  That way, you may simply make the necessary modifications to the existing macro and save it under a different file name, without having to write the entire macro from scratch. 

In cases such as these, you may select “Macros > Edit/Run ZPL macros…” from the ZEMAX main menu or press F9 on your keyboard.  Upon doing so, the ZEMAX Programming Language dialog will appear, which includes the entire list of current macros in your ZEMAX > Macros directory.  You may choose an existing macro and execute it, or you may choose to edit the file via the “Edit” button:



Selecting “Edit” will open the selected macro in the NOTEPAD Editor.  You may then edit the desired text, or you may delete the entire macro and start with a blank screen.

For the current demonstration, we will start with a completely blank text editor.  Note that EditPlus 2 is the text editor software which will be used in the following pages of this article.

In the Twyman-Green Interferometer example, a select few functions and keywords are used to automate the process of tilting the test plate and saving the images of the fringe patterns to separate files.  Type in the following text into your text editor (or you may use the already generated macro at the end of this article).  Though the ZEMAX macro language is not case sensitive, it is good practice to capitalize functions and keywords to help distinguish the macro logic.  EditPlus 2 can be used to color code functions (in blue below), keywords (in red below), and strings…which make it even easier to read and create macros.



To get a better idea of the functionality of this marco, let's review the macro logic line by line (the line numbers are indicated in gray at the very left hand side of each line):

LINE	DESCRIPTION
10	This line of the macro defines a FOR loop, which marks the beginning of a group of statements to be executed a multiple number of times.  The start_value is the initial Tilt About X (zero degrees) for the test surface, and the stop_value is the desired end value for the loop (0.1 degrees).  For simplicity, we will only execute five different tilts of the test surface, hence the increment of 0.025 degrees.
11	This starts the first statement to be executed within the FOR loop.  The SETNSCPOSITION keyword in this case is used to set the x tilt (the Tilt About X parameter) of the test object.  Note that the value is set to the value carried by the variable, x.
12	Prior to performing each new ray trace, it is important to clear the information from the detectors first.  Line twelve of the macro calls the NSDD(surf, object, pixel, data) function.  If the object number is zero, then all detectors are cleared and the function returns zero.
13	The non-sequential ray trace is performed by the keyword, NSTR.  Note that split rays, polarization, and ignore errors are all flagged by the integer 1.  This is equivalent to checking the respective boxes in the Ray Trace/Detector Control dialog.
14	UPDATE 3 updates window number 3, which is the Detector Viewer in the Twyman-Green_2.ZMX file.  This window will need to be updated to reflect the new ray trace results upon each execution of each loop.
15, 16, & 17	Each of these lines are used to define the path and name of the file to be saved upon each execution of the loop.  Strings can be added together (as in Line 17) to generate a single string entity.  The $STR(x) string function is used to convert the value of x into a string.  This way, each file will be saved under a different name which is indicative of the tilt value.  Note that the path (indicated by prefix$) may be changed to indicate any desired path.  The above path was specified simply for demonstration purposes.
18	The EXPORTWMF keyword exports any graphic window as a Windows Metafiile.  This keyword requires the filename to have the desired extension (.WMF) included in the filename argument.  The filename argument, is indicated by the filename$ string, which was defined in lines 15 through 17.
19	The NEXT keyword marks the end of the group of statements.
20	Once the FOR loop has been executed the defined number of times, the PRINT statement is used to indicate that the macro is complete.
21	The END keyword terminates the macro.

Once the macro has been constructed, you may save the macro using any desired file name.  However, the extension of the macro must be .ZPL.  For the current example, “Twyman-Green.ZPL” is a suitable file name. 

Note that ZPL macros must be saved into your ZEMAX > Macros directory or any sub-folder so that they may be called from within ZEMAX.  Or, the default folder used for macros can be set under the File > Preferences > Directories tab.  Save the current macro with the desired filename in the appropriate directory.

Macros may be executed one of two ways.  If you select “Macros” from the main ZEMAX menu, all of the available macros are listed in alphabetical order from the pull down menu that appears.  If your macro does not appear on the list, try refreshing the macro list by selecting “Refresh Macro List.” 



If the macro still does not exist after refreshing the list, double check the directory and filename of your recently created macro.

If you simply select the macro from the list, ZEMAX will automatically execute the macro.  Or, as was described earlier, you may select “Edit/Run ZPL Macros” to activate the ZEMAX Programming Language dialog.  Once the desired macro is selected, you may execute or edit the macro via the available buttons on the bottom of the dialog.



Execute the Twyman Green macro from within ZEMAX.  Be aware that the macro may take a few minutes to complete due to the number of non-sequential ray traces.  However, the point here is that this automation may be performed on a much larger scale, enabling you to use your time much more valuably while ZEMAX continues to “number-crunch.”

After the macro is complete, view the directory to which the files were saved; a total of five metafiles should have been created.  Each of the images can be used to perform a qualitative analysis as to how the interference fringes were affected by the tilt of the test surface in the Twyman Green Interferometer.

Four of the five files are shown below, excluding the nominal case in which the tilt of the test plate was zero.

TG - Tilt About X By_0.0250DEG.WMF	TG - Tilt About X By_0.0500DEG.WMF
TG - Tilt About X By_0.0750DEG.WMF	TG - Tilt About X By_0.1000DEG.WMF

The ZEMAX Programming Language offers great user-extensibility to ZEMAX.  ZPL macros can be used to perform any number of tasks and are very useful in automating a series of evaluations.  Some of the basics of ZPL are as follows:

• These ZPL capabilties are separated into two main categories: functions and keywords.  Functions can be used on the right hand side of an assignment, and will return a value or string.  Keywords are used to directly program flow, and may be used to set values in the lens prescription.
• Macros must be saved with an appropriate filename, with a .ZPL extension. 
• Macros should be saved in the ZEMAX>Macros directory so that they may be called from within ZEMAX

References

ZEMAX Optical Design Program User's Guide, ZEMAX Development Corporation