FDTD Note: lsf Language

Learning notes for lsf script language of Lumerical FDTD.

Useful commands in ScriptPrompt

clear;  # clear all the variables in the workspace
a = 1;
clear a;  # clear variable a

clc;  # clear all the commands in the window

Variables

Variable types

Different types of variable a available in Lumerical’s scripting:

• Strings can be used to define a file name, for instance, or a material.
• Numbers can be used to define dimensions, wavelength, etc.
• Arrays or matrices can be used, for instance, to define a frequency vector or to store a field profile.
• Structure array and cell array can store any type of data elements.
• Matrix datasets contain a data without spatial parameters
• Rectilinear datasets contain data with spatial information from a ectilinear grid (such as the FDTD mesh).
• Unstructured spatial datasets can be used to store data with spatial information on a finite element mesh (for instance, a calculation result from DEVICE) and arbitrary unstructured datasets can store any kind of data type.

Note:

• Datasets are typically used to store results from monitors.
• Cell arrays have a defined number of elements.
• Cell matrixes are not supported.
• Array is special matrix (1 * N or N * 1 matrix).

Predefined constants

• endl - “\n”

Prinf the values

Use print() or ? to see the value of variables.

a = 1;
print(a);
# > result:
# > 1
?a;
# > result:
# > 1

Initialization of variables

Use operator = to initialize the variables.

string_ = "Rectangle";

number_ = 1;

array1 = [1, 3, 5];  # 1*3 
array2 = [1; 3; 5];  # 3*1 
array3 = 1:2:5;  # equal to [1; 3; 5]
array4 = 5:-2:1;  # [5, 3, 1]
array5 = linspace(1, 5, 3);  # Create an array with 3 numebrs from 1 to 5.

matrix1 = [1, 2; 
           3, 4;
           5, 6];  # 3*2
matrix2 = matrix(2, 3);  # Use the “matrix” and the “zeros” functions to create an array filled with 0.
matrix3 = ones(2, 3);  # Use the “ones” function to create an array filled with ones.

struct_ = struct; # To create a structure array, use the "struct" command.
struct_.a = 1;  # Add and access the structure array’s elements using the “.” operator.
struct_.b = "Rectangle";

cell_ = cell(2);  # to create a cell array, use the "cell" command and specify the number of elements.
cell_{1} = "String";  # The elements can be accessed using "{}" and the index of the element.
cell_{2} = 2;  # The elements can be accessed using "{}" and the index of the element.

Element access

The matrix(array)’s elements can be accessed using operator () with their index. Note the index starts at 1 and not 0.

matrix1 = zeros(2, 3);
print(matrix1(1, 2));
# > result: 
# > 0

The structure array’s elements can be accessed using the . operator.

The cell’s elements can be accessed using {} and the index of the element.

Operations

• num2str()
• str2num()
• unwrap(): remove the changes of more than $2\pi$ from the phase that can be got with the angle function.
• All the angles are expressed in radians in these functions.
• When using mathematical functions on matrixex, the function is applied on each element of the matrixes.
• mult(): matrix multiplication.
• find(): find a value in arrays or matrixes.
• findpeaks(): find array peaks.
• logical operators (pay attention to function almostequal())

Simulation objects

Simulation modes

To add a simulation object and set its properties, you first have to be in layoutmode.

You can do the same by using layoutmode. It returns ‘1’ if you are in layoutmode and ‘0’ when in analysis mode.

To set the simulation into layoutmode, you can use switchtolayout command.

Location (group scope) in the objects tree

Default group scope is model, which is the root of the object tree.

When you add an object using script, it is placed under the current group scope.

Use command groupscope("::model::NAME") to go into one group named “NAME” or groupscope("NAME") if in model scope now.

Add objects

Command: addOBJECT_TYPE_NAME if the name of the object’s type is “OBJECT_TYPE_NAME”. For instance, addrect

Get/Set properties of objects

To set the properties of an object, you first have to select it and then set the properties. But when you add an object, it is automatically selected as shown here with addcircle. So there is no need to select the object if you are to set its properties right after adding it.

How to select objects?

• select("NAME"): select the object named “NAME”.
• shiftselect("NAME"): select new object named “NAME” while keeping the current selected objects.
• selectall(): select all the objects.
• selectpartial("PNAME"): select objects with the partial name “PNAME”.

How to set property?

• Use command set("PROPERTY_NAME", VALUE) to set the property named “PROPERTY_NAME” of selected objects with value represented by VALUE.
• Use command setnamed("OBJECT_NAME", "PROPERTY_NAME", VALUE) to set the property named “PROPERTY_NAME” of the object named “OBJECT_NAME” with value represented by VALUE.

How to get property?

• Use command get("PROPERTY_NAME", VALUE) to get the property named “PROPERTY_NAME” of selected objects.
• Use command getnamed("OBJECT_NAME", "PROPERTY_NAME") to get the property named “PROPERTY_NAME” of the object named “OBJECT_NAME”.

Delete objects

To delete one object, you first have to select it. And then, run delete() to delete the selected object.

Use command deleteall() to delete all the objects.

Running simulations

Running a single simulation

To start a simulation, simply use the command run. It will launch the current project using the resources set in the resource manager.

Once the simulation is finished, the project is in analysis mode. Modification of any simulation settings is not allowed in this mode.So, if you want to change some of the settings for another simulation, you first need to get back to layout mode, using the command switchtolayout. Note you can use the command layoutmode to check if the project is in layout or analysis mode. It returns ‘1’ if you are in layoutmode and ‘0’ when in analysis mode.

Running multiple simulations using the job manager

The job manager allows you to run concurrent calculations using the resources set in the resource manager.

Commands:

• Use command addjob("FILENAME") to add the specified project named “FILENAME” to the queue of simulations to be run.
• Use command clearjobs to remove all jobs from the queue.
• Use command runjobs to run all the jobs in the queue.

Notes:

• The job manager can be used to run a parameter sweep by creating all the simulation files and add them to the queue firstly and then running the jobs in the queue.
• (Advantage) The job manager can run more than 1 simulation at a time.

Running parameter sweep and optimization

When using parameter sweep, the selected task is run by first creating simulation files corresponding to the sweep parameter values and then adding them to the job manager.

Commands:

• Use command runsweep("TASKNAME") to start the specified task named “TASKNAME” in the Optimizations and Sweeps window.
• Use command runsweep to start all the tasks.

Accessing and visualizing simulation results

Accessing simulation results

There are two types of data available in an object: results and rawdata. While results contains datasets formed by related data, rawdata contains individual data elements in matrix form. In comparison to rawdata, results have the advantage that they can be opened in the visualizer to generate plots with proper axes.

Basic commands:

• Use command getdata("OBJECT_NAME", "PROPERTY_NAME") to get a rawdata named “PROPERTY_NAME” from the object named “OBJECT_NAME”.
• Use command getresult("OBJECT_NAME", "PROPERTY_NAME") to get a results named “PROPERTY_NAME” from the object named “OBJECT_NAME”.
• Omit the parameter “PROPERTY_NAME” to get all.

mname = 'profile';

# rawdata
x = getdata(mname, 'x');
y = getdata(mname, 'y');
Ex = getdata(mname, 'Ex');
Ey = getdata(mname, 'Ey');
Ez = getdata(mname, 'Ez');

# results (equal)
E = getresult(mname, 'E');
x = E.x;
y = E.y;
Ex = E.Ex;
Ey = E.Ey;
Ez = E.Ez;

Commands for retrieving specific data from monitor:

• Use command getelectric("MONITOR_NAME") to get the intensity of electric field from the monitor named “MONITOR_NAME”.
• Use command getmagnetic("MONITOR_NAME") to get the intensity of magnetic field from the monitor named “MONITOR_NAME”.
• Use command transmission("MONITOR_NAME") to get the fraction of power transmitted through the monitor named “MONITOR_NAME” with respect to the source power.

Commands for retrieving data from parameter sweep, optimization, yield analysis, and S-parameter sweep objects:

• Use command getsweepdata("SWEEP_NAME", "PROPERTY_NAME") to get a rawdata named “PROPERTY_NAME” from the Optimization and Sweeps object named “SWEEP_NAME”.
• Use command getsweepresult("SWEEP_NAME") to get a result named “PROPERTY_NAME” from the Optimization and Sweeps object named “SWEEP_NAME”.
• Omit the parameter “PROPERTY_NAME” to get all.

Notes:

• The sign of the transmission depends on the direction of propagation. The transmission is positive when the power is flowing through the monitor in the positive direction, that is in the +x, +y, or +z direction. So for a planewave propagating in backward (negative) direction, a negative transmission will be returned.

Visualising simulation results

• plot creates a line plot. All data sets in its argument should be sampled on the same position vector.

x = 1:0.1:10;
y1 = sin(x);
y2 = cos(x);

plot(x, y1);
# >

plot(x, y1, y2, "x label", "y label", "title");
legend("sin(x)", "cos(x)");
# >

# Plotting options
plot(x, y1, "x", "y", "title", "plot type = point, color = red, marker style = o")
# >

• plotxy allows us to use datasets that are sampled on different position vectors.

x1 = linspace(0, 2*pi, 10);
y1 = sin(x1);
x2 = linspace(pi, 3 * pi, 5);
y2 = cos(x2);

plotxy(x1, y1, x2, y2, "x label", "y label", "title");
legend("sin(x1)", "cos(x2)")
# >

• polar visualizes results in polar coordinates. All data sets must be sampled on the same array of angle values.
• polar2 adds multiple polar plots sampled on different angle values.
• image creates 2D color plots.

x = linspace(0, 10, 100);
y = linspace(0, 10, 100);
X = meshgridx(x, y);
Y = meshgridy(x, y);
Z = sin(X) ^ 2 + cos(Y) ^ 2;
image(x, y, Z, "x label", "y label", "title");
# >

• polarimage creates 2D polar image plots. The first two arguments should be a vector that can go from -1 to +1. When used with farfield projection commands, the first two arguments are associated with the direction cosine of the farfield - hence the limitations on the values they can accept.
• Use command setplot to get the properties can be set for current figure window.
• Use command setplot("PROPERTY_NAME", VALUE) to set the property named “PROPERTY_NAME” of the current figure window with value VALUE.
• holdon switches the plotting mode to hold multiple functions on the same figure.
• holdoff switches off the holdon mode.
• selectfigure(NUMBER) selects a figure with a specified figure number NUMBER. When used without any argument, it selects the last figure created.
• exportfigure("FILE_NAME", XRES, YRES) exports the current figure to a JPG image with the name ‘filename’, the x resolution XRES and the y resolution YRES. If the x/y resolutions are not specified, the exported image will have the same size as the current figure.

File I/O

Manipulating project files

Commands:

• Use command newproject without argument will create a new project based on the default template. You can also create a new simulation project based on another template with an argument, for instance to use materials from an existing simulation file.
• Use command save("PATH_FILENAME") to save the current simulation project in a file specified with “PATH_FILENAME”. You can specify a path, otherwise the file will be saved in the current directory. If you don’t specify the file name, a file browser window will open.
• Use command load(PATH_FILENAME) to load another project with “PATH_FILENAME”.

Tips

• "" is equal to ''.

Reference

Core

[1] Lumerical scripting language - Alphabetical list: https://optics.ansys.com/hc/en-us/articles/360034923553

[2] Lumerical scripting language - By category: https://optics.ansys.com/hc/en-us/articles/360037228834-Lumerical-scripting-language-By-category

[3] Scripting100 videos: https://www.bilibili.com/video/BV1hr4y1w7Ze?p=1&vd_source=c24841bbb7f5d10925aeadfcbf43b52f

[4] Scripting100 transcripts: https://optics.ansys.com/hc/en-us/sections/360007813714-SCRIPTING100-List-of-videos

Note:

• You can learn Scripting100 Course using Ref.[3] with Ref.[4].