Publish date: 2025/04/15
Authored by: Zach Derocher
Introduction
This article provides a ZOSAPI tool which automates the export of diffractive optical elements (DOEs) defined using the parametric/dynamic Lumerical Sub-Wavelength Model (LSWM) into the JSON data format. This enables one-way conversion from the dynamic LSWM model to the static LSWM model. Since the static LSWM model is also supported in Ansys Speos, the tool also simplifies the DOE data exchange process between the two software.
Background
Ansys’s solution for DOE optical design and simulation within the Ansys Zemax OpticStudio or Ansys Speos ray-tracing environment leverages Ansys Lumerical FDTD solver for computing grating efficiency via RCWA/FDTD. Within Zemax, two simulation modes are possible (see below), a “static” mode based on stored RCWA data, and a “dynamic” connection with Lumerical which enables parametric modelling of DOE characteristics; in Speos only the static workflow is currently supported.
The choice between DOE analysis environment largely depends on the simulation goals; for instance, in the design phase of a DOE, dynamic adjustment of DOE structure parameters (i.e. grating depth, blaze angle, etc.) enables efficient design workflow. On the other hand, needlessly re-computing the DOE efficiency is time-consuming, and so once the grating design is fixed moving to the static workflow (where the RCWA results are pre-computed and stored to disc) may be preferred. Moreover, the static workflow also allows DOE simulation with LSWM within the Speos environment.
By automating the LSWM JSON export process, the tool provided in this article supports the workflow of beginning DOE design using the dynamic LSWM model, and later switching to the static model i.e. for system validation or simulation within the Speos environment.
System Requirements
To use the dynamic Lumerical-Zemax LSWM workflow or the JSON export tool provided here, both Zemax OpticStudio and Lumerical FDTD need to be installed on the same PC with Windows as the operating system.
The Zemax OpticStudio edition must be Ansys Zemax OpticStudio Premium or Ansys Zemax OpticStudio Enterprise, vesion 2024 R1.0 or later. Legacy Zemax OpticStudio is not allowed. Both Lease and Paid-Up Ansys Zemax licenses are valid to use this tool.
Lumerical must have an FDTD license, and the edition must be 2024 R1.0 or later.
The LSWM JSON Export Tool provided in this article also relies on Python to employ the FDTD API; Python version v3.7, v3.8, v3.9, v3.10, or v3.11 must be installed and available in PATH.
Installation
To install the LSWM JSON Export Tool, first ensure the above system requirements are met.
Next, download the attachments of this article. Unzip the contents of the download package to the folder “…\Documents\Zemax\ZOS-API\User Analysis\”. If Zemax was already open, restart the program; the user analysis will now be available under Programming>User Analyses>LswmJsonExport
Usage
To execute the LSWM JSON Export Tool, Zemax must be in non-sequential mode and at least one object defined using the dynamic LSWM DLL must be present in the system.
Note that when defining a DOE in the Zemax non-sequential model using the dynamic LSWM DLL, the user must choose both the LSWM .dll file as well as a .fsp file (lumerical model file) which defines the DOE object shape and parameterization. For the .dll file, it is recommended to use the most recent version of the LSWM DLL; development and validation testing of this JSON export tool was carried out using the LSWM v2024R2-2 DLL. For the .fsp file, it is recommended to use the latest Ansys-provided Lumerical FSP models (i.e. “lswm_1D_slang_2024R1.fsp”, “lswm_2D_hex_cylinder_2024R1.fsp”, etc.); this is because the LSWM JSON Export Tool relies on the standardized parameterization used in those models. This DLL and FSP files can be downloaded from this Knowledgebase Article.
The LSWM JSON Export Tool can be executed by following these steps
- Open the tool via the Programming Tab > User Analyses > LswmJsonExport.
- Open the analysis settings, and adjust as needed (see following discussion for details on analysis settings)
- (optional) Click “OK” to validate the settings; any detected issues will be reported in the analysis window.
- (optional) with “FDTD Debug” enabled, press “Export to JSON” to open and validate settings within FDTD (see “Section 7: Troubleshooting”)
- With “FDTD Debug” disabled, press “Export to JSON” to run the json export.
- The exported JSON DOE data will be saved to the …\Documents\Zemax\DLL\Diffractive\ folder, with the given json name plus the object number(s) appended.
The analysis settings are described below.
Object Number: the NSCE object#’s that will be analyzed/exported to json. This can be a single number, or a comma-separated list. Dashes are also allowed.
Example input: 2, 3, 5-8
Note: Multi-export is intended for exporting multiple zones of a single grating object. As such, all LSWM objects to be simultaneously exported must use the same FSP file, and have the same material substrate. If you need to export objects which use different FSP files or substrate materials, the tool will need to be run multiple times.
FSP File: the FSP file which is associated with the selected object#’s in the diffraction DLL settings.
Note: the chosen value should always match the FSP file chosen in the DLL parameters of the provided object#. The drop-down list
JSON File: The name of the JSON file describing the RCWA results for the DOE object to be exported. The object number will be appended to the file name (for example, exporting object#3, the name “rcwa_export.json” à “rcwa_export_3.json”).
nPositive: The material of the +Z side (in local object coords) of the DOE interface (also sometimes denoted “n-upper”). A value of “-” denotes air. The material fields will be automatically populated based on the selected object’s material settings. Note that only Model Glass and library materials are supported. In the case of Model glass, only the Index of Refraction field is currently considered.
nNegative: The material of the -Z side (in local object coords) of the DOE interface (also sometimes denoted “n-lower”). A value of “-” denotes air.
Swap: Inverts the selection of nNegative and nPositive.
Note: Due to the Zemax conventions, in the majority of cases, the non-air material will be on nPositive, with nNegative being air (“-”).
Note: It is helpful to enable Object Properties > Draw tab > ‘Draw Local Axis’, and then view the object in the NSC 3D Layout (the wireframe viewer) to see the orientation of the object’s local Z axis.
RCWA Excitation Settings (General Comments): This data describes the sampling used for the RCWA json export. There are three blocks here (theta, phi, wavelength); these settings determine sample points for the DOE plane-wave excitation. The RCWA analysis will be computed for each combination of excitation parameters. Subsequent ray-tracing using the JSON depends on interpolation of the excitation sampling.
For each wavelength, the material index of refraction is computed within Zemax and passed to FDTD. A monochromatic RCWA simulation is executed for each individual wavelength in sequence.
Testing is recommended to determine the required sampling granularity. As an example, a theta spacing of 1o, and phi spacing of 2o provides a reasonable balance between performance and accuracy.
RCWA Excitation Settings (theta settings): The theta angle represents the elevation angle of excitation, with zero being along the surface normal. Values should range from 0 to 90, with units of degrees.
Example: Min Theta = 0, Max Theta = 88, Num Theta = 9
àExcitation theta sample points (deg) = [0, 11, 22, 33, 44, 55, 66, 77, 88]
RCWA Excitation Settings (phi settings): The phi angle represents the incident azimuth angle for excitation; values should range from 0 to 360 degrees. The behavior of these settings mimics that of the theta angles.
RCWA Excitation Settings (wavelength settings):
Wavelength Mode: The user can choose between three methods of wavelength input.
- Uniform Sampling: the user specifies Minimum, Maximum, and step size to generate an evenly-spaced set of sample wavelengths. The behavior mimics that of theta/phi sampling.
- System Wavelengths: the wavelengths defined in the system explorer will be used as the excitation wavelengths; weights and primary wavelength are ignored.
- List: the user can specify a comma-separated list of values, in the Wavelengths (um) entry box. Units should be in microns.
FDTD Debug:
If this option is checked, and then “Export to JSON” is executed, the process will execute but terminate immediately before RCWA is actually run in FDTD.
This option is useful when validating settings or debugging. The FDTD window will remain open, so the user can manually check all the settings (object geometry, RCWA excitation settings, etc.) precisely as they will be used during the JSON export.
Note: this option terminates the execution mid-way through; a RCWA will not run, and a JSON file will not be generated. The FDTD window must be manually closed to resume normal Zemax operation.
Discussion
When the LSWM JSON Export tool is executed, the tool operates in two steps.
First, the user analysis retrieves the LSWM DLL settings for each of the specified objects from the Non-Sequential Component Editor. This includes the FSP file and other DLL inputs, as well as the material index of refraction for each wavelength specified. This data is stored in an intermediate JSON file (saved to …\Documents\Zemax\ZOS-API\User Analysis\LswmExport\), which can be useful as a debug/troubleshooting reference (see Section 7).
Next, the analysis launches the Lumerical FDTD application, and executes an LSF script. The script (exportLswmToJson.lsf) and dependencies are included in LSWM JSON Export Tool’s installation; they too will be stored in …\Documents\Zemax\ZOS-API\User Analysis\LswmExport\. These scripts instruct the FDTD application to:
- load the FSP file and apply the DOE parameters and RCWA settings, according to the data stored in the intermediate JSON
- execute a series of RCWA simulations based on the excitation settings stored in the intermediate JSON data
- export the RCWA results to the final LSWM JSON
While the data handoff from Zemax to Lumerical is handled by the compiled code, the actual implementation of the RCWA analysis and export is handled by the provided lumerical scripts. As such, customization in how the Zemax data is interpreted/applied to the FSP file is possible by customization of those scripts.
Troubleshooting
There are two primary troubleshooting features provided with the LSWM JSON Export tool.
Firstly, if an issue arises, the intermediate JSON file as discussed in the previous section should be reviewed. This file contains all data retrieved from the Zemax model and user settings which is being passed to Lumerical. This makes it a useful debug log for confirming if an issue is on the Zemax side, or the Lumerical side.
Secondly, the “FDTD Debug Mode” option in the analysis window settings enables validation of the Lumerical model. If this option is enabled when “Export to JSON” is executed, the analysis will run through the preparation of the RCWA analysis, but will pause before RCWA execution. The user can investigate the FDTD model and RCWA settings to validate the model settings match expectations and to identify any issues, particularly within the Lumerical Script Files.
Conclusion
This article provides a ZOS-API based user analysis which enables the conversion of dynamic-type LSWM models into static-type LSWM models, by automating the export of RCWA data to the LSWM JSON format.
For support or enhancement requests, please contact your Ansys Zemax support provider.