Dynamic workflow between Lumerical RCWA and Zemax OpticStudio

Updated: 2022-Nov-03

In this article, a dynamic workflow using Zemax OpticStudio and Lumerical RCWA for accurately simulating 1D/2D gratings in a whole optical system is introduced. The methodology will be first briefly introduced. Then details about how to set up the system will be explained.

Note: This feature is only available in Ansys Zemax OpticStudio Premium/Enterprise.

Authored By Michael Cheng


Article Attachments


Previously, OpticStudio has provided a 1D RCWA plugin for 1D grating simulation. In this article, a similar but much more powerful workflow based on a dynamic link from Zemax OpticStudio to Lumerical RCWA is introduced.
In this workflow, designers build the macroscopic optical system in Zemax OpticStudio and build the microstructure of the grating in Lumerical. The simulations in both software are seamlessly connected. During the raytracing process in Zemax OpticStudio, if a ray hits the grating, Lumerical RCWA will be automatically called for solving the field response and providing return data.
This workflow has several advantages:

  1. Complex 1D/2D gratings modeling: With a powerful geometry editor, users can easily build and simulate arbitrary 1D or 2D gratings.
  2. Fast prototyping: The parameters in Lumerical are exposed in OpticStudio. Any change made in OpticStudio can automatically trigger Lumerical to calculate updated data for new grating shapes and return the new data. There is no need to import and export the data.
  3. Optimization: Users can easily define their customized parameterized model in Lumerical and optimize the grating shape considering the whole system performance.
  4. Import & Export grating shape: The workflow supports standard import and export grating geometry in file formats of STEP, STL, and GDS II.

System requirements

To use this dynamic workflow, both Zemax OpticStudio and Lumerical need to be installed on the same PC with Windows as the operating system. Zemax OpticStudio must be in version of Ansys Zemax OpticStudio Premium or Ansys Zemax OpticStudio Enterprise. Both Lease and Paid-Up Ansys Zemax license are valid to use this tool. Lumerical must have a license for FDTD.

Static vs. dynamic workflows

It may be worth mentioning that there are two existing workflows to exchange data between Lumerical and OpticStudio. One is the dynamic workflow that we are going to introduce in this article. Another is the static workflow that works in a different way. The two workflows have different flexibilities, and no one is superior to the other. Users should consider which one to use based on their design case.


Preparing the grating file in Lumerical

The grating geometry at each periodic box needs to be defined in a Lumerical .fsp file. In the dynamic workflow, OpticStudio would automatically call Lumerical fsp file, applying the parameters sent by OpticStudio, and then calculate the electric field response.

Several .fsp files simple grating geometries are provided in the attachments of this article, as shown below.

Users can also customize their own parametric models if they follow the rules below.


A structure “topcell” must be defined in the .fsp file.


User properties in topcell

In the topcell settings, we must define five user properties as below red-boxed. These user properties should be used in the script, which we will explain later. The meaning of these user properties are as below.

period_x, period_y: Periods in x and y directions

n_neg, n_pos: Indexes of substrate (n_neg) and superstrate (n_pos)

tag: This is a string that is only used by the dynamic link.


Script in topcell

We must define some scripts in the topcell as shown below.


First, the script should define two “rectangle” objects for substrate and superstrate. They should be centered at (x=0,y=0) and be larger than period_x and period_y in x and y directions. They should be just at the top (+z) and bottom (-z) of the grating structure as the “simulation region” in the following picture. Also, the script must set the refractive index of the superstrate and substrate with the variables n_pos and n_neg. Finally the thickness (size in z) of the two objects must be larger than 200 nm.

Second, the script must make sure to generate the complete geometry in the range x = -period_x/2 ~ period_x/2 and y = -period_y/2 ~ period_y/2. Note this sometimes means we need to repeat the same structure twice or more times in order to have a full geometry in the periodic range.


Third, the script must define the layers to be used by RCWA solver as shown in line 85 in the following picture. At the final line of the script, we must write out the as the line 86 in the following picture.


Finally, optionally, users can define more user properties which is used by scripts to dynamically change the grating geometry based on the corresponding values. As shown below is an example we also provided in the attachments. Note these parameters must be defined in the format of p#_****, where # is an integer and **** is any name for the user property.


Set up the gratings in Zemax OpticStudio

In OpticStudio, to set up a grating, it’s suggested to use one of the following 3 objects: Diffraction Grating, User Defined Object (DiffractionGrating.DLL), and User Defined Object (Polygon_grating.DLL). The Polygon_grating.DLL file is not provided in the installation folder by default, but it can be found in the article How to simulate exit pupil expander (EPE) with diffractive optics for augmented reality (AR) system in OpticStudio: part 4.

Note the grating is at Face 1 for these suggested objects.


After adding one of the above 3 objects, we then use the Object Properties…Diffraction tab to define the plugin DLL “Lumerical_RCWA_dynamic_link.dll” for the added diffraction object. This DLL creates the link to Lumerical, and you will see it includes several parameters that we are going to explain in the next section.


Parameters in Zemax OpticStudio

Shown below is a table describing all the parameters this DLL provides:

Parameter name



File Name

Shows all the files with .fsp as extension in the folder “\Zemax\DLL\Diffractive\”.


+Period/-Freq X (µm), +Period/-Freq Y (µm)

The period of the grating in x and y directions.


Max Order X

Max Order Y

The number of diffraction order (harmonics) to be considered in the RCWA solver.

A rule of thumb:


Link Lumerical

When this parameter is 0, the DLL will not link to Lumerical. More details later.



These are dynamically linked to the parameters defined in grating file (.fsp)


# Layer

This specifies the number of layers to sample for the grating geometry.


Rotate Grating

This allows users to rotate the grating’s periodic direction.




Set it to 1

Error Log

Setting this to 1 enables the plugin to export log data.


Order Filter #

This allows users to control which order of diffraction rays will be traced.


Stochastic Mode

Setting this to 1 means rays don’t split at the grating. Instead, it diffracts a single input ray into one output order through probability.

Use it when the ray splits too many times in the system

Interp. Pre-sampling

This controls how many incident angles the plugin should request at each call.

No more than 10

Start Order X, Y and Stop Order X, Y

The DLL will only consider diffraction orders in the range between -Max Order ~ +Max Order. The value should be large enough to include all orders of interest. However, note it’s not meaningful to have the range of X/Y Start/Stop Order to be outside of the range defined by -Max Order X/Y ~ +Max Order X/Y. If users set it so, OpticStudio will try to ask the DLL for data with higher order than Max Order but then the DLL will simply return no power for the output rays.

File Name

This specifies which file to read for the grating geometry. Note the file must be put in the specified folder “\Zemax\DLL\Diffractive\” to be shown in the list.


+Period/-Freq X/Y (µm)

The period of the grating in x and y directions in microns. It it’s negative value then it’s interpreted by the DLL as frequency where the unit is (1/µm).

Max Order X, Y

This specifies how many harmonics (orders) are considered in the RCWA solver. When both X, Y are >= 0, Max Order Y is ignored and a circular area in harmonic space (diffraction order) is sampled, as shown below in the left-side image. When X < 0 or Y < 0, rectangular area is sampled in harmonic space. The half width in x and y directions of the rectangular area are the absolute value of Max Order X and Y, as shown below in the right-side image.


Link Lumerical

If this parameter is 0, OpticStudio will stop accessing Lumerical for ray trace data.

  • Rays will stop at the grating.
  • User defined parameter name will not show in the UI.

If this parameter is any number other than 0, OpticStudio will perform the call to Lumerical.

This is useful when users are setting up the system, as they can temporarily stop the link to Lumerical and avoid delays in the user interface caused by the dynamic link.


p1 ~ p20

These are parameters that will map to the user properties in Lumerical .fsp file. When we change the value of these parameters, the corresponding user properties will be automatically updated in the Lumerical file.


Order Filter File#

This parameter allows users to define which order to be considered during raytracing. Physically, when a ray hits the grating, all possible diffraction rays should launch. However, sometimes we may want only some orders to be launched for efficiency.

When this parameter is set to a positive integer, it will read the predefined text file in the folder “\Zemax\DLL\Diffractive\”. For example, if it’s set to 8, then the DLL searches for filter_8.txt.

The format of the text file is as below

* First line must be an odd number n.

* The next are two n x n blocks for reflection and transmission orders.

* 1 = allowed, 0 = not allowed.

* If the file number is negative, it means always re-read the filter file. Otherwise, the filter data is read and aved in RAM for further access.


# Layer

RCWA considers the structure in slices (layers)! The more layers you consider, the more accurate the result is, but the slower the calculation speed is. When # Layers is 0, it uses the default setting in the .fsp file (defined by layers as explained in previous pages). When # Layer is a positive integer, it re-samples the structure with equal distance layers.


Rotate Grating

This is useful if users want to change the rotation of the grating but not the aperture shape of the grating.


Interpolation & Interp. Pre-sampling

For efficiency, OpticStudio caches calculated data in memory. It doesn’t call Lumerical to calculate for the same data at the same incident angles.

Setting Interpolation = 1 ~20 turns this feature on with 201x201 sampling in direction cosine x and y space for the incident angle. Setting this to a number larger than 21 also turns on the interpolation feature but can control the sampling resolution at the same time.

Interp. Pre-sampling controls the radius of the sampling circle as shown below. This can be useful because the RCWA solver take shorter time to calculate if we call data for many incident angles at once instead of calling it frequently. This is most effective around 5~10.


Stochastic mode

If this is set to non-zero, rays don’t split when hitting the surface. Instead, the ray will be randomly diffracted into one order, as shown below. This is useful when one ray will hit the diffractive surface multiple times and split into too many segments.


Error Log

If this is set to 1, the DLL will export a log file in the folder “Zemax\DLL\Diffractive\” as shown below. This is useful when seeing any geometric error coming from the Lumerical Dynamic Link DLL.



Tips and cautions

Update: None

It’s suggested to set “Update: None” in the non-sequential editor. This can avoid crashing during parameter changes.


Lumerical FDTD window

When using this workflow, the Lumerical FDTD window is always automatically opened. Make sure you don’t accidentally close it. This will cause the program to crash.

Use same .fsp file

It is most effective to use the same .fsp file for multiple grating objects when the grating is of a similar structure. This is demonstrated in the system shown below in the upper picture. This is true even if all these grating objects have different parameters in the Object Properties…Diffraction tab. Do not duplicate the .fsp files and apply different .fsp files to different grating objects. The plugin creates a calculation cache for each of the .fsp files. If we duplicate the .fsp multiple times, then the plugin will not know they are the same source .fsp and cannot organize the data in the most efficient way.



If you optimize using OpticStudio’s optimizer, you must first run local optimization once and then use Hammer for global optimization. Also, it’s suggested to use Orthogonal Descent instead of DLS.



As a start, users can try the attached example. When opening the zar file, the corresponding fsp file used by this system will be automatically extracted in the folder “\Zemax\DLL\Diffractive\”.

Open the attached “SIMPLE_CASE_for_KBA.zar” in OpticStudio. Then, go to the object’s Diffraction property settings. Change the Link Lumerical parameter to a non-zero value and update the 3D Layout in the system.


We should see the Lumerical FDTD window is automatically opened, and the 3D Layout will look like below:


If we trace rays, we can see the result in the detector is as below:




Was this article helpful?
1 out of 1 found this helpful



Article is closed for comments.