Dynamic workflow between Lumerical RCWA and Zemax OpticStudio

Also available in 日本語

Updated: 2026-April-21

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, Yihua Hsiao

download example (.zip)

1. Introduction

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.
5. Spatial variation: Users can define how the grating parameters vary at different places on the grating.

1.1 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.

2. 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.

3. Lumerical: prepare the grating files (.fsp)

In attached file, 6 simple gratings file are provided. Users can save these files in \Zemax\DLL\Diffractive\ in order to read them. The following table explains each of files.

3.1 Tips

• For hexagonal 2D gratings, when setting up systems, users need to manually make sure period_y = sqrt(3) * period_x so it's a hexagonal lattice.
• For index parameter, such like "p4_slab_index", if it's 0, it's using the value of n_pos. If it's -1, it's using the value of n_neg. This is achieved by writing the script in the Lumerical file to control it.

If these 6 shapes don't meet users' requirements, users can follow the appendix to customize their own gratings.

4. Zemax OpticStudio (set up system)

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.

The following objects are basically supported, but detailed verification has not been conducted, and there is a possibility of failure in specific situations.
Binary 1
Binary 2
Binary 2A
Hologram lens
Lenslet Array 1
Toroidal Hologram

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” （or "Lumerical_sub_wavelength_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.

4.1 Parameters in Zemax OpticStudio

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

4.1.1 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.

4.1.2 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.

4.1.3 +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).

Be careful that, when lattice vector angle is not 90 degree, the period x and y are defined as below.

If it's a 1D grating, for example periodic in X direction, the period y can be arbitrary but not zero.

4.1.4 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.

If it's a 1D grating, for example periodic in X direction, the Max Order Y is highly suggested to be zero and the Max Order X should be negative. This makes the simulation most efficient.

4.1.5 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.

4.1.6 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.

4.1.7 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.

* Note: there cannot be spaces or comma between numbers in each of line. And there cannot be empty lines between two non-empty lines in each of the Reflect and Transmit blocks.

4.1.8 # Layer

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

4.1.9 Rotate Grating

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

4.1.10 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.

• When it's negative, it's same as positive value, but the power-conversed interpolation will be used.
• When it's 0 or 1, it's set to 201.
• When it's larger than 1 be smaller than 51, it's set to 51.
• When it's larger than 51, users can customize the sampling rate. For example, if it's set to 101, than the sampling array is 101 x 101.

Interp. Pre-sampling tell the dynamic link to get more calculation data from Lumerical at each of the call. As shown in the figure below, a Pre-sampling=0 only considers the 4 neighboring points, while a value larger than 0 considers more points. 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.

4.1.11 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.

The probability will be calculated only for Start Order when Stochastic mode is on. However, OpticStudio will still call the DLL for every order defined. Therefore, it is recommended to set Start Order=Stop Order when Stochastic mode is on . (e.g. Start Order=Stop Order=0 or Start Order=Stop Order=1). This ensures that the DLL is only accessed once, avoiding unnecessary time consumed for function call

4.1.12 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.

4.1.13 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.

4.1.14 Has metal in grating

When there is any material with non-zero imaginary index in the grating, this parameter should be set to 1. If it's not set to 1, the DLL will check power conversation, decide the calculation is wrong, and stop returning ray data.

4.1.15 Lattice vector angle

This value describes the angle, in degrees, between two lattice vectors. For any 2D grating, we can always find the 2 lattice vectors.

If this value is set to 0, it's internally considered as 90 degrees. This promises backward compatibility for the .fsp files created before this parameter is added to the DLL.

4.1.16 Spatial variation parameters

The spatial variation feature is available starting in 2026R1.1. It can be enabled by setting the parameter "Spatial Vary File#" to a positive integer. The plugin will load a spatial_vary_#.txt from \Document\Zemax\DLL\Diffractive\, where # is the positive integer at parameter "Spatial Vary File#". Users need to define the equation how the parameters vary and the boundaries in the spatial_vary_#.txt file. 

Note: This file will only be loaded once. If the user edited the file after the file is loaded, the change will not be reflected.

4.1.16.1 Format of input file spatial_vary_#.txt

In a spatial_vary_#.txt file, any line beginning with the # symbol is ignored, and all whitespace is skipped.

Users may define equations such as p# = v0 * (1 + y/150 + v1), where p# is the parameter to be spatially varied. The variables v0, v1, v2, … correspond to values defined in the DLL plugin UI and may be adjusted manually or during optimization. The variables x and y represent the local coordinates of the object where the DLL plugin is applied. In addition to basic arithmetic operators (+, -, *, /), the parser supports trigonometric functions (sin, cos, tan, asin, acos, atan), advanced functions (log, log10, sqrt, abs), and the constants \(\pi\) (pi) and \(e\) (e) .

Spatial Vary Mode = 0 – Sampling in XY Space

When Spatial Vary Mode is set to 0, the DLL plugin samples data in the x–y positional space.

The spatial_vary_#.txt file must contain a line formatted as:

xmin, xmax, xinterval, ymin, ymax, yinterval

Here, xmin/xmax and ymin/ymax define the spatial boundaries (in millimeters), and xinterval and yinterval define the sampling intervals.

If a ray intersects the grating outside these boundaries, the ray stops with error. If a ray intersects within the boundaries, RCWA is evaluated only at the discrete grid points defined by the six values above.

The interpolation parameter Spatial Vary Interp affects sampling as follows:

• If Spatial Vary Interp = 0, RCWA data at the nearest sampled grid point is used.
• If Spatial Vary Interp ≠ 0, RCWA data is interpolated using the nearest four grid points.

Spatial Vary Mode = 1 – Sampling in Parameter Space

When Spatial Vary Mode is set to 1, the DLL plugin samples data in parameter space.

Each equation in the spatial_vary_#.txt file must be followed by:

; min, max, interval

These values specify the lower bound, upper bound, and sampling interval for that parameter.

Example:

p# = v0*(1 + y/150 + v1); -10, 10, 2.5

When a ray hits the grating, the parameter values at the intersection point are first computed using the defined equations. If a parameter falls outside its defined range, the ray stops with an error. Otherwise, RCWA is evaluated only at the parameter-space samples defined by the min, max, and interval values.

The interpolation parameter Spatial Vary Interp affects sampling as follows:

• If Spatial Vary Interp = 0, the nearest parameter-space sample is used.

• If Spatial Vary Interp ≠ 0, linear interpolation is performed across the nearest parameter samples. 

  Example
  
  1 varying parameter → 2 points
  2 varying parameters → 4 points
  3 varying parameters → 8 points

Note: Because the number of sampling points increases exponentially with the number of spatially varying parameters, users are suggested to use Spatial Vary Mode 0 when many parameters vary spatially to avoid excessive computation.

5. Tips and cautions

5.1 Update: None

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

5.2 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 or hang.

5.3 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.

5.4 Optimization in Zemax OpticStudio

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.

5.5 Optimization in optiSLang

The following 2 articles show optimization examples using optiSLang.

Optimization of Exit Pupil Expander with 2D out-coupler – Knowledgebase (zemax.com)

Optimization of an Exit Pupil Expander with 1D gratings – Ansys Optics

5.6 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.

The following picture explains more how Lumerical and Zemax OpticStudio are linked in terms of the structure. In OpticStudio, the grating is only a surface (Face 1) with no volume. When a ray hit this surface, Lumerical is called to calculate the physics and return.

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.

5.7 How dynamic link load settings from OpticStudio to Lumerical

Here is a process how the dynamic link load the settings in OpticStudio UI and write in Lumerical for user's reference.

1. Copy "period_x", "period_y", "p#_****" from the DLL UI in OpticStudio to the properties with same name in structure "topcell" in Lumerical.
2. Set up topcell's properties "n_neg" and "n_pos" in Lumerical based on the refractive index at the two sides of the grating face in OpticStudio.
3. Set up the size of RCWA object. The x, y positions are always at (0,0). The x, y spans are set to the period x, y based on the OpticStudio's UI settings. The z min and max are automatically set based on the minimum and maximum interface position, extended by 100 nm outward. For example, if the smallest and largest interface position is -1.0 µm and 5.0 µm, then the z min and z max of the RCWA object is changed to -1.1 µm and 5.1 µm.
4. The "propagation direciton" setting in the RCWA object > General is set up based on the requested ray's information in OpticStudio.
5. Set up the RCWA object > Excitation based on the on the requested ray's information in OpticStudio. The "incident angle" is set to "table". The requested theta and phi's are set based on the interpolation method from the dynamic link DLLs. The "sample spacing" is set to "custom". The "custom frequency samples" is set to the incident ray's wavelength in OpticStudio.
6. Set up the RCWA object > Solver. The "k vectors domain" and "max number k vectors"/"max number ku/kv" are set up based on the parameter "Max Order X/Y" in the OpticStudio UI.
7. In RCWA object > Results, the "report field amplitudes" is set to checked.

5.8 Simulation speed too slow

Check here for some general tips to speed up your simulation. Since different system can have different hurdles, it's very likely many of these suggestions will not work for whoever is looking at this section. However, even you just fixed one point, often that can already give you some visible improvements. Hope this section is useful for anyone who is trying this solution.

1. In RCWA, note you only need to set more layers when the structure changes its shape. For example, if you have a pyramid, you may want to take more layers for better sampling the structure changes in z direction. However, if you have a cylinder or any polygon shaped pillar, you only need to set up two layers at the top and bottom of the pillar. The more layers in between won't help at all.
   • Similarly, it may be worth to use fewer layers even for those regions where the structure varies in z direction, at least for initial design stage. Users can do a convergence test by increase layers and observe the simulation result change to understand adequate number of layers.
2. In RCWA, if you have high index in your structure and you have to use very large order number for convergence, check the tangential vector field, which is a feature designed to let you converge with fewer order used.
3. If your grating is going to be hit by a large range of incident angle of rays, you should set non-zero Interp. Pre-Sampling. See above sections for explanations of this parameter.
4. Sometimes we might be only interested in simulating some specific diffraction orders. In this case, we can use Order Filter settings to only diffract these orders during simulation.
5. If we are going to consider more than 3 or 4 orders at the same time for a grating, it means every 1 ray hitting the grating will split into many rays. If these rays further hit other grating with similar settings, the number of rays will grow very fast and soon the simulation becomes impossible. In this case, we need to use Stochastic mode.
6. If you use Stochastic mode, be careful you have set X/Y Start/Stop all to zero. Other settings will only make the simulation slower. See above sections about explanations of this parameter.
7. It's not very suggested, but it's possible users can use lower sampling rate for Interpolation. For example, we can set Interpolation to 100 during simulation. See the more explanations in above sections for this parameter.
8. If the grating is 1 dimensional, the simulation region for the RCWA setting can be 2D. This should also be faster. However, note tangential vector field doesn't work in this case. If the grating includes high index material or even metal, high Max Order is needed.
   
9. If you simulate AR waveguides,
   1. Try to use as small X/Y Start/Stop Order as possible initially. For example, for a in-coupler grating, you probably only need 0th and +-1st order in X or Y direction.
   2. At initial stage, check system only with collimated beam, grating by grating. If you right-click on the object in editor, you can select "Ignore and Hide Object" to temporarily turn of the second and third grating. After you are sure grating 1 is OK, continue to 2nd and then 3rd grating.
   3. When you use a non-zero field of view input, which means there are a large range of incident angle of rays hitting the grating, remember you should set up non-zero integer in Interp. Pre-Sampling. Typically, we need to test to find out the best value, but it's typically about 5~15. See the above sections for more explanation of this parameter.
      1. Note if the input beam is collimated, you should only use 0 or 1 for pre-sampling.
   4. Consider Stochastic mode. In many cases, Stochastic mode is actually much better. This is especially true when one ray can split into too many segments, which happens when the waveguide is thin or when the grating area is large.
      1. Note you can use Diffractive DLL Setup Assistant to quick set for all gratings.
   5. If we have a 2D grating in the waveguide, users are suggested to set Fast 2D coupler to 1 to speed up simulation of this 2D grating.
   6. If the goal is to optimize, you should consider using collimated beam. See Optimization of Exit Pupil Expander with 2D out-coupler for more details about optimization settings.

6. Troubleshooting

6.0 Did you customized your .fsp grating?

Wrong setting in customized .fsp file is the most frequent seen reason in user questions. If you have customized your .fsp file, it's highly suggested to read the appendix and carefully check if anything is missed. For example, the common reasons of failure are as below.

1. In the topcell script, there is no lines to specify n_neg and n_pos as index for the negative_z_material and positive_z_material. Note this is the No. 1 problem in user questions. What usually happens is users ignores the following scripts and make the index of the two objects fixed. It's highly suggested not to ignore this settings.
   
2. In the topcell script, the period_x and period_y are not adequately considered when constructing geometry of the grating.
3. The topcell cannot well generate the geometry with some parameters input.

6.1 First check the following points

1. Make sure the version of the DLL and Lumerical are matched. See the section "DLL version vs. Lumerical version" in below.
2. Check the list of known and solved bugs in this community post: Zemax - Lumerical RCWA dynamic linking updates
3. Check software edition and license type: Lumerical must has a FDTD license. OpticStudio must use Ansys license forPremium or Enterprise edition.
4. Make sure the parameter "Link Lumerical" is set to 1 or 99, which makes DLL linking to Lumerical.
5. If setting "Link Lumerical" to 1 doesn't work, restart OpticStudio, set the "Link Lumerical" to 99, and see if a Lumerical window is opened. This is useful to check what happen when the dynamic link editing the grating.
6. Set the parameter “Error Log” to 1 and the DLL will export error to \Document\Zemax\DLL\Diffractive\lumerical-sub-wavelength-dynamic-link.log
7. The filename of the .fsp file cannot be longer than 56 characters.
8. The filename of the .fsp file cannot include spaces. (This is a bug which can be fixed in the future.)
9. If simulation result is not accurate, check whether the mesh number in the Lumercial UI is many enough. See the above explanation about interfaces in the section "RCWA region" for the mesh in z direction, and the section "How to change x/y mesh " for the x and y directions.
   
10. In order to get the converged result, the 'Max order' setting in the OpticStudio dynamic link DLL UI should be large enough. Note the higher these 2 numbers are, the accurate the result is, but the longer the simulation time will also be. See the section "Max Order X, Y" above for more details.
11. The mesh refinement in RCWA solver settings is suggested to be “Conformal Variant 0”. If it’s metal,  “Conformal Variant 1” is suggested.
    
12. If "interfaces reference position" is used and there are two interface overlap, users need to be careful about the "type", which should be either "MAX" or "MIN". Selecting the wrong reference interface may cause nothing drawn as shown in the right side of the following picture. More details about interface settings can be found in RCWA Solver - Simulation Object – Ansys Optics.
    
13. If you use parameter "Rotate Grating", be careful it rotates the grating in direction of "from x- to y-axis". If the grating object is rotated by 180 degree by TiltX or TiltY. This direction might seems opposite.
14. Do you customize your grating file (.fsp)? If so, it's suggested to set the parameter "Link Lumerical" to 99 to show the Lumerical window. See the following section "Check gratings in Lumerical during linking" for some points you could check.

6.2 DLL version vs. Lumerical version

The following table shows the relationship between the versions of the DLL and Lumerical. Most of them are neither forward compatibility nor backward compatibility. 

The version of the Lumerical can be found in the title of the software as shown below.

The version of the DLL is directly in the file name. Users can clearly know which DLL is used when looking at the UI. The version of OpticStudio itself is not critical. However, to get latest version of the DLL, users need to download and install the latest OpticStudio. For example, to get "lumerical-sub-wavelength-dynamic-link-2023R1-2.dll", users need to download and install Ansys Zemax OpticStudio 2023 R1.02 from support.ansys.com or www.zemax.com.

6.3 Check gratings in Lumerical during linking

Here is some steps that users could follow to check when the system doesn't work as expected.

1. When turn on the link, set "Link Lumerical" to 99 so Lumerical window shows and we can check the system.
   
2. Check whether the geometry in the Lumerical window matches expectation following your setting to the parameter. Especially we need to check if negative_z_material and positive_z_material covers the RCWA region's top and bottom sides as described in Appendix - Customize your gratings.
3. If objects overlap and is hard to check, you can right-click on the object, select "Edit object" and set the transparency in "Graphical redering" tab.
   
   
   
4. We can also check whether the refractive index matches expectation in "Material" tab. Especially, we should check index settings for negative_z_material and positive_z_material. See the section "How the grating is located on the object" to have an idea how the index is supposed to be.
   
   
5. Trace at least one rays through the grating surface (Face 1 on the diffractive object) which will trigger the calculation in Lumerical. Note "Split NSC Rays" should be turned on during the raytracing. A trick is this can be done by simply setting a source object with Layout Ray = 1 and updating the Layout.
6. Go to Lumerical, select "RCWA" object, right-click "substrate" in the result view and select "Send to script".
   
7. In the command window, we can check how the RCWA solver actually consider the refractive index at the two sides of the grating. The n_lower should be exactly same as the index of negative_z_material and n_upper should be exactly same as the index of positive_z_material.
   

6.4 The n_neg and n_pos data in topcell seems incorrect

There can be many reason this data seems incorrect. One common reason is because the value is updated from UI change not raytracing. In 2023R2 version and later version, the dynamic link will also update the grating parameter Lumerical in addition to raytracing event. However, when the parameter is updated from UI change in OpticStudio not raytracing, the n_neg and n_pos will be some default value but not real data from the system setting. For the 2023R2 and 2024R1 value, this default value is 1.0. In the 2024R1-2 version and later, this value will be 99 as shown below.

6.5 Cannot read/find .fsp or .dll

When loading the dynamic link DLL into OpticStudio or when the dynamic link DLL try to load the .fsp file, they will look up for the Zemax folder in following two places in order. It's suggested users to check the following two places before contacting Zemax support.

1. Look up "Computer\HKEY_CURRENT_USER\Software\Zemax\Zemax Root" in Registry Editor.
   
2. In File Explorer, search for "%userprofile%\Documents" as below and press enter. If the above path is empty, then the dynamic link will try to look for this path.
   

It's also worth to mention that, if the username in Windows is non-English, the dynamic link may also has issue to find the .fsp file.

6.6 Computation results of Zemax in-house RCWA and the dynamic link with Lumerical

If you want to compare the computation results Zemax in-house RCWA and the dynamic link with Lumerical, please consider the following points:

1. Make sure the grating structures are the same. Often it could be the geometries in Zemax and Lumerical RCWAs is different.
2. Check the tangential vector field option in Lumerical, since Zemax in-house RCWA always considers this option.
3. Increase the mesh number in Lumerical. Due to algorithm differences, Zemax in-house RCWA doesn't need mesh-related setting. If Lumerical has too few mesh cells, it may lead to inaccurate calculations. Note by default these options are hided and users need to set "mesh type" to custom in order to show them.

6.7 Do not manually close Lumerical windows

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 or hang.

6.7 Is there any material with non-zero imaginary index

Usually this happens when the grating includes some metal. In this case, users need to set the parameter "Has metal in grating" to 1. Otherwise, the simulation stops and no rays are diffracted.

6.8 Minor points to check

6.8.1 Mesh refinement can only be conformal variant when Tangential Vector Field is used.

7. Tool to assist setting up complicated system

In attached download file, users can find a small tool to help users setting up DLL parameters in a more convenient way. This is mainly useful when we need to set up multiple objects and parameters. Please save the Diffractive_DLL_Setup_Assistant.exe to Documents\Zemax\ZOS-API\Extensions folder, and open this tool from the OpticStudio UI (Programming > User Extensions > Diffractive_DLL_Setup_Assistant.exe).

Here is a quick user guide about the tool.

1. The cell "From Obj" should be a single integer for object number we want to load DLL parameter settings.
2. The par# is a string only including integer, comma, dash, and spaces. Integers are separated by comma. Dash is used to represent a range of integers.
3. By cliking the button Load Par#, all the parameter numbers from the object defined by "From Obj" will be written in Par# cell.
4. Par Val is a string only including numbers, comma, and spaces. Numbers don't need to be integer and are separaterd by comma.
5. By clicking the button Load Values, the value of parameter number defined by cell Par# in object defined by cell "From Obj" will be collected and written in cell Par Val.
6. The To Objs is a string works similar to Par#. We can define one or multiple objects that the 3 buttons "Set MCE", "Set paraemters", and "Copy paraemters" will use for target.
7. By clicking the button Auto Detect, the tool will automatically collect all objects that uses same DLL as the object defined by cell "From Obj" and write them in the cell To Objs.
8. By clicking the button Set MCE, we can create a series of multi-config operands that load the diffraction DLL parameters for objects defined by "To Objs" and its parameters defined by "Par#".
   
9. By clicking the button "Set paraemters", the tool will use the settings in "Par#" and the corresonding "Par Val" to set up the DLL parameters for the objects defined by "To Objs".
10. By clicking the button "Copy parameters", the tool will copy the DLL parameter defined by "Par#" from the object "From Obj" to the objects "To Objs".
11. By default all above operation will only consider refelct DLL parameters. When "Also Set Transmission" is checked, the transmission parameters will also be set up.
12. There are 3 shortcuts at the right side of the step 1 block. All 3 will set Par# to 5. Link Lum On (1) will set Par Val to 1. Link Lum On (99) will set it to 99. Link Lum Off will set it to 0.

Please refer to this forum post if you can't run the extension: Why I got the message Failed to locate OpticStudio when trying to run an extension | Zemax Community

8. Examples

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:

Also in attached file, users can file more application examples for AR waveguide, Flash LiDAR, grating on curved surface.

Appendix - Customize your gratings

Please note that the wrong setup of grating file (.fsp) can cause simulation fail. We have provided a Troubleshooting steps for check possible problem in the .fsp file.

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.

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

A.1 topcell

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.

A.2 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”.

Note that, by "simulation region", we mean the region defined by uppermost and lowermost layer in the RCWA object settings. Ths is the place where we consider the structure in the RCWA calculation. It's important to know the actual RCWA object size must be slightly larger than the simulation region. In dynamic link, the RCWA object region will always to 0.1 µm larger than the simulation region. Therefore, we suggest to set the positive_z_material and negative_z_material to be 0.2 µm in their z size.

The following shows 3D view of positive_z_material, negative_z_material and RCWA object region. The simulation region should be between the positive_z_material and negative_z_material. The RCWA object region should be always slightly larger than simulation region.

A.3 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.

A.4 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. Note this is the No. 1 problem when users customize their own grating while forget this setting.
  
• 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.
• 

A.5 RCWA Object

Here only the required settings in the RCWA object will be explained. More details about this solver object can be found in this article: RCWA Solver - Simulation Object – Ansys Optics

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 are the interfaces. This setting is related to the z-direction mesh numbers. If users don't set this value correctly, the simulation result could be inaccurate. 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.

Users can try to set the value of the interfaces, the larger interfaces value also means more mesh number.

A.6 Ignorable parameters

The following is a list of parameters that will be automatically controlled by the dynamic link and users don't need to change their value in the .fsp file.

1.  p#_**** parameters in topcell structure.
2.  period_x, period_y, n_neg, n_pos in topcell structure. period_x and period_y follow the settings in OpticStudio UI. n_neg and n_pos are decided by the Material settings in OpticStudio.
3. RCWA object's x, y, z sizes. The sizes x and y follow the period_x and period_y settings in OpticStudio UI. The size z is decided by adding 0.1 µm margin to the uppermost and lowermost layer setting in RCWA object.
4. All settings in excitation (incident ray) in RCWA object. These will be based on the incident ray's data in OpticStudio.
5. K-space discritization settings in RCWA object. See explanation of "Max Order" below.

A.7 How to change x/y mesh 

We cannot directly edit them, and in general, it's not necessary to change the x/y direction mesh. But if users want to change the mesh size, the values are automatically determined by a number of k vector domains. If users increase the k numbers, the mesh number will also be increased. 

A.8 How to support dispersion (refractive index vs. wavelength) in the grating

As shown below, the sample .fsp files, the lswm_2D_hex_cylinder_221210.fsp for example, provided in this article is designed to let user exactly specify the refractive index for the pillars, which is independent to the wavelength.

However, it's possible users modify these .fsp so that the refractive index can automatically change based on the wavelength. A short guidance to make this change is provided below.

1. We need to first remove the corresponding property, "p4_pillar_index" for example, in the topcell object.

2. Then we need to remove the related code in the script of topcell. For example, if we remove the property "p4_pillar_index" from the topcell, we also need to remove the following line from the topcell script:

   setnamed("circle_"+lbls{j},"index",p4_pillar_index);

3. Finally, the related object in the topcell group should be modified with using the correct material as below.

A.8 How to consider tangential vector

To make the .fsp file supporting lattice vector angle, it's needed to add a parameter called "lattice_vector_angle" in the topcell object.

The script should also correctly consider the angle change and modify the grating structure. The following is only an example of part of the code where we change the upper and lower blocks. This is only an example. As a lazy method, designers can also just make the upper and lower block to be 2x ~ 3x large which can cover most of possible lattice vector angle settings.

One thing designer should be careful it that when changing the lattice vector angle in RCWA settings, the RCWA regions will tilt with anchored at the lower left point. This make the RCWA region seems like having a x shift.

For convenience, when the dynamic link plugin changes the lattice vector angle of the RCWA settings, it will also set up a x shift to the RCWA region as below so it's always "centered" in x direction.

setnamed('RCWA', 'x', -tan((90-latticeVectorAngle)/180*pi) * period_y / 2);

In other words, if the lattice vector is set up from the dynamic link plugin, the RCWA region will looks like below.