Lumerical Sub-Wavelength Model: How to Simulate a Grating with Spatial Variations

The Lumerical Sub-Wavelength Model (LSWM) plugin enables the simulation of optical surfaces with sub-wavelength structures, such as diffraction gratings, thin-film coatings and polarizers, within raytracing software Ansys Zemax OpticStudio and Ansys Speos. This is achieved using input data generated from Ansys Lumerical simulations’ results. For certain applications, such as augmented reality glasses, it is necessary to spatially vary the gratings along specific directions.

In this article, we will explain how to model and simulate a diffraction grating with spatial variation using the LSWM plugin.

Introduction

A single .json file can contain multiple grating simulation data. The basic principle is to define a grid of points, each labeled with an index. When a ray intersects the grating at a given spatial location, Zemax or Speos raytracing software identifies the corresponding grating orders based on its position on the ray's position on the surface.

The main intention for this feature is to simulate primarily grating with smooth variation. If a ray hits at a location between several grid points, a linear interpolation is made (though it can be deactivated) between the different responses (e.g. direction of the diffraction order, or efficiency) of the closest surrounding grid points. Then, for a region with a linear variation (or no variation at all), it is only necessary to define the response of the extreme points of the region. On the other hand, very fast variation would require many data points with a fine sampling.

For each grating variant, it is possible to completely customize the parameters (period, material, height, duty cycle, etc…).

As of release 2026 R1.1 the lmapexport - Script command – Ansys Optics is available, for exporting the .lswm and .lmap files. More details are provided in section How to generate .lswm and .lmap files with RCWA solver.

How to generate the .json file with Ansys Lumerical FDTD

The most complex part of this workflow is the generation of the .json file with all the required spatial information. The process is described step by step as follows:

1. Definition of the grid of sampling points
2. Definition of the index map
3. Definition of the reciprocal lattice vectors
4. Generation of the .json file with the response computed with the RCWA solver

Definition of the grid of sampling points

The 1st step to generate the data is to define a map of points for the spatial variation. There are 3 options to construct a map for the spatial variation:

• Cartesian coordinates (x,y)
• Polar coordinates (r,\(\theta)\)
• Custom parameter scan: this special case enables to call for the index number directly rather than a spatial coordinate.

Definition of the index map

Each grid point is labeled with an index going from 0 to M. M must be an integer inferior or equal to the number of grid points defined in the spatial map. If several points have the same index, it means the same grating is used at each of these points.

If an index is set to 0 (or any value smaller than 1), it means there is no grating at this location and the Fresnel law will be applied for the ray interaction.

Note that the sampling needs to be a regular rectangular grid of points. To define a non-rectangular region, set the index of the points outside of the grating region to 0.

Definition of the reciprocal lattice vector

The .json file is not containing specific information about the nature of the grating (e.g. height, duty-cycle, slant angle), it only contains a set of response computed by the RCWA. However, it is necessary to specify the period of the grating so that the ray tracing software (Ansys Zemax OpticStudio or Ansys Speos) reading the data can not only provide the correct efficiency of the given diffractive orders, but also figure out its direction. Then, in addition of the index, it is also necessary to provide the reciprocal lattice vectors defining the period and the orientation of the grating at each particular grid point. Since 2D gratings are supported, there are 2 reciprocal lattice vectors that can be provided at each points, labelled 1 and 2. For 1D gratings, the 2nd vector can simply be set at 0.

Generation of the .json file with the RCWA solver information

We do not cover in this article how to model a diffractive grating and setup a RCWA solver region in Ansys Lumerical FDTD (RCWA solver). For more information on basic cases, see Lumerical Sub-Wavelength Model: Introduction and Data Generation.

For simple cases without spatial variation, it is possible to simply right click on the RCWA results to export them as a .json file. However, in the case where a spatial variation is defined, the RCWA solver needs to be run several times, once for each grating variant defined with a different index as described in the previous sections. Attached are a few example scripts that can be used as templates (see the "Examples" section).

Below is a list of the different parameters that need to be set in the script:

• Spatial map:
  • spatial_variation_or_parameter_scan.pos_x         # Vector of size 1 x N1
  • spatial_variation_or_parameter_scan.pos_y         # Vector of size 1 x N2
  • spatial_variation_or_parameter_scan.pos_rad     # Vector of size 1 x N1
  • spatial_variation_or_parameter_scan.pos_pol     # Vector of size 1 x N2
  • spatial_variation_or_parameter_scan.par_1               # Vector of size 1 x N1
  • spatial_variation_or_parameter_scan.par_1_name    # String
  • spatial_variation_or_parameter_scan.par_2              # Vector of size 1 x N2
  • spatial_variation_or_parameter_scan.par_2_name   # String
• Index map:
  • spatial_variation_or_parameter_scan.index_map   # Matrix of size N2 x N1
• Reciprocal Lattice Vector:
  • reciprocal_lattice_vector_1       # Matrix of size M x 2 
  • reciprocal_lattice_vector_2       # Matrix of size M x 2 

where M is the maximum index number in spatial_variation_or_parameter_scan.index_map.

Note that even if there is no variation of the period induced (e.g. variation of another parameter, or no variation), it is necessary to copy the reciprocal lattice vector into the matrix so that it holds M lines.

It is also important to note that when running the RCWA for the different variant of the grating it is possible that they don't have all the same output orders (e.g. order +2 exist in one case and not in another). However, the set of RCWA runs for each case should have the same size. In the template scripts provided (see examples below), the list of orders to be read is specified to ensure all datasets have the same dimension.

Usage in Ansys Zemax OpticStudio

The usage with OpticStudio is similar to the case without spatial variation, the .json file is selected from the drop-down list. For more information, see Lumerical Sub-wavelength Model: Usage in Zemax OpticStudio. The DLL from version 2024.R2.2 and beyond supports .json files with spatial variation. A few additional parameters are available compare to older versions:

• Stochastic Mode:

  Trace the ray in stochastic mode instead of splitting into multiple rays.

• Test mode:

  This variable is used for troubleshooting. It can be set to different values to output different level of information in a log file. The log file is generated in the folder Zemax DLL diffractive where the .json file is also located.

  • 0: nothing logged
  • +1: log for major issue
  • +16: logs for every ray
  • +32: DLL exports a detailed log file (File can be heavy with many rays)

• Rotate Grating (degrees):

  Enable to rotate the gratings from a certain angle in degree

• Check Environment index:

  This is a flag to avoid using a grating in a configuration different than the environment in which it was characterized with the RCWA. If set to 1, the index of the material defined in Zemax OpticStudio will be compared to the value of the index material written in the .json file. If they are different, an error will occur un the ray tracing.

• Parameter Scan 1 and 2:

  These parameters are used when the map is defined with the custom method. This variable then enables to call the desired index directly from the .json file.

• No Interpolation:

  This variable is used to deactivate interpolation. The closet point is then used to determine the grating parameter at any given location. Different level of interpolation can be deactivated depending on the entry value of this parameter:

  • 0: Interpolation is active
  • +1: no interpolation for angle
  • +2: no interpolation for wavelength
  • +4: no interpolation for xy

  e.g. if set to 6, the interpolation will be deactivated in angle and xy. 7 would mean no interpolation at all. Note that the interpolation flags can be set directly into the file, but they may be overwritten with this parameter. 

Usage in Ansys Speos

With Ansys Speos there are no additional parameters to set the interpolation flags like in Zemax OpticStudio. If you want to turn on and off interpolation in Speos, the interpolation flags shall be set directly in the file. 

Below is the flag list to turn on and off the interpolation. By default, all interpolations are turned on. 

By setting polarization_interpolate_over_spatial_parameter = False/0  in the file, the interpolation can be turned on. For more information, see Lumerical Sub-wavelength Model: Usage in Speos.

Note that with the spatial variation, the grating region is defined on the specified spatial region of the surface, the UV map cannot be used to rescale or rotate it. The orientation of the grating can be modified by rotating manually the axis system attached to the surface.

How to generate .lswm and .lmap files with RCWA solver

Generation of the .lswm file

Follow the steps below to export the sweep results from RCWA solver in .lswm file:

1. Set up the RCWA simulation as you would a normal RCWA simulation.
2. Set the propagation direction to both in the General tab of the RCWA settings.
3. Enable the report grating characterization option in the Results tab of the RCWA settings.

4. In the sweep object add both “grating_characterization” and “substrate” in the results tab:

   

5. Run the sweep.
6. Right click on the sweep object and select Export to LSWM. A dialog window will appear.

7. In the dialog window, there are several options to be set by the user:

   Lattice angle (degrees)	Set the lattice angle that has been used in RCWA “Geometry” tab
   Backward definition	Set it to the definition that was used in RCWA “General” tab
   Lossless	Defaults to false. Enable this option if the cladding or substrate materials is lossless.
   Interpolate over incident angle	Defaults to false. Enable this option to enable linear interpolation of responses for when incident rays are between angles defined in the RCWA solver.
   Interpolate over incident wavelength	Defaults to false. Enable this option to enable linear interpolation of responses for when incident rays have a wavelength between the wavelength points from the RCWA solver.
   Truncate order	Defaults to false. Enable this option to enable truncation of grating orders. When this is set to false, all orders are kept. If this option is enabled, you must provide the minimum and maximum orders.
   Polarization interpolation basis	Set the basis for interpolating the polarization when the LSWM file is imported, either “SP”, “XY” or “Auto”
   Resampling parameter	Select the parameter to be resampled as well as the number of resampling points. Number of points to resample to must be an integer value greater than 2. Out of all the resample options, you can only select one parameter to resample.

8. Select a path and name for the generated LSWM file either by editing the text box or clicking the Save as... button to open a file dialog.
9. Click the OK button to save the file.

Alternatively, you can use the lswmexport - Script command – Ansys Optics. An example for exporting .lswm file using script is provided below:

lswmFile="export_sweep.lswm";
span = [getnamed("RCWA","x span"), getnamed("RCWA","y span"),getnamed("RCWA","z span")];
latticeVectorAngle = getnamed("RCWA","lattice vector angle");
grating_characterization = getsweepresult("sweep","grating_characterization");
substrate = getsweepresult("sweep","substrate");

lswmexport({"grating_characterization":grating_characterization, "substrate":substrate,"lattice_angle":latticeVectorAngle, "mirror_k_vector":1,"span":span},lswmFile,{"polarization_interpolation_basis":"AUTO","truncate_order":true,"truncate_order_min":-1, "truncate_order_max":1, "lossless":1});

Generation of the .lmap file

The generation of the .lmap file with all the required spatial information is described in the steps below:

1. Definition of the grid of sampling points
2. Definition of the index map
3. Generation of the LMAP file that contains the index map.

Definition of the grid of sampling points

The 1st step is to define a map of points for the spatial variation. There are 2 options to construct a map for the spatial variation:

• Cartesian coordinates (x,y)
• Polar coordinates (r,θ)

Definition of the index map

Each grid point is labeled with an index going from -1 to M-1, with M being the number of sweep points. If several points have the same index, it means the same grating is used at each of these points.

If an index is set to -1 (or any value smaller than 0), it means there is no grating at this location, and the Fresnel law will be applied for the ray interaction.

Note that the sampling needs to be a regular rectangular grid of points. To define a non-rectangular region, set the index of the points outside of the grating region to -1.

It is also possible to vary multiple parameters using nested sweeps. For instance, if one wants to vary the duty cycle in addition to the slant angle of the grating, the sweep should look like this:

If the duty cycle varies from 0.2 to 0.8 and the slant angle from 10° to 60°, the nested parameter list is defined as follows:

Once the index map has been defined, we use the lmapexport - Script command – Ansys Optics to export the LMAP file.

An example using the lmapexport - Script command – Ansys Optics in cartesian coordinates can be found in the attached lmapexport_1D_waveguide.lsf discussed in Example 4.

 An example for exporting the LMAP in polar coordinates is provided below:

map_type = "polar";
lswmFile = "1D_slant_polar.lswm";
cellTypeMap = [ 0,0,0,0,0,0,0,0,0;1,1,1,1,1,1,1,1,1;2,2,2,2,2,2,2,2,2;3,3,3,3,3,3,3,3,3];  #dim1: R from to size_R // dim2: phi from -180 to 180
size_R = 2; #maximum radius size
interpolate_over_spatial_coordinate = true;
spatialInfo = {"size_R":size_R};
mapInfo = {"map_type":map_type, "spatial_info":spatialInfo, "cell_type_map":cellTypeMap};

lmapexport(lswmFile,mapInfo,interpolate_over_spatial_coordinate);

Examples

For these examples to run properly, note that the .json files should be located in the folder Zemax\DLL\ Diffractive.

Example 1: Simple map with XY coordinates

With Ansys Zemax OpticStudio

The .json file for this example is generated with the script [[Generate_JSON_XY_map_simple.lsf]]. Then, open the file [[test_xy_variation.zprj]] to observe how it behaves in the ray-tracing environment. In the diffraction properties of object 2, the file "1D_diffraction_grating_xy_variation_simple.json" should already be loaded. For a better visualization, the sources 4-8 are set to show rays in the layout.

We define a grating region of 2mm x 2mm, with only 4 points (at the 4 corners of the square). At 2 points of this square, we define a grating of period 5µm, and we set the period to 9µm for the 2 other points. In the Lumerical scripts to generate the .json file, it looks like this:

The rest of the script consists of running the RCWA for these 2 cases and writing the results in a .json file. In Zemax OpticStudio, the result looks like this:

With Ansys Speos

The same .json file can be read with Ansys Speos. Open the file [[LSWM_test_XY_variation.scdocx]]. In the simulation tab, ensure the [[.sop]] and the [[.json]] files are selected in the properties of "Surface_json". Then, run the simulation "Direct_Normal_Source".

Example 2: Simple map with Polar coordinates

The .json file for this example is generated with the script [[Generate_JSON_polar_map_simple.lsf]]. Then, open the file [[test_xy_variation.zprj]] to observe how it behaves in the ray-tracing environment. In the diffraction properties of object 2, load the file "1D_diffraction_grating_xy_variation_pol_simple.json". For a better visualization, set the sources 10-17 to show rays in the layout.

In this example, we define a variation along a line of 2mm long. Since we consider only one angle, the variation is then induced in a similar way for all polar angles, i.e. the variation is rotationally symmetric.

Example 3: Advanced map

The .json file for this example is generated with the script [[Generate_JSON_polar_map_simple.lsf]]. Then, open the file [[test_xy_variation.zprj]] to observe how it behaves in the ray-tracing environment. In the diffraction properties of object 2, load the file "1D_diffraction_grating_xy_variation_advanced_map.json". For a better visualization, set the source 19 to show rays in the layout.

In this example, we show how to define a non rectangular grating region with a grid of XY points. The idea is simply to set to 0 the index of all points outside of the desired region.

Example 4: Simple map export using LSWM and LMAP files from RCWA

In this example a slant grating is used, and we perform a sweep in the slant angle between [10° 60°] with a step of 1°.

Within the waveguide, the center propagation angle is around 51°.
It is expected to have maximum efficiency in Tss +1 order for a slant angle around 10°.

For the in‑coupling (IC) grating case we consider a slant grating operating as a green coupler. After running the model we right-click on the RCWA results à grating characterization and export them as a LSWM file named green_coupler_slant10.lswm. In the dialogue box we set all the interpolation flags to true, and we truncate the data to keep only the orders   -1/0/+1. This is the case where no spatial variation is needed.

For the out‑coupling (OC) grating, we want the sweep data over the slant angle, so we generate the LSWM file from the sweep results. First, run the sweep. Then right-click on the sweep object and export the sweep results as a LSWM file named green_coupler_slant_sweep.lswm. In the dialogue box keep the settings same as in previous step.

To generate the LMAP file, open and run lmapexport_1D_waveguide.lsf. We use the lmapexport script command to generate the map for spatial variation. 

The map defines a variation of slant angle in one direction, and no variation in the other direction. 

Setup in Zemax

First, copy all the .lswm and .lmap files as well as the provided lumerical-sub-wavelength-2026R1.dll in the folder Zemax>>DLL>>diffractive.

OC standalone

We start by verifying the behavior of the OC as a standalone. The grating is set as follows:

And we can observe the variation in diffraction efficiency as desired:

Note that you select only the .lswm file. The DLL is looking for a corresponding .lmap automatically. If there is no map found with the same name as the .lswm, there is no spatial variation.

Complete system

In the final system, we have IC + OC.
First, if we use the same file with no spatial variation for both IC and OC, this is what we get:

In order to make the output more uniform, we use the file with spatial variation in the OC: