Zemax Programming Language (ZPL) allows users to automate a number of tasks in OpticStudio, for both Sequential and Non-Sequential mode. This article describes use of the ZPL keyword ZRDPLAYBACK to restore data from a previously saved ZRD file onto detectors in a Non-Sequential system.
Authored By Sanjay Gangadhara
Introduction
In Non-Sequential mode, the keyword NSTR is used to trace rays, and the results of the ray-trace may be obtained using evaluation ZPL functions such as NSDD or NSDE. However, using NSDD right after NSTR does not allow filtering of ray-trace data before evaluation, even if NSTR was used to filter the data before saving to the Ray Database file.
The solution to this issue is to use the ZRDPLAYBACK keyword which reloads saved ZRD data onto the detectors in the system. The data may then be filtered, and any subsequent calls to functions which evaluate the detector data will account for the filtering. Multiple uses of ZRDPLAYBACK allow the user to obtain multiply-filtered information from the ray-trace.
Example Setup: Diffraction Grating and cylinder lens
The archive file for a simple example used to illustrate the capabilities of ZRDPLAYBACK is attached to this article. Also provided as an attachment is a ZPL macro which is to be used with the file.
The file consists of a polychromatic collimated beam of light (created using the Source Ellipse object) incident on a Diffraction Grating. The diffracted light then passes through a cylinder lens (created using the Biconic Lens object) and is brought to focus on a Detector Color object. More details on the Source Ellipse object may be found in the chapter of the OpticStudio manual entitled "NSC Sources". More details on the Diffraction Grating and Biconic Lens objects may be found in the chapter of the OpticStudio help files entitled "NSC Objects". More details on the Detector Color object may be found in the chapter of the OpticStuio help filesentitled "NSC Detectors", as well as in the Knowledgebase article "How to measure and optimize color data".
The spectral distribution of the source is provided in the Wavelength Data dialog:
Note that the weighting of each wavelength is equal. If we were to trace rays "manually" in OpticStudio using the Ray Trace Control:
we would find that the grating provides a nice splitting of the beam into the wavelength components:
But how much power is in each wavelength? We could find this out by saving the results of the ray-trace to a ZRD file and then applying filter strings in the Detector Viewer for each wavelength separately. Such a task is best suited for a ZPL macro.
First Results: Power at Each Wavelength
The macro provided at the end of this article is used to save ray-trace results to a ZRD file and then analyze filtered results using the ZRDPLAYBACK keyword. The first step in the macro is to clear the detector, and then run a ray-trace with results saved to a ZRD file:
! Clear the detector
x = NSDE(1,0,0,0,0,0)
! Trace rays
A$ = "No_Scatter.ZRD"
NSTR 1, 1, 0, 0, 1, 1, 1, 1, A$
The file name "No_Scatter" is used to distinguish between this case and the next one we'll look at (in the next section of the article). From this ray-trace, we can get the total power incident on the detector, both in Watts and Lumens:
! Obtain total power in Watts and Lumens
tot_pow_W = NSDE(1,4,0,0,1,0)
tot_pow_L = NSDE(1,4,0,0,3,0)
If we wish to get the power at each wavelength, we need to filter the data. Rather than running a new ray-trace for each filtered case, we simply use ZRDPLAYBACK to filter the data. The syntax for the keyword is:
ZRDPLAYBACK zrdfilename, surface, detector, clear, filterstring
More information on each of these inputs is provided in the chapter of the OpticStudio manual entitled "Zemax Programming Language". In this case, we will use the Wn filter string to isolate rays at each wavelength:
! Get power at each wavelength using ZRDPLAYBACK with filter string
ZRDPLAYBACK A$, 1, 4, 4, "W1"
w1_pow_W = NSDE(1,4,0,0,1,1)
w1_pow_L = NSDE(1,4,0,0,3,1)
ZRDPLAYBACK A$, 1, 4, 4, "W2"
w2_pow_W = NSDE(1,4,0,0,1,2)
w2_pow_L = NSDE(1,4,0,0,3,2)
ZRDPLAYBACK A$, 1, 4, 4, "W3"
w3_pow_W = NSDE(1,4,0,0,1,3)
w3_pow_L = NSDE(1,4,0,0,3,3)
More information on filter strings may be found in the chapter of the OpticStudio manual entitled "NSC - Overview" as well as in the Knowledgebase article entitled "How to identify specific rays using filter strings".
We then print the results using the PRINT keyword, and find:
which shows an equal amount of power for each wavelength in Watts - as expected given the equal wavelength weighting in the spectral distribution of the source. The power in Lumens is correspondingly higher for the central wavelength, since the human eye is more sensitive to this wavelength.
Adding Scatter
In the next part of the macro, we account for possible scattering that may occur in this system. The cylinder lens has been defined as a bulk scattering object, in which light can undergo fluorescence:
More information on modeling fluorescence via bulk scattering may be found in the Knowledge Base article entitled "How to model fluorescence using bulk scattering".
To account for the fact that scattering will spread the emission, we first increase the size of the detector from 4 mm x 2 mm to 10 mm x 10 mm using the SETNSCPARAMETER keyword:
! Allow for bulk scattering by increasing detector size
! and clearing detector
SETNSCPARAMETER 1, 4, 1, 10
SETNSCPARAMETER 1, 4, 2, 10
x = NSDE(1,0,0,0,0,0)
We repeat the ray-trace, saving the results to a different ZRD file:
! Trace rays with bulk scattering on
A$ = "Bulk_Scatter.ZRD"
NSTR 1, 1, 0, 1, 1, 1, 1, 1, A$
Again, the total power may be directly obtained from the ray-trace results:
! Obtain total power in Watts and Lumens
tot_pow_W = NSDE(1,4,0,0,1,0)
tot_pow_L = NSDE(1,4,0,0,3,0)
The ZRDPLAYBACK keyword may again be used to filter for the results. However, in this case a different filter string is required. It is not sufficient to know the launch wavelength, but the wavelength of each ray on the detector itself. This may be obtained using the X_WAVERANGE filter string:
! Get power at each wavelength using ZRDPLAYBACK with filter string
ZRDPLAYBACK A$, 1, 4, 4, "X_WAVERANGE(4,0.48,0.49)"
w1_pow_W = NSDE(1,4,0,0,1,1)
w1_pow_L = NSDE(1,4,0,0,3,1)
ZRDPLAYBACK A$, 1, 4, 4, "X_WAVERANGE(4,0.58,0.59)"
w1_pow_W = NSDE(1,4,0,0,1,2)
w1_pow_L = NSDE(1,4,0,0,3,2)
ZRDPLAYBACK A$, 1, 4, 4, "X_WAVERANGE(4,0.65,0.66)"
w1_pow_W = NSDE(1,4,0,0,1,3)
w1_pow_L = NSDE(1,4,0,0,3,3)
The wavelength ranges are chosen appropriately for the input spectrum. More information on the X_WAVERANGE filter string may be found in the chapter of the OpticStudio help files entitled "NSC - Overview".
The results are then again printed to the screen:
As expected, much more power ends up at the long wavelength (red) due to scattering of light from short to long wavelength. However, in Lumens the power is still highest at the middle wavelength, where the human eye is most sensitive. The results for all light incident on the detector may be observed by updating the detector viewer, after another call to ZRDPLAYBACK to "remove" the last used filter:
! Update Detector Viewer for all wavelength data
ZRDPLAYBACK A$, 1, 4, 4
UPDATE 2
Here are those results:
