Dynamic workflow between Lumerical RCWA and Zemax OpticStudio

Updated: 2023-Jan-30

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 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's 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 edition must be Ansys Zemax OpticStudio Premium or Ansys Zemax OpticStudio Enterprise. 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 2023 R1.0 or later.

Please see the section “Legacy versions of DLLs”, at the end of the article, to find more information if you have used any old version of DLL built in 2022.

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 which 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, apply the parameters sent by OpticStudio, and then calculate the electric field response. The length of the fsp name is recommended to be less than 50.

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 group called “topcell” must be defined in the .fsp file.


Structure group is a type of object groups in Lumerical. A quick explanation is that structure group can be considered as a composite object that is built by many basic structures, such like Polygon and Rectangle. When two structures overlap, the priority is determined by the mesh order or the object. More information can be found in Lumerical knowledge base.

Structure Groups - Simulation object

Understanding mesh order for overlapping objects

In structure group in Lumerical, we can define “Properties” and “Script”. The properties are like the parameters of an object. We can write the script so it will read the property values and update the basic structures in the group. The script is quite flexible where it can even add/delete structures inside. This makes the structure group itself like a new object that you set up its shape, material via the Properties.



Structures in topcell

In the topcell group, in addition to the grating structures, we must define two Rectangle objects to represent the materials at positive and negative sides. They should be centered at (x=0,y=0) and their x and y sizes should be larger than period_x and period_y. They should be at the top (+z) and bottom (-z) outside of the “simulation region” as shown in the following picture.

The name of the two Rectangle objects can be arbitrary. To make is each to read and neutral, in our provided examples, we use “negative_z_material” and “positive_z_material”.


Properties of the topcell

We must define 4 user properties as below red-boxed. These user properties will be set up by the dynamic link. And in the script, we will read their values to modify the structures in the group. The 4 properties to use 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)


There could be more properties. If we make their name with the form p#_***, note # is number and *** is any string, then these parameters will be read by the dynamic link and shown in the OpticStudio UI.


Script of the topcell

We can define scripts in the topcell as shown below.


Defining scripts is not optional, there are some required scripts we must write. We suggest users open the sample file provided by this article and use the script as a template.

Here are required scripts:

  • We must set the refractive index of the positive_z_material and negative_z_material with the variables n_pos and n_neg.
  • If the grating’s size in z direction changes, which means the simulation zone changes, we also need to modify the position of positive_z_material and negative_z_material. The thickness (size in z) of the two objects must be larger than 200 nm.
  • The script must make sure to generate the complete geometry of the grating 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.
  • 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.
  • image9.pngimage10.png

RCWA Region

The final requirement to this fsp file is a RCWA region must be defined. This can be added by clicking “Simulation > Add RCWA”.


The only settings users must carefully check is the interfaces. The settings of the RCWA can be accessed by right-clicking on the object and selecting Edit object.


Before editing the interfaces, make sure you have turned on the mesh view of the simulation region.


There are two ways to set up interfaces. Users can directly define the absolute positions, but this means the highest and lowest position of the grating cannot change. The other way is to use reference positions. In this way, when you edit the parameters of the gratings from the OpticStudio UI, the interface position will automatically update when the grating shape changes.



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

0: No connection to Lumercial, and the Lumerical window does not be opened

99: Connect to Lumercial, and the Lumerical window will be opened automatically

Any number other than 0 and 99: Connect to Lumercial, but the Lumerical window does not be opened



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


# Layer



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

Fast 2D out-coupler

This parameter is designed to speed up the calculation for 2D out-coupler used in AR waveguide.



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 and 99, OpticStudio will perform the call to Lumerical and the Lumerical window will not be opened.

If this parameter is 99, OpticStudio will perform the call to Lumerical and the Lumerical window will be opened.

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

This parameter is deprecated. The number of layers should be set up in in the RCWA object tin the .fsp file.

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 turns this feature on.

Interp. Pre-sampling tell the dynamic link to get more calculation data from Lumerical at each of the call. There is no a standard answer to how large this should be. This is usually most useful around 5~10, but some experiment is needed to understand which value is more adequate for each of the different system.


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.


Fast 2D out-coupler

When this parameter is set to non-zero, it assumes a hexagonal grating. When a ray hit the grating in an orange region in the k-space as shown below, it will try to calculate data in all related orange regions.



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.


How the grating is located on the object

This section is supposed to help if you have questions similar to below when setting up the grating in the system.

“Where is substrate/superstrate?”

“Why are the index at two sides exchanged after tracing rays?”

To correctly set up the grating in the system, there are a few important points:

  1. The grating is located on the Face 1 of object.
  2. Both Lumerical and Zemax OpticStudio object have their own coordinates which are linked.
  3. The materials at -z and +z infinite half space are automatically determined by OpticStudio.
  4. The substrate can be at -z or +z side.

The first concept is that grating is always on the Face 1. Although, there could be exceptions, the grating is normally on the Face 1. If needed, we can check Help File to know the definition for any specific object. Note a “face” is basically a thin surface with no volume. The grating is assumed to be a surface property in our simulation.


The second concept is about coordinates in OpticStudio and Lumerical.

We can check coordinate of an object in OpticStudio by checking the “Draw Local Axis” in Object Property > Draw section, as shown below.


On the other hand, Lumerical FDTD also has a coordinate system. The coordinate system in Lumerical should exactly match to the object coordinate in Zemax OpticStudio, as shown below. The two coordinates in Lumerical and on OpticStudio object are same.


Another important thing to mention is that the refractive indexes at two sides (n_neg and n_pos) of the grating are automatically set up by the dynamic link plugin based on the object settings in the OpticStudio. As shown in the following picture, the value of n_neg and n_pos are different with different system set-up.

Note the following picture also shows how the coordinate systems between Lumerical and OpticStudio should really match. Also, although the coordinate below only shows x and z axes, this rule actually works to fully x,y,z all axes. It’s important to always check if the coordinate system in Lumerical and OpticStudio match to what the designer expected.


In the example .fsp files attached in the article, the index of n_pos will be assigned to the rectangle object “positive_z_material” in Lumerical and the index of n_neg will be assigned to “negative_z_material”, by the Lumerical script defined in the structure group “topcell”.


In above, when we say the index of grating of object or other object in OpticStudio, we mean whatever users assign in the column “Material” as shown below. If the n_neg or n_pos are from any object, then it’s from the environment default, which is 1.0.



Legacy versions of DLLs

For users who have used this dynamic link in 2022, it’s important to check whether the versions of the Lumerical and the DLL match. As shown below, the DLL Lumerical_RCWA_dynamic_link.dll, published in OpticStudio 2022 R2.02, only works with Lumerical 2022 R2.3/R2.4. On the other hand, the DLL lumierical-sub-wavelength-dynamic-link-2023R1.dll works with Lumerical 2023 R1.

It’s suggested to always make sure the version of the DLL match to the Lumerical version for the best stability and accuracy.


The following is a table showing the difference between the two versions of DLLs for readers’ reference.




.fsp structure


No “tag” parameter

Must add “RCWA” object

Be careful with correct interface setting

(optional) use neutral names for material at two sides

Lumerical version

2022 R2.3 & R2.4

2023 R1 and later

Lumerical window

Always show

Can show or hide



Add “Fast 2D out-coupler” for AR waveguide application

OpticStudio installer

Comes with 2022 R2.02 and later version

Comes with 2023 R1 and later version



Here are some steps that users can check if seeing any problems.

  1. Check software edition: Lumerical much be 2023 R1.0 or higher. OpticStudio must use Ansys license with Premium or Enterprise edition.
  2. Make sure the parameter Link Lumerical is set to 1, which makes DLL linking to Lumerical.
  3. Sometimes if Lumerical cannot access license, the DLL will not work. Users can simply open a Lumerical FDTD license to make sure Lumerical can get license correctly.
  4. Set the parameter “Error Log” to 1 and the DLL will export error to \Document\Zemax\DLL\Diffractive\lumerical-sub-wavelength-dynamic-link.log
  5. Set the Link Lumerical to 99 can trigger a Lumerical window to open. This is useful to check what happen when the dynamic link editing the grating.
  6. If one .fsp file can't be selected in UI, please check the length of the file name and make it less than 56.


Open the attached “Demo_simple_grating_test.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.


The Lumerical FDTD window is automatically linked, and the 3D Layout will look like the below:


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



From here, users can try to use other grating files and modify the user parameters to see how the geometry is automatically changed.


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



Article is closed for comments.