File formats

Toggles the script interpreter between 2 output precision states. The commands ? (print, display) and num2str use this state to set the digits of precision for output.

Syntax	Description
format long;	Set script interpreter to 16 digits of precision.
format short;	Set script interpreter to 6 digits of precision (maximum).

Examples

Print π

to screen in both output formats.

format short;
?pi;
result: 
3.14159

format long;
?pi;
result: 
3.141592653589793

The behavior of the short and long format.

format short;
?1;
result: 
1 

format long;
?1;
result: 
1.000000000000000

CSV (Comma separated value) files

exportcsvresults - Script command

This script command can export the results of a simulation to comma separated value formatted files, which can be opened by Microsoft Excel.

Syntax	Description
exportcsvresults("filename")	exports the results of the entire simulation to multiple .cvs files, named filename_elementname.csv
exportcsvresults("filename", "elementname")	exports the results of the specified element to a .cvs file, named filename_elementname.csv

Parameter	Type	Description
filename	string	name of the .csv file
elementname	string	name of the element.

fld (field) files

asapexport - Script command

FDTD MODE

Exports the desired monitor to a file for interfacing with BRO's ASAP. These files have the .fld extension. The monitor must be a frequency power or a frequency profile monitor.

Syntax	Description
asapexport( "monitorname");	Export data from monitorname. By default, the first frequency point is exported. This function does not return any data.
asapexport( "monitorname", f);	Exports the frequency point specified by the index f.
asapexport( "monitorname", f, "filename");	Exports to the specified "filename" without opening a file browser window.

Syntax

Description

asapexport( "monitorname");

Export data from monitorname. By default, the first frequency point is exported.

This function does not return any data.

asapexport( "monitorname", f);

Exports the frequency point specified by the index f.

asapexport( "monitorname", f, "filename");

Exports to the specified "filename" without opening a file browser window.

Examples

Export data from monitor transmission to a .fld file for ASAP. The monitor had more than one frequency point, so the first point was exported by default.

asapexport("transmission");
Warning: prompt line 1: in asapexport: no frequency point was specified and the d-card has

asapload - Script command

FDTD MODE

Loads data from an fld file from BRO's ASAP. asapload creates a d-card structure called "fld_data" which contains all the data in the file. If "fld_data" exists, it will be called "fld_data_2". After loading an asapfile with asapload, you can extract any desired data., which can be

Ex, Ey, Ez, Hx, Hy, Hz, x, y, z
power, frequency, wavelength, index

Syntax	Description
asapload;	Select the file to load with the file browser. This function does not return any data.
asapload( "filename");	Loads data from an fld file called "filename" without a file browser.

Syntax

Description

asapload;

Select the file to load with the file browser.

This function does not return any data.

asapload( "filename");

Loads data from an fld file called "filename" without a file browser.

Examples

After loading the file, you can use ?getdata to see a list of all d-cards, or the variables in the d-card. Data can be extracted using the getdata function. For example, the real part of Ex can be imaged using the following code.

asapload("asap.ldf");
?getdata;
global monitors:
 fld_data 
?getdata("fld_data");
f wavelength index power x y z Ex Ey
Ez Hx Hy Hz 
Ex = getdata("fld_data","Ex");
x = getdata("fld_data","x"); 
y = getdata("fld_data","y"); 
image(x,y,pinch(real(Ex)));

asapimport - Script command

FDTD

Imports an ASAP fld file into an ASAP source. This is equivalent to editing the properties of the Import source, and clicking on the Import Source button.

Syntax	Description
asapimport( "sourcename");	Imports the fld file into the sourcename source. A file browser will open to select the file. This function does not return any data.
asapimport( "sourcename", "filename");	Specify the file to open.

Syntax

Description

asapimport( "sourcename");

Imports the fld file into the sourcename source. A file browser will open to select the file.

This function does not return any data.

asapimport( "sourcename", "filename");

Specify the file to open.

GDSII

gdsopen - Script command

This function creates a new .gds file and returns a file handle that can be used with the other GdsWriter functions to write the file. The default database units are in 0.1nm and the user units are microns. The GDSII export function works as a group of commands, shown below as an example. For more information, please see GDSII - Import and export .

Syntax	Description
f = gdsopen("filename", "userUnit", "dataBaseUnit")	Opens a .gds file in the current directory, specifies the size of user units and size of the GDSII file units. f is a file handle to open the GDSII file.

Parameter	Type	Description
filename	string	name of the GDSII file to export, may also contain a file path.
userUnit	number	size of user units in GDSII file units.
databaseUnit	number	size of the GDSII file units in meters.

Example

This shows an example to export some simple structures to GDSII format via script code

f=gdsopen('GDS_export.gds'); 
# create a .gds file to write code. If the file exits, it will be overwritten.
gdsbegincell(f,'cell_1');# create a cell named "cell_1"
gdsaddcircle(f, 5, 0, 0, 1.5e-6);# add a circle
gdsendcell(f);# finish "cell_1"
gdsbegincell(f,'cell_2');# create another cell
gdsaddpoly(f, 5, [0,0; 1.5,0; 1.2,1.3]*1e-6);# add a polygon 
gdsaddcircle(f, 5, -3e-6, -3e-6, 1.5e-6);# add a circle 
gdsaddrect(f, 5, -3e-6, 3e-6, 1e-6, 2e-6);# add a rectangle 
gdsaddref(f, 'cell_1', 3e-6, -3e-6);
# reference a structure from "cell_1"
gdsendcell(f);# finish the current cell
gdsclose(f);# close the current .gds file
gdsimport('GDS_export.gds','cell_1', 5);
# show the exported design in a layout environment

An example of script code is available on the webpage.

gdsclose - Script command

This function closes a GDSII file for writing. Before calling this command, a .gds file has to be previously opened, see gdsopen.

Syntax	Description
gdsclose("filename")	closes a .gds file in the current working directory.

Parameter	Type	Description
filename	string	name of the GDSII file to export, may also contain a file path.

Example

An example of script code is available on the gdsopen page.

gdsbegincell - Script command

This function creates a cell in a GDSII file. All GDS elements (polygons, boxes, references, array references, etc) must be placed inside a cell, so this function must be called before adding any elements. When finished adding elements, gdsendcell can be called to finish the cell. Cells cannot be nested, so after calling gdsbegincell, a new cell cannot be called again until the first called cell has been closed. Although the GDSII file is a flat list of cells, cells can reference other cells, thus creating a nested hierarchy. See gdsaddref for more details. A GDS "cell" exists as a "structure group" when imported to FDTD, see gdsimport for more details.

Syntax	Description
gdsbegincell(f, "cellname")	Creates a new cell in a GDSII file.

Parameter	Type	Description
f	string	a file handle that was previously opened with gdsopen.
cellname	string	name of the cell.

Example

An example of script code is available on the gdsopen page.

Note: Just to clarify, a GDS cell is different from a Cell Array in FDTD.

gdsendcell - Script command

This function finishes a cell in a GDSII file. This function ends the current cell in the GDSII file stream. The command gdsbegincell has to be called before closing a cell.

Syntax	Description
gdsendcell(f)	Finishes the previously created cell in a GDSII file.

Parameter	Type	Description
f	string	a file handle that was previously opened with gdsopen.

Example

An example of script code is available on the gdsopen page.

gdsaddpoly - Script command

This function adds a polygon element to a GDSII file stream. Polygons are also known as boundary elements in GDS terminology. This command can be called only if a cell has been created.

Syntax	Description
gdsaddpoly(f, layer, [vertices])	Adds a polygon element on a layer with vertices.

Parameter

Type

Description

string

a file handle that was previously opened with gdsopen.

layer

string or number

string: a string of the form "layer:datatype" (for example "6:2") can be used to define the layer number and datatype for this structure from the GDSII file to import. Layer and datatype are integers.

number: defines the layer number and sets the datatype to be zero.

vertices

matrix

vertices of the polygon, in a Nx2 matrix where the first column represents x and the second column represents y, e.g., [x1,y1; x2,y2;...xn,yn]. The values are in meters. The first and last values should not be the same, the polygon will be automatically closed.

Example

An example of script code is available on the gdsopen page.

gdsaddcircle - Script command

This function adds an approximation of a circle to a GDSII file stream. GDSII files do not support circles, so this is just a convenient function to create a polygon representation of a circle. Polygons can only be added in a GDSII cell, so this command can be called only if a cell has been created.

Syntax	Description
gdsaddcircle(f, layer, x, y, r, n)	Adds an approximation of a circle on a layer with x-, y-coordinates, radius and number of polygon sides.

Parameter	Type	Description
f	string	a file handle that was previously opened with gdsopen.
layer	string or number	string: a string of the form "layer:datatype" (for example "6:2") can be used to define the layer number and datatype for this structure from the GDSII file to import. Layer and datatype are integers. number: defines the layer number and sets the datatype to be zero.
x	number	x-coordinate of the center position in meters.
y	number	y-coordinate of the center position in meters.
r	number	radius of the circle in meters.
n	number	number of sides to use in the polygon approximation. It is 64 by default.

Example

An example of script code is available on the gdsopen page.

gdsaddrect - Script command

This function adds a rectangle element to a GDSII file stream. This is just a convenient function to create a polygon for the case of a rectangle. Other element type for rectangle (such as, box) is not supported at this moment. Polygons can only be added in a GDSII cell, so this command can be called only if a cell has been created.

Syntax	Description
gdsaddrect(f, layer, x, y, width, height)	Adds a rectangle element on a layer with x-, y-coordinates, width and height.

Parameter	Type	Description
f	string	a file handle that was previously opened with gdsopen.
layer	string or number	string: a string of the form "layer:datatype" (for example "6:2") can be used to define the layer number and datatype for this structure from the GDSII file to import. Layer and datatype are integers. number: defines the layer number and sets the datatype to be zero.
x	number	x-coordinate of the center position in meters.
y	number	y-coordinate of the center position in meters.
width	number	width of the rectangle in meters.
height	number	height of the rectangle in meters.

Example

An example of script code is available on the gdsopen page.

gdsaddref - Script command

This function adds a reference to another cell to the current cell in the GDSII file stream. This function replicates the referenced cell (has to be previously opened and finished) to the current cell, to create a nested hierarchy. The layer numbers of the replicated structures follow the referenced cell. References can only be added in a GDSII cell, so this command can be called only if a current cell has been created. In addition, the cell to be replicated has to exist before it is referenced.

Syntax	Description
gdsaddref(f, "cellname", dx, dy)	Adds a reference to another cell ("cellname") to the current cell, with a specified move of dx and dy.

Parameter	Type	Description
f	string	a file handle that was previously opened with gdsopen.
cellname	string	name of the referenced cell.
dx	number	x-movement of the replicated cell in the current cell.
dy	number	y-movement of the replicated cell in the current cell.

Example

An example of script code is available on the gdsopen page.

gdsaddpath - Script command

This function adds adds a segmented line path with a fixed width. It supports the options with the square corner style.

Syntax	Description
gdsaddpath(fileHandle, layer_datatype, width, vertices);	Adds a segmented line path with a fixed width.

Parameter	Type	Description
fileHandle	string	a file handle that was previously opened with gdsopen.
layer_datatype	integer	layer_datatype is the same as other gdsadd commands, either an integer layer, or an integer layer colon integer data type encoded as string 'x:y'.
width	number	width is a floating number.
vertices	matrix	2 column matrix of floating point coordinates.

Example

This shows an example to export a path and text to GDSII format via script code

f=gdsopen("path_text.gds", 1e-3, 1e-9);
gdsbegincell(f, 'example');
gdsaddpath(f, 1, 0.5e-6, [-1, 0; 1, 0]*1e-6);
gdsaddpath(f, '1:10', 0.5e-6, [-0.9, 0; -1.1, 0]*1e-6);
gdsaddpath(f, '1:10', 0.5e-6, [0.9, 0; 1.1, 0]*1e-6);
gdsaddtext(f, 10, -1e-6, 0, 'this is a pin');
gdsendcell(f);
gdsclose(f);

gdsaddtext - Script command

This function adds a text notation to a gds file at a specified position. This is usually just done on a notes layer for annotations. It supports text at a vertex position.

Syntax	Description
gdsaddtext(fileHandle, layer, x, y, text);	Adds a text notation to a gds file at a specified position.

Parameter	Type	Description
fileHandle	string	a file handle that was previously opened with gdsopen
layer	integer	layer must be an integer
x,y	number	x, y are floating point coordinates where text is placed (lower left corner of text box)
text	string	text is an ascii string that forms the note body

Example

An example of script code is available on the gdsaddpath page.

gdsimport - Script command

This command imports a cell from a .gds file into the layout environment. This is equivalent to performing a GDSII import through the FILE->IMPORT menu. See the Layout editor reference guide on GDSII import for more information.

Syntax	Description
n = gdsimport("filename", "cellname", layer);	Imports the specified layer from the specified cell in the specified file into the current simulation environment. The objects created will have their material set to an object defined dielectric. In 3D, the 2D geometric data will be extruded to default values in the Z dimension. The optional returned value, n, is the number of objects that were imported from the gds file.
n = gdsimport("filename", "cellname", layer, "material");	Same as the above command, but the material of the imported object will be set to the value specified.
n = gdsimport("filename", "cellname", layer, "material", zmin, zmax);	This form of the command is only allowed in 3D layouts. The behavior is the same as the above command, but the structures will be extruded in the Z dimension to the specified z min and z max values

Parameter	Type	Description
filename	string	name of the GDSII file to import. It can contain a complete path to file, or path relative to the current working directory.
cellname	string	name of the cell to import from the GDSII file.
layer	number or string	the layer number from the GDSII file to import. If only elements matching a certain data type are desired, this can be specified by using a string of the form: "6:2" where the desired layer is 6 and the desired data type is 2.
material	string	a valid name of a material in your current layout environment. Partial names of materials can be matched starting at the beginning of the string. For example, "Al (3" would match "Al (300nm)".
zmin	number	the minimum z value for extruding 2D GDSII data into 3D objects
zmax	number	the maximum z value for extruding 2D GDSII data into 3D objects

Example:

This command imports "cell_1", on the first layer in the GDS_export.gds file, with a specified material, z min and z max assigned. For more examples, please visit the Layout editor reference guide on GDSII import .

gdsimport("GDS_export.gds", "cell_1", 1, "Ag (Silver) - CRC", 0, 1e-6);

savegdsfile

Creates a GDS file with the pattern geometry from a layer builder object. Only polygon pattern data is supported. The data must be in the format used by the "geometry" property of layer builder objects.

Syntax	Description
savegdsfile("GDS file name", "cell name", pattern_geometry);	Creates a GDS file ("GDS file name") with a cell ("cell name") that contains the polygon patterns defined in the struct pattern_geometry formatted as the "geometry" property in a layer builder object.

Example

pattern_geometry = getnamed("layer group", "geometry"); # Polygons from layer builder object
savegdsfile("myfile.gds", "my design", pattern_geometry);

Please refer this example for more details.

HDF5 files

h5info - Script command

Returns information about the structure of an HDF5 file.

Syntax	Description
info = h5info("filename");	Returns a struct "info" that contains information about the structure of the HDF5 file named "filename."

Parameter	Type	Description
filename	string	name of the HDF5 file.

Examples

filename = "samplefile.h5";
info = h5info(filename);
?info;
> Struct with fields:
> Attributes
> Datasets
> Datatypes
> FileName
> Groups
> Name

The struct containing the information about the HDF5 file has the following fields:

Belongs to	Field	Description
File	Attributes	structure containing a list of the attributes of the file.
Datasets	structure containing a list of the datasets in the file.
Datatypes	structure containing a list of the datatypes in the file.
Filename	string containing the name of the file.
Groups	structure containing a list of the top-level groups.
Name	string containing the path to the root. The value is always "/".
Groups	Attributes	structure containing a list of the attributes of the group.
Datasets	structure containing a list of the datasets in the group.
Datatypes	structure containing a list of the datatypes in the group.
Groups	structure containing a list of the sub-groups within the group.
Name	string containing the name (path) of the group.
Datasets	Attributes	structure containing a list of the attributes of the dataset.
Dataspace	structure containing information about the size of the dataset.
Datatype	structure containing information about the dataset type.
Name	string containing the name (path) of the dataset.
Propertylist	structure containing various properties of the dataset such as fill value, filter, etc.
Datatypes	Class	string containing the HDF5 class of the datatype.
Name	string containing the name of the datatype.
Size	size of the datatype in bytes.
Type	string describing the type of the datatype.

h5read - Script command

Reads data from an HDF5 file. The command supports a large number of dataset types such as integer, float, double, string, compound, etc.

Syntax	Description
data = h5read("filename", "dataset_name");	Reads data in the dataset named "dataset_name" within the HDF5 file named "filename."

Parameter	Type	Description
filename	string	name of the HDF5 file.
datasetname	string	name (path) of the dataset to be read.

Examples

filename = "samplefile.h5";
info = h5info(filename);
dataset_name = info.Group{1}.Datasets{1}.Name;  # returns the name (path) of the first dataset in the first group
data = h5read(filename,dataset_name);

h5readattr - Script command

Reads attributes from an HDF5 file.

Syntax	Description
attr = h5readattr("filename", "attr_path", "attr_name");	Reads the attribute named "attr_name" at the location "attr_path" within the HDF5 file named "filename."

Parameter	Type	Description
filename	string	name of the HDF5 file.
attr_path	string	name (path) of the dataset or group to which the attribute belongs to.
attr_name	string	name of the attribute to be read.

Examples

filename = "samplefile.h5";
A = h5info(filename);
attr_path = A.Groups{1}.Name;
attr_name = A.Groups{1}.Attributes{1}.Name;
attr = h5readattr(filename, attr_path, attr_name);

h5write – Script command

Write data to HDF5 file. The command supports only real matrices.

Syntax	Description
h5write("filename", "dataset_name", data);	Writes data to a dataset named "dataset_name" in an HDF5 file named "filename". Will create an HDF5 file named "filename" if it does not exist. Otherwise, the dataset is simply added to the existing HDF5 file.
h5write("filename", "dataset_name", data, ["access_mode"]);	Optional argument: "append" or "overwrite" "append": The dataset is added to an existing HDF5 file. If the file does not exist, it is created. This option is set by default. "overwrite": If the HDF5 file named "filename" already exists, the file is overwritten completely. Otherwise, it will be created. The file will only contain the group named "group_name" and the attribute named "attribute_name".
h5write("filename", "dataset_name", data, [{"datatype": "datatype_name"}]);	Optional argument: {"datatype": "int"} or {"datatype": "double"} Struct indicating the data type in which the data is stored in the HDF5 file. {"datatype": "int"}: Will store the matrix data as integers. {"datatype": "double"}: Will store the matrix data as doubles.

Syntax

Description

h5write("filename", "dataset_name", data);

Writes data to a dataset named "dataset_name" in an HDF5 file named "filename". Will create an HDF5 file named "filename" if it does not exist. Otherwise, the dataset is simply added to the existing HDF5 file.

h5write("filename", "dataset_name", data, ["access_mode"]);

Optional argument: "append" or "overwrite"

"append": The dataset is added to an existing HDF5 file. If the file does not exist, it is created. This option is set by default.

"overwrite": If the HDF5 file named "filename" already exists, the file is overwritten completely. Otherwise, it will be created. The file will only contain the group named "group_name" and the attribute named "attribute_name".

h5write("filename", "dataset_name", data, [{"datatype": "datatype_name"}]);

Optional argument: {"datatype": "int"} or {"datatype": "double"}

Struct indicating the data type in which the data is stored in the HDF5 file.

{"datatype": "int"}: Will store the matrix data as integers.

{"datatype": "double"}: Will store the matrix data as doubles.

Parameter	Type	Description
filename	string	Name of the HDF5 file
dataset_name	string	Name of the dataset
data	matrix	Real matrix. Will throw an error if the matrix is imaginary or complex. In this case, real and imaginary part should be stored as two separate real matrices in the HDF5 file.
access_mode	string	Optional argument. Only the strings "append" and "overwrite" are valid options.
{"datatype": datatype_name}	struct	Optional argument. The string "datatype" is a mandatory field in the struct. The field can only have the string values "int" and "double". The only two valid structs are {"datatype": "int"} and {"datatype": "double"}. The latter is the default data type.

Example

Write a real matrix to an HDF5 file as a dataset. Firstly, the matrix is stored using the default data type. Secondly, the matrix is stored as integer dataset.

a = [1, 2, pi; 4, 5, 2*pi];
h5write("testfile.h5", "double_matrix", a);
h5write("testfile.h5", "int_matrix", a, {"datatype":"int"});

Reading the data using h5read gives the following results.

?h5read("testfile.h5", "double_matrix");
result:
1  2  3.14159
4  5  6.28319

?h5read("testfile.h5", "int_matrix");
result:
1  2  3
4  5  6

Overwrite the existing HDF5 file by replacing the existing data with a real 1D matrix as a dataset.

b = [2, 3, 5, 7, 11, 13];
h5write("testfile.h5", "test_vector", b, "overwrite");

Applying h5info and h5read to the HDF5 file shows a singular dataset named "test_vector" which contains the given 1D matrix.

info = h5info("testfile.h5");
?info.Datasets
Cell array with 1 elements

?h5read("testfile.h5", "test_vector");
result: 
2  3  5  7  11  13

JSON files

jsonsave - Script command

Saves data to a JSON file.

Syntax	Description
jsonsave("filename");	Saves all data in workspace to a JSON file using the explicit Lumerical Cell and Matrix Option 1 notation. For detailed information on the notations, please see the page JSON files .
jsonsave("filename", var1, var2, ...);	Saves the specified data variables to a JSON file using the explicit Lumerical Cell and Matrix Option 1 notation. For detailed information on the notations, please see the page JSON files .

Example

The following code example shows how to save the data in Lumerical workspace to a JSON file.

# Create variables a and b
a = 1;
b = [1+2i, 3+4i];
jsonsave("test_json.json");

Data in the "test_json.json" file:

{ "a" : 1, "b" : { "_complex" : true, "_data" : [ 1, 2, 3, 4 ], "_size" : [ 1, 2 ], "_type" : "matrix" } }

Specify the variables you would like to save in your workspace.

a = 1;
b = [1+2i, 3+4i];
string = "string";
jsonsave("test_json.json",a,string);

Creates the following json file.

{
 "a" : 1,
 "string" : "string"
}

jsonsaves - Script command

Saves a struct to a JSON format string. The string can be load by the jsonloads command.

Syntax	Description
out = jsonsaves(struct);	Saves the struct to a JSON format string. The string can be load by the jsonloads command.
out = jsonsaves();	Saves all the variables in the Script Workspace to a JSON format string.

Example

The following code example shows how to save the struct "a" to a JSON format string "str1".

a = {"b": [1, 2, 3], "c" : "a string"};
str1 = jsonsaves(a);

The string "str1" is:

?str1;

 {
  "a" :
  {
   "b" :
   {
    "_complex" : false,
    "_data" : [ 1, 2, 3 ],
    "_size" : [ 1, 3 ],
    "_type" : "matrix"
   },
   "c" : "a string"
  }
 }

The following code example shows how to load the JSON format string "str1" to the Script Workspace:

jsonloads(str1);

jsonload - Script command

Returns the value of a JSON file.

Syntax	Description
jsonload("filename");	Returns the values of the json file (struct, cell, string, number).

Example

The following code example shows how to load the data of the JSON file "test_json.json".

jsonload("test_json.json");
?a;
?b;

The output result looks like:

?a;
result: 
1  
?b;
result: 
1+2i  3+4i

jsonloads - Script command

Loads the value of a JSON format struct to the Script Workspace.

Syntax	Description
jsonloads(str);	"str" is a JSON format string. Returns the struct to the Script Workspace.

Example

The following code example shows how to load the struct "a" defined by a JSON format string to the Script Workspace.

jsonloads('{"a" : ["b", 2, 3]}');

The output result looks like:

?a;
result: 
Cell array with 3 elements  
?a{1};
result: 
b  
?a{2};
result: 2
?a{3};
result: 3

jsonread - Script command

Reads the value of a JSON file to a variable.

Syntax	Description
a=jsonread("filename");	Reads the values of the json file (struct, cell, string, number) and coverts the json lists to Lumerical cells and assign the result to the variable "a". Note that the "jsonread" result must be assigned to a variable.

Syntax

Description

a=jsonread("filename");

Reads the values of the json file (struct, cell, string, number) and coverts the json lists to Lumerical cells and assign the result to the variable "a".

Note that the "jsonread" result must be assigned to a variable.

Example

The following code example shows how to read the data of the JSON file "test_jsonread.json" to the variable "a". The data in file "test_jsonread.json" is:

{
"element" : {
    "name" : "straight_waveguide",
    "prefix": "WG"
    }
}

The read and output result looks like:

a = jsonread("test_jsonread.json");
?a.element.name;

straight_waveguide

jsonreads - Script command

Reads the value of a JSON list string to a variable.

Syntax	Description
a = jsonreads(str);	"str" is a JSON format string.

Example

The following code example shows how to load the struct "a" defined by a JSON format string to the variable "d".

d = jsonreads('{"a" : ["b", 2, 3]}');

The output result looks like:

?d;
result: 
Struct with fields:
a

?d.a;
result: 
Cell array with 3 elements 

?d.a{2};
result: 
2

?d.a{3};
result: 
3

jsonvalidate - Script command

Validates a JSON file against a JSON schema.

Syntax	Description
jsonvalidate(data, schema);	Validates a JSON file against a JSON schema, which itself is validated against draft 7 of the standard. "data" and "schema" can be either a struct with the data or a filename. The schema uses standard conforming data and schemas. This command returns the "Validation" struct with the "generalMsg" and "valid" fields to indicate the validation result.

Syntax

Description

jsonvalidate(data, schema);

Validates a JSON file against a JSON schema, which itself is validated against draft 7 of the standard.

"data" and "schema" can be either a struct with the data or a filename. The schema uses standard conforming data and schemas.

This command returns the "Validation" struct with the "generalMsg" and "valid" fields to indicate the validation result.

Example

The following code is an example of validating the JSON file "json_schema_validation_port_data.json" against the JSON schema saved in the file "json_schema_validation_partial_schema_struct.json" (files attached). There are 5 tests in the script that generates different validation results.

?"Test 1 : Correct Json data and schema using filenames";
ValidationResult = jsonvalidate("json_schema_validation_port_data_original.json", "json_schema_validation_partial_schema_struct.json");
?ValidationResult.valid;
assert("Validation failed", ValidationResult.valid == 1.);
?"-----------------";

clear;
?"Test 2 : Correct Json data and schema using jsonread";
ValidationResult = jsonvalidate(jsonread("json_schema_validation_port_data_original.json"), jsonread("json_schema_validation_partial_schema_struct.json"));
?ValidationResult.valid;
assert("Validation failed", ValidationResult.valid == 1.);
?"-----------------";

clear;
? "Test 3 : Invalid data type - number instead of required string";
json_data = jsonread("json_schema_validation_port_data_original.json");
json_schema = jsonread("json_schema_validation_partial_schema_struct.json");
incorrect_data_value = 1.0;
json_data.port_list.connected_port_list.opt_1.name = incorrect_data_value;
jsonwrite("port_data_temp.json", json_data);
ValidationResult = jsonvalidate("port_data_temp.json", json_schema);
?ValidationResult.valid;
?ValidationResult.specificMsg;
?ValidationResult.value;
?ValidationResult.location;
assert("Validation should fail", ValidationResult.valid != 1.0);
assert("pos should be in the json file", str2num(ValidationResult.value) == incorrect_data_value);
assert("Found error in connected_port_list", ValidationResult.location == "/port_list/connected_port_list/opt_1/name");
?"-----------------";

clear;
? "Test 4: Invalid data - missing required properties";
json_data = jsonread("json_schema_validation_port_data_original.json");
json_data.port_list.connected_port_list.opt_1 = {"loc" : 0.3};
ValidationResult = jsonvalidate(json_data, "json_schema_validation_partial_schema_struct.json");
?ValidationResult.valid;
?ValidationResult.specificMsg;
?ValidationResult.value;
?ValidationResult.location;
assert("Validation should fail", ValidationResult.valid != 1.0);
assert("name should be in the json file", findstring(ValidationResult.specificMsg, "name"));
assert("Found error in connected_port_list", ValidationResult.location == "/port_list/connected_port_list/opt_1");
?"-----------------";

clear;
? "Test 5 : invalid schema input";
schema = 1;
try{jsonvalidate("json_schema_validation_port_data_original.json", schema);}catch(ErrMsg);
assert("schema should be string or struct", ErrMsg != "");

And the 5 tests generate the following test result messages based on different problems in the JSON file. Note that the 5 tests are for a successful validation, an invalid data type, missing fields, a successful validation, and an invalid schema to test against, respectively.

Test 1 : Correct Json data and schema using filenames
result: 
1 
-----------------
Test 2 : Correct Json data and schema using jsonread
result: 
1 
-----------------
Test 3 : Invalid data type - number instead of required string
Validation failed, see return value for more details
result: 
0 
unexpected instance type

1.0
/port_list/connected_port_list/opt_1/name
-----------------
Test 4: Invalid data - missing required properties
Validation failed, see return value for more details
result: 
0 
required property 'name' not found in object

{"loc":0.3}
/port_list/connected_port_list/opt_1
-----------------
Test 5 : invalid schema input

jsonwrite - Script command

Writes a single variable to a JSON file.

Syntax	Description
jsonwrite("filename", var);	Writes the variable "var" to a json file. The variable can be declared in the command and can be a struct, cell, matrix, or string.

Example

The following code example shows how to write the variable "a" to a json file.

# Create a variable a 
a = [1+2i, 3+4i];
jsonwrite("test_jsonwrite.json", a);

Creates the following json file.

{
"_complex" : true,
"_data" : [ 1.0, 2.0, 3.0, 4.0 ],
"_size" : [ 1, 2 ],
"_type" : "matrix"
}

The following code example shows how to define and write a struct to a json file with the jsonwrite command.

jsonwrite("test_jsonwrite.json", {"a":1, "b":"a string"});

Creates the following json file.

{
"a" : 1.0,
"b" : "a string"
}

jsonwrites - Script command

Writes the provided argument in a JSON formatted string. The string can be read back by the jsonreads command.

Syntax	Description
out = jsonwrites(argument);	Writes the provided argument in a JSON formatted string. The string can be read by the jsonreads command. The single argument must evaluate to either a Lumerical struct, cell, matrix, or string.

Example

The following code example shows how to save the struct "a" to a JSON list "str1".

a = {"b": {1, 2, 3}};
str1 = jsonwrites(a);

The string "str1" is:

?str1;
{
"b" : [ 1.0, 2.0, 3.0 ]
}

The following code example shows how to read the JSON list "str1" to the variable "b":

b = jsonreads(str1);

The struct to save to a JSON list can be defined in the line:

?jsonwrites(2);
2.0

?jsonwrites({1,2,3});
[1.0, 2.0, 3.0]

?jsonwrites('test');
"test"

?jsonwrites({'foo': 'bar'});
{
"foo": "bar"
}

LDF files

loaddata - Script command

Loads workspace variables or d-card data from a Lumerical data file (ldf) file. If any current variables exist with the same names as those in the file, the current values will be overwritten. This command will automatically detect if the .ldf file contains d-card or script workspace variable data and load them into the d-card deck or script workspace, respectively.

Syntax	Description
loaddata("filename");	Reads data script variables or d-card data from the specified file. This function does not return any data. Note: This function will check for the file in the current working directory. If the file to read from is in a different directory, either specify the full path or change the current working directory.

Syntax

Description

loaddata("filename");

Reads data script variables or d-card data from the specified file.

This function does not return any data.

Note: This function will check for the file in the current working directory. If the file to read from is in a different directory, either specify the full path or change the current working directory.

Examples

Loads file called mydata.ldf . Then use the workspace and showdata commands to see what workspace variables or d-cards have been created.

filename="mydata";
loaddata(filename);
?workspace;     # view workspace variables
?getdata;     # view d-cards (generally the complete set of data from a monitor)

savedata - Script command

Saves workspace variables to a Lumerical data file (ldf) file. To save monitor (D-card) data to an ldf file, see the savedcard function.

Syntax	Description
savedata("filename");	Saves all current variables to the specified file. This function does not return any data.
savedata("filename", var1, var2,...);	Saves only variables with the specified names to file.

Syntax

Description

savedata("filename");

Saves all current variables to the specified file.

This function does not return any data.

savedata("filename", var1, var2,...);

Saves only variables with the specified names to file.

Examples

This is a simple example that shows how to save two workspace variables to a .ldf data file.

x=1:10;
y=x^2;
savedata("x_squared_data", x, y);

This example shows a section of code that could be used to save some specific data from a monitor named xy_monitor. The data is first obtained with script functions such as getdata and transmission. These workspace variables are then saved with the savedata function.

Note that the complex file names can be created with the num2str command. This is useful when doing parameter sweeps where a unique file name is required for each point in the sweep.

# get data from the simulation to be saved
mname="xy_monitor";       # monitor name
x=getdata(mname,"x");      # position vectors associated with Ex fields
y=getdata(mname,"y");      # position vectors associated with Ex fields
Ex=getdata(mname,"Ex");     # Ex fields at monitor
T=transmission(mname);     # Power transmission through monitor
 
# save variables x, y, Ex, T and i to a data file
filename="results_"+num2str(i); # set filename. i could be a loop counter variable.
savedata(filename, x,y,Ex,T,i);

savedcard - Script command

FDTD MODE

Saves d-card data to a Lumerical data file (ldf) file. D-cards are generally used to store monitor data.

Data is saved in the nonorm state. See the units and normalization section of the reference guide for more information.

Syntax	Description
savedcard("filename");	Saves all current d-cards (local and global) to the specified ldf file. This function does not return any data.
savedcard("filename", "name1", "name2",...);	Saves only the d-cards with the specified names, "name1", "name2", etc.

Syntax

Description

savedcard("filename");

Saves all current d-cards (local and global) to the specified ldf file.

This function does not return any data.

savedcard("filename", "name1", "name2",...);

Saves only the d-cards with the specified names, "name1", "name2", etc.

Examples

This example shows how to save all data from the monitor named xy_monitor.

?getdata; # view all d-cards
savedcard("monitor_data","::model::xy_monitor");

Lookup tables

lookupclose - Script command

Closes a lookup table file previously created with a lookupopen command.

Syntax	Description
lookupclose ("filename");	Closes a file previously created with a lookupopen command. This command is required in order to close any file open by lookupopen .

Example

In order to create the lookup table “new.xml” with table named “new_extracted”:

#open file to write lookup table
lookupopen("new.xml", "new_extracted" );
...
#write design/extracted pair
lookupwrite( "new.xml", design, extracted );
...
#close file
lookupclose("new.xml");

lookupopen - Script command

Opens a file to write a lookup table.

Syntax	Description
lookupopen ("filename","table");	Opens a file to write a lookup table. This command is required before any calls to lookupwrite can be made.

Example

In order to create the lookup table “new.xml” with table named “new_extracted”:

#open file to write lookup table
lookupopen("new.xml", "new_extracted" );
...
#write design/extracted pair
lookupwrite( "new.xml", design, extracted );
...
#close file
lookupclose("new.xml");

lookupread - Script command

Finds the nearest extracted value from a file containing a lookup table of design and extracted parameters.

Syntax

Description

out = lookupread ("filename","table",design,"extracted");

Finds the nearest extracted value from a file containing a lookup table of design and extracted parameters. Parameter table is the name of the lookup table located inside the file, design is a cell containing multiple structures that define the design parameters to search, and extracted is the name of the parameter to be extracted. It will return the value located at the nearest design parameters.

out = lookupread ("filename");

Returns a script object, in this case a cell array containing all the contents of the xml file.

Example

To load the coupling length index associated to a coupler gap:

#design cell containing design/layout parameters (input parameter to search)#“gap” is the name of the property in the file

w_gap=3.5e-07;
design = cell(1);
design{1} = struct;
design{1}.name = "gap";
design{1}.value = w_gap;
#read coupling length from file (using design as input search “coupling_length”)
cl=lookupread( "coupler_map.xml", "coupler_extracted", design, "coupling_length" );
?c1
7.18624026618721e-06

where “coupler_map.xml” is a lookup table containing a map between coupler gap and coupling length values:

?xml version="1.0" encoding="UTF-8"?
<lumerical_lookup_table version="1.0" name = "coupler_extracted">
  <association>
    <design>
      <value name="gap" type="double">3.5e-07</value>
    </design>
    <extracted>
      <value name="coupling_length" type="double">7.18624026618721e-06</value> 
    </extracted> 
  </association>
...
</lumerical_lookup_table>

lookupwrite - Script command

Writes to a lookup table file with a design and an extracted parameter pair. This function must be called after lookupopen and before lookupclose .

Syntax

Description

out = lookupwrite ("filename","table",design, "extracted");

Writes to a lookup table with a design and an extracted parameter pair. The design and extracted parameters are cells that contain multiple structures, allowing for mapping between multiple design and extracted parameters. This function can be called multiple times, for each call the design and extracted parameters will be appended to the current file. This function must be called after lookupopen and before lookupclose .

out = lookupwrite ("filename");

Takes a script object, in this case a cell array containing all the contents of the xml file, and save it to a file.

Example

The script below maps two values of waveguide width and height to the effective index and group index.

design = cell(2);
#extracted contains neff and ng
extracted = cell(2);
#design (input parameters)
design{1} = struct;
design{1}.name = "width";
design{1}.value = 5.03333e-07;
design{2} = struct;
design{2}.name = "heigth";
design{2}.value = 2.18889e-07;
#extracted (output results)
extracted{1} = struct;
extracted{1}.name = "neff";
extracted{1}.value = 2.1;
extracted{2} = struct;
extracted{2}.name = "ng";
extracted{2}.value = 4.42;
#open file to write table
lookupopen( "new.xml", "new_extracted" );
#write first design/extracted pair
lookupwrite( "new.xml", design, extracted );
#second design/extracted pair
design{1}.value = 6.03333e-07;
design{2}.value = 1.18889e-07;
extracted{1}.value = 2.2;
extracted{2}.value = 4.45;
#write second design/extracted pair
lookupwrite( "new.xml", design, extracted );
#close file
lookupclose( "new.xml" );

where “new.xml” is a lookup table containing the table “new_extracted”

<?xml version="1.0" encoding="UTF-8"?>
<lumerical_lookup_table version="1.0" name = "new_extracted">
<association>
  <design>
    <value name="width" type="double">5.03333e-07</value>
    <value name="heigth" type="double">2.18889e-07</value>
  <design>
  <extracted>
    <value name="neff" type="double">2.1</value>
    <value name="ng" type="double">4.42</value>
  </extracted>
</association>
<association>  
  <design>
    <value name="width" type="double">6.03333e-07</value>
    <value name="heigth" type="double">1.18889e-07</value>
  <design>
  <extracted>
    <value name="neff" type="double">2.2</value>
    <value name="ng" type="double">4.45</value>
  </extracted>
</association>
</lumerical_lookup_table>

lookupreadtable - Script command

Returns an interpolated matrix from a file containing a lookup table of design and extracted parameters.

Syntax

Description

out = lookupreadtable ("filename","table",design,"extracted");

Returns an interpolated matrix from a file containing a lookup table of design and extracted parameters. Parameter table is the name of the lookup table located inside the file, design is a cell containing multiple structures that define the design parameters to search, and extracted is the name of the parameter to be extracted. It will return a matrix that contains multiple columns. The first column is the independent variable. e.g. frequency dependent transmission values.

Example

The script below loads the frequency dependent propagation properties of a bent waveguide:

filename = "waveguide.ixml";
table = "waveguide";
design = cell(1);
#design (input parameters)
design{1} = struct;
design{1}.name = "radius";
design{1}.value = 3e-6;
w_length = 1e-6;
M=lookupreadtable("waveguide.ixml", "waveguide", design, "Filename" );
# set the s-parameter in scripted element
setsparameter("port 2", "port 1", "propagation", M, w_length);
setsparameter("port 1", "port 2", "propagation", M, w_length);

where “waveguide.ixml” is a lookup table containing a map between waveguide ‘radius’ and ‘Filename’ containing frequency dependent propagation properties:

<?xml version="1.0" encoding="UTF-8"?>
<lumerical_lookup_table version="1.0" name = "waveguide">
  <association> 
    <design>
      <value name="radius" type="double">3e-06</value>
    </design> 
    <extracted>
      <value name="Filename" type="string">radius_3.txt</value> 
    </extracted>
  </association>
</lumerical_lookup_table>

For example, “radius_3.txt” file contains a matrix with frequency dependent propagation properties

2.315e+14552.62.787.071e+07
2.30918e+14552.72.717.076e+07
2.30335e+14543.32.737.075e+07
2.29753e+14543.32.767.076e+07
2.2917e+14544.72.787.062e+07
2.28588e+14545.52.727.061e+07
2.28006e+14546.62.717.064e+07
2.27423e+14544.22.737.061e+07
2.26841e+14533.12.747.063e+07
2.26258e+14532.22.757.069e+07

lookupreadvalue - Script command

Finds the value from a file containing a lookup table of design and extracted parameters.

Syntax	Description
out = lookupreadvalue ("filename","table",design,"extracted");	Find the value from a file containing a lookup table of design and extracted parameters. Parameter table is the name of the lookup table located inside the file, design is a cell containing multiple structures that define the design parameters to search, and extracted is the name of the parameter to be extracted. It will return the value is interpolated at the design parameters.

Example

In order to load the coupling length index associated to a coupler gap:

#design cell containing design/layout parameters (input parameter to search)
#“gap” is the name of the property in the file
w_gap=3.5e-07;
design = cell(1);
design{1} = struct;
design{1}.name = "gap";
design{1}.value = w_gap;
#read coupling length from file (using design as input search “coupling_length”)
cl=lookupreadvalue( "coupler_map.ixml", "coupler_extracted", design, "coupling_length" );
?cl
7.18624026618721e-06

where “coupler_map.ixml” is a lookup table containing a map between coupler gap and coupling length values:

<?xml version="1.0" encoding="UTF-8"?>
<lumerical_lookup_table version="1.0" name="coupler">
  <association>
    <design>
      <value name="gap" type="double">3.5e-07</value>
    </design>
    <extracted>
      <value name="coupling_length" type="double">7.18624026618721e-06</value>
    </extracted>
  </association>
</lumerical_lookup_table>

lookupreadnportsparameter - Script command

Returns an interpolated s-parameter cell from a file containing a lookup table of design and extracted parameters.

Syntax

Description

out = lookupreadnportsparameter ("filename","table",design,"extracted");

Returns an interpolated s-parameter cell from a file containing a lookup table of design and extracted parameters. Parameter table is the name of the lookup table located inside the file, design is a cell containing multiple structures that define the design parameters to search, and extracted is the name of the parameter to be extracted. S-parameter file format must be compatible with the ‘Optical N Port S-Parameter’.

Notes: The s-parameter files in the lookup-table should be in exact the same format. The s-parameter files shouldn't contain any header.

Example

Loads the s-parameters of a coupler depending on user defined design parameters:

filename = "coupler.ixml";
table = "coupler";
radius = 3e-06;
gap = 3e-07;
design = cell(2);
#design (input parameters)
design{1} = struct;
design{1}.name = "radius";
design{1}.value = radius;
design{2} = struct;
design{2}.name = "gap";
design{2}.value = gap; 
?M = lookupreadnportsparameter( filename, table, design, "out_filename" );
# set s-parameter to a S Parameter element
addelement("Optical N Port S-Parameter");
setvalue('SPAR_1','s parameters',M);

where “coupler.ixml” is a lookup table containing a map between coupler parameters and different s-parameters:

<?xml version="1.0" encoding="UTF-8"?>
<lumerical_lookup_table version="1.0" name = "coupler">
  <association>
    <design>
      <value name="radius" type="double">3e-06</value>
      <value name="gap" type="double">3e-07</value>
    </design>
    <extracted>
      <value name="out_filename" type="string">radius_3_gap_3.txt</value>
    </extracted>
  </association>
</lumerical_lookup_table>

For example “radius_3_gap_3.txt” file contains s-parameters for the ‘Optical N Port S-Parameter’ element

("port 1","TE",1,"port 1",1,"transmission")
(3,3)
 2.262580000000e+014 1.034036580296e-002 -2.629253819969e+000
 2.275690000000e+014 9.716591457652e-003 -2.734774978072e+000
 2.288790000000e+014 6.884340821788e-003 -2.838683842048e+000
("port 1","TE",1,"port 2",1,"transmission")
(3,3)
 2.262580000000e+014 9.847090174703e-001 1.376105202083e-001
 2.275690000000e+014 9.959778891317e-001 1.450376288706e-001
 2.288790000000e+014 1.002869828593e+000 1.483183421805e-001

lookupappend - Script command

Inserts a new association into an existing lookup table.

Syntax	Description
lookupappend("filename", "table", design, "extracted");	Inserts a new association into an existing lookup table.

Example

Loads the lookup table "coupler_map.ixml" and prints the cell array that containing all the contents of the .ixml file

clear;
tabCoupler = lookupread( "coupler_map.ixml" );
?toscript( tabCoupler );

where “coupler_map.ixml” is a lookup table containing a map between coupler parameters and different s-parameters:

tabCoupler=cell(1);
tabCoupler{1}=struct;
tabCoupler{1}.association=cell(1);
tabCoupler{1}.association{1}=struct;
tabCoupler{1}.association{1}.design=cell(1);
tabCoupler{1}.association{1}.design{1}=struct;
tabCoupler{1}.association{1}.design{1}.name='gap';
tabCoupler{1}.association{1}.design{1}.value=3.5e-007;
tabCoupler{1}.association{1}.extracted=cell(1);
tabCoupler{1}.association{1}.extracted{1}=struct;
tabCoupler{1}.association{1}.extracted{1}.name='coupling_length';
tabCoupler{1}.association{1}.extracted{1}.value=7.18624e-006;
tabCoupler{1}.name='coupler_extracted';

The following commands insert an object into the existing lookup table:

association=struct;
association.design=cell(1);
association.design{1}=struct;
association.design{1}.name='gap';
association.design{1}.value=5e-007;
association.extracted=cell(1);
association.extracted{1}=struct;
association.extracted{1}.name='coupling_length';
association.extracted{1}.value=9e-006;
# insert association at last position
tabCoupler{1}.association = insert( tabCoupler{1}.association, association, 2 );
# print updated values
?toscript(tabCoupler);
lookupwrite( "coupler_map.ixml", tabCoupler );

now the table prints as below:

tabCoupler=cell(1);
tabCoupler{1}=struct;
tabCoupler{1}.association=cell(2);
tabCoupler{1}.association{1}=struct;
tabCoupler{1}.association{1}.design=cell(1);
tabCoupler{1}.association{1}.design{1}=struct;
tabCoupler{1}.association{1}.design{1}.name='gap';
tabCoupler{1}.association{1}.design{1}.value=3.5e-007;
tabCoupler{1}.association{1}.extracted=cell(1);
tabCoupler{1}.association{1}.extracted{1}=struct;
tabCoupler{1}.association{1}.extracted{1}.name='coupling_length';
tabCoupler{1}.association{1}.extracted{1}.value=7.18624e-006;
tabCoupler{1}.association{2}=struct;
tabCoupler{1}.association{2}.design=cell(1);
tabCoupler{1}.association{2}.design{1}=struct;
tabCoupler{1}.association{2}.design{1}.name='gap';
tabCoupler{1}.association{2}.design{1}.value=5e-007;
tabCoupler{1}.association{2}.extracted=cell(1);
tabCoupler{1}.association{2}.extracted{1}=struct;
tabCoupler{1}.association{2}.extracted{1}.name='coupling_length';
tabCoupler{1}.association{2}.extracted{1}.value=9e-006;
tabCoupler{1}.name='coupler_extracted';

The following commands append a new association into the existing table:

clear;
design=cell(1);
design{1}=struct;
design{1}.name='gap';
design{1}.value=6e-007;
# create extracted parameter
extracted=cell(1);
extracted{1}=struct;
extracted{1}.name='coupling_length';
extracted{1}.value=9.9e-006;
# append to existing table
lookupappend( "coupler_map.ixml", "coupler_extracted", design, extracted );
# print contents
?toscript( lookupread( "coupler_map.ixml" ) );

Now the lookup table prints as below:

value=cell(1);
value{1}=struct;
value{1}.association=cell(3);
value{1}.association{1}=struct;
value{1}.association{1}.design=cell(1);
value{1}.association{1}.design{1}=struct;
value{1}.association{1}.design{1}.name='gap';
value{1}.association{1}.design{1}.value=3.5e-007;
value{1}.association{1}.extracted=cell(1);
value{1}.association{1}.extracted{1}=struct;
value{1}.association{1}.extracted{1}.name='coupling_length';
value{1}.association{1}.extracted{1}.value=7.18624e-006;
value{1}.association{2}=struct;
value{1}.association{2}.design=cell(1);
value{1}.association{2}.design{1}=struct;
value{1}.association{2}.design{1}.name='gap';
value{1}.association{2}.design{1}.value=5e-007;
value{1}.association{2}.extracted=cell(1);
value{1}.association{2}.extracted{1}=struct;
value{1}.association{2}.extracted{1}.name='coupling_length';
value{1}.association{2}.extracted{1}.value=9e-006;
value{1}.association{3}=struct;
value{1}.association{3}.design=cell(1);
value{1}.association{3}.design{1}=struct;
value{1}.association{3}.design{1}.name='gap';
value{1}.association{3}.design{1}.value=6e-007;
value{1}.association{3}.extracted=cell(1);
value{1}.association{3}.extracted{1}=struct;
value{1}.association{3}.extracted{1}.name='coupling_length';
value{1}.association{3}.extracted{1}.value=9.9e-006;
value{1}.name='coupler_extracted';

insert - Script command

Inserts an object into an existing cell in a lookup table.

Syntax	Description
out{1}.association = insert( out{1}.association, association, cell number );	Inserts an object into an existing cell.

Example

Loads the lookup table "coupler_map.ixml" and prints the cell array that containing all the contents of the .ixml file

clear;
tabCoupler = lookupread( "coupler_map.ixml" );
?toscript( tabCoupler );

where “coupler_map.ixml” is a lookup table containing a map between coupler parameters and different s-parameters:

tabCoupler=cell(1);
tabCoupler{1}=struct;
tabCoupler{1}.association=cell(1);
tabCoupler{1}.association{1}=struct;
tabCoupler{1}.association{1}.design=cell(1);
tabCoupler{1}.association{1}.design{1}=struct;
tabCoupler{1}.association{1}.design{1}.name='gap';
tabCoupler{1}.association{1}.design{1}.value=3.5e-007;
tabCoupler{1}.association{1}.extracted=cell(1);
tabCoupler{1}.association{1}.extracted{1}=struct;
tabCoupler{1}.association{1}.extracted{1}.name='coupling_length';
tabCoupler{1}.association{1}.extracted{1}.value=7.18624e-006;
tabCoupler{1}.name='coupler_extracted';

The following commands insert an object into the existing lookup table

association=struct;
association.design=cell(1);
association.design{1}=struct;
association.design{1}.name='gap';
association.design{1}.value=5e-007;
association.extracted=cell(1);
association.extracted{1}=struct;
association.extracted{1}.name='coupling_length';
association.extracted{1}.value=9e-006;
# insert association at last position
tabCoupler{1}.association = insert( tabCoupler{1}.association, association, 2 );
# print updated values
?toscript(tabCoupler);
lookupwrite( "coupler_map.ixml", tabCoupler );

now the table prints as below:

tabCoupler=cell(1);
tabCoupler{1}=struct;
tabCoupler{1}.association=cell(2);
tabCoupler{1}.association{1}=struct;
tabCoupler{1}.association{1}.design=cell(1);
tabCoupler{1}.association{1}.design{1}=struct;
tabCoupler{1}.association{1}.design{1}.name='gap';
tabCoupler{1}.association{1}.design{1}.value=3.5e-007;
tabCoupler{1}.association{1}.extracted=cell(1);
tabCoupler{1}.association{1}.extracted{1}=struct;
tabCoupler{1}.association{1}.extracted{1}.name='coupling_length';
tabCoupler{1}.association{1}.extracted{1}.value=7.18624e-006;
tabCoupler{1}.association{2}=struct;
tabCoupler{1}.association{2}.design=cell(1);
tabCoupler{1}.association{2}.design{1}=struct;
tabCoupler{1}.association{2}.design{1}.name='gap';
tabCoupler{1}.association{2}.design{1}.value=5e-007;
tabCoupler{1}.association{2}.extracted=cell(1);
tabCoupler{1}.association{2}.extracted{1}=struct;
tabCoupler{1}.association{2}.extracted{1}.name='coupling_length';
tabCoupler{1}.association{2}.extracted{1}.value=9e-006;
tabCoupler{1}.name='coupler_extracted';

The following commands append a new association into the existing table:

clear;
design=cell(1);
design{1}=struct;
design{1}.name='gap';
design{1}.value=6e-007;
# create extracted parameter
extracted=cell(1);
extracted{1}=struct;
extracted{1}.name='coupling_length';
extracted{1}.value=9.9e-006;
# append to existing table
lookupappend( "coupler_map.ixml", "coupler_extracted", design, extracted );
# print contents
?toscript( lookupread( "coupler_map.ixml" ) );

Now the lookup table prints as below:

value=cell(1);
value{1}=struct;
value{1}.association=cell(3);
value{1}.association{1}=struct;
value{1}.association{1}.design=cell(1);
value{1}.association{1}.design{1}=struct;
value{1}.association{1}.design{1}.name='gap';
value{1}.association{1}.design{1}.value=3.5e-007;
value{1}.association{1}.extracted=cell(1);
value{1}.association{1}.extracted{1}=struct;
value{1}.association{1}.extracted{1}.name='coupling_length';
value{1}.association{1}.extracted{1}.value=7.18624e-006;
value{1}.association{2}=struct;
value{1}.association{2}.design=cell(1);
value{1}.association{2}.design{1}=struct;
value{1}.association{2}.design{1}.name='gap';
value{1}.association{2}.design{1}.value=5e-007;
value{1}.association{2}.extracted=cell(1);
value{1}.association{2}.extracted{1}=struct;
value{1}.association{2}.extracted{1}.name='coupling_length';
value{1}.association{2}.extracted{1}.value=9e-006;
value{1}.association{3}=struct;
value{1}.association{3}.design=cell(1);
value{1}.association{3}.design{1}=struct;
value{1}.association{3}.design{1}.name='gap';
value{1}.association{3}.design{1}.value=6e-007;
value{1}.association{3}.extracted=cell(1);
value{1}.association{3}.extracted{1}=struct;
value{1}.association{3}.extracted{1}.name='coupling_length';
value{1}.association{3}.extracted{1}.value=9.9e-006;
value{1}.name='coupler_extracted';

MAT (Matlab) file

matlabload - Script command

Load Matlab .mat data into workspace

Syntax	Description
matlabload("filename");	Load to the workspace the data of the specified .mat file.

Examples

This is a simple example that shows how to load to workspace from a .mat data file.

#this file has variables data1, data2, data3
matlabload("myData.mat");  
?workspace;
matrices:
 data1 data2 data3

matlabsave - Script command

Save Lumerical workspace variables to MATLAB .mat data files.

Syntax

Description

matlabsave("");

Save all workspace variables to a .mat file that has the same name as the simulation file.

This function does not return any data.

matlabsave("filename");

Saves all workspace variables to the specified .mat file.

matlabsave("filename", var1, ..., varN);

Saves the specified workspace variables to the .mat file.

Examples

Simple example:

x=1:10;
y=x^2;
matlabsave("x_squared_data", x, y);

Save data from a monitor named xy_monitor. The data is first obtained with script functions such as getdata and transmission. These workspace variables are then saved with the matlabsave function. Note that complex file names can be created with the num2str command. This is useful when doing parameter sweeps where a unique file name is required for each point in the sweep.

# get raw matrix data from the simulation
mname="xy_monitor";       # monitor name
x=getdata(mname,"x");      # position vectors associated with Ex fields
y=getdata(mname,"y");      # position vectors associated with Ex fields
Ex=getdata(mname,"Ex");     # Ex fields at monitor
T=transmission(mname);     # Power transmission through monitor
 
# save matrix variables x, y, Ex, T and i to a data file
i=1;
filename="results_"+num2str(i); # set filename. i could be a loop counter variable.
matlabsave(filename, x,y,Ex,T,i);

Save a Lumerical dataset (eg. Electric field vs x,y,z,f) to a .mat file. Lumerical datasets will be imported into Matlab using the struct data type.

# get electric field dataset from the simulation
mname="xy_monitor";       # monitor name
E=getresult(mname,"E");     # E fields at monitor
 
# save dataset to mat file
filename="ElectricField";
matlabsave(filename, E);

matlabsavelegacy - Script command

Save workspace data to Matlab .mat data using a legacy Matlab file format required for Matlab version 7.2 and earlier. This file format does not support matrices larger than 2GB.

The command syntax is the same as the standard matlabsave command. See matlabsave for details.

Process files

saveprocessfile - Script command

Exports the process information in a layer builder object as a process file. The command only functions properly when a layer builder object is included in the simulation and is selected.

Syntax	Description
saveprocessfile("process_example.lbr", options);	Exports the process information in the currently selected layer builder object to a process file named "process_example". The additional (optional) argument options is a struct with field "export materials", which is a Boolean that defines if the material properties are included or not in the process file.

Example

select("layer group"); # select layer builder object
saveprocessfile("new_process_file.lbr", {"export materials": true}); # include material properties in process file

Please refer this article for more details.

PSF folder

setpsfoutput - Script command

Specifies the location of the PSF folder and avoids using the netlist location as a reference in the co-simulation.

By default, INTERCONNECT uses the netlist path to create the PSF path. The setpsfoutput command allows the users to specify a location of the PSF folder instead of using the default netlist path.

Syntax	Description
setpsfoutput("path")	Specifies the location of the PSF folder.

Example

The following script command will import netlist, save file and save output data to a PSF folder in 3 different locations.

static const char* InitScript =
"new;"
"historyoff;"
"setpsfoutput(\"%path3%\");
"importnetlist(\"%path1%\");"
"save(\"%path2%\");"
"edacosimulation;"
"setnamed('::Root Element','simulation output','psf');"
"runinitialize;";

SPICE Netlist

importnetlist - Script command

This script command can import an optical SPICE netlist.

Syntax	Description
importnetlist("compound name", "filename");	imports an optical SPICE netlist. The "compound name" is optional, if not specified, the Root Element level circuit configuration will be imported; if specified, the sub-circuit will be imported to this specified compound.

Parameter		Type	Description
compound name	optional	string	name of the compound
filename	required	string	name of the netlist.

exportnetlist - Script command

Export a netlist for the current circuit.

Syntax

Description

exportnetlist;

exportnetlist (filename);

exportnetlist (element,filename,overwrite=true);

Export a netlist for the current circuit. ‘filename’ is the output netlist name, ‘element’ is the compound element to be exported. If ‘overwrite’ is true, any existing netlist file with the same name as ‘filename’ will be overwritten. If ‘element’ is not provided, the currently selected compound element will be exported, otherwise the root element will be exported.

Example

>exportnetlist;
>exportnetlist("circuit.spi");

STL files

readstltriangles - Script command

Imports a matrix of vertex positions from an STL file.

Syntax

Description

out=readstltriangles("filename.stl",scaling_factor);

Returns an Mx3 matrix with vertices from all STL triangles from the specified STL file.

scaling_factor: An STL file does not contain unit data. To import data in units of microns, set this value to 1e-6. For nanometers, set this value to 1e-9.

Example

The following script command will read the STL file named "sample_file.stl" and save the vertex positions assuming units of micron.

vtx = readstltriangles("sample_file.stl",1e-6);

Tecplot files

tecplotread - Script command

DGTD CHARGE HEAT FEEM

Imports data from Tecplot formatted file (text).

Syntax	Description
? tecplotread('filename.dat');	List all zones ( domains) in the data file.
? tecplotread('filename.dat','zonename');	List all of the data fields associated with the zone.
out = tecplotread('filename.dat','zonename','dataname');	Retrieve the data as an array

Example

The following example shows how the tecplotread command can be used to import data from these files into CHARGE. Special field “FETriangle” represents the triangulation and X and Y coordinates of mesh are treated as node data. Names and units depend on original data source but we must convert units to SI (m).

The first part of the tecplot_import_diode.lsf file reads the data from the example_diode_tecplot.dat file. The following two lines in the script reads in the names of the zones and the data available in the zones of the tecplot file.

filename = 'example_diode_tecplot.dat';
zonename = 'Silicon';
?"Available zones: " + tecplotread(filename);
?"Data in zone " + zonename + ": " + tecplotread(filename,zonename);

The next few lines read in the information about the finite element grid. Here t is the connectivity matrix and x, y are the vertex matrices. Notice the coordinate data is converted from units of micron to meter.

t = tecplotread(filename,zonename,'FETriangle');
x = 1e-6*tecplotread(filename,zonename,'X [um]'); # convert to SI from um to m
y = 1e-6*tecplotread(filename,zonename,'Y [um]'); # convert to SI, invert

The following lines then read the doping data.

NA_name = 'NA [1/cm3]';
ND_name = 'ND [1/cm3]';
NA = 1e6*tecplotread(filename,zonename,NA_name); # convert to SI (cm^-3 -- m^-3)
ND = 1e6*tecplotread(filename,zonename,ND_name); # convert to SI (cm^-3 -- m^-3)

After reading the data, the code creates unstructured datasets for the doping data and creates geometries and import doping objects. The same task can be performed using the Dataset builder in CHARGE once the data has been imported.

Text files or standard output

readdata - Script command

Reads a file with data in a row/column format. User can import numerical values stored in text files with the readdata command. The data must be correctly formatted so each row has the same number of columns. Readdata will ignore any line that begins with a letter. The supported file format is ASCII.

Syntax

Description

M=readdata("filename.txt");

Will load the text file filename into matrix variable M. Any lines starting with a letter are ignored.

Examples

If you have a text file called testfile.txt with the following data:

Time Value

0.0 3.2e-6

1.0 2.8e10

2.0 4.1e5

3.0 3.3

The first rows contains the column headers, and the next four rows contain data. In this case, readdata will ignore the first line, and import the data as a 4x2 matrix.

M=readdata("testfile.txt");
?M;
result: 
0 3.2e-006 
1 2.8e+010 
2 4.1e+005 
3 3.3

write - Script command

Writes string variables to text files or to standard output.

Typically the write command is used to output data to a text file. If the specified file does not exist, it will be created. If it does exist, then the output string will either be appended to the end of the file or overwrite the file. The write command will automatically add a new line character at the end of the string.

On Linux systems only, the write command will output to the standard output (stdout) if a filename is not specified.

Syntax

Description

write(my_string);

Write my_string to the standard output (Linux only).

write("testfile.txt", my_string, option);

Will write the contents of the string variable my_string to testfile.txt. The file "testfile.txt" will be created if it does not exist.

option: can be "append" or "overwrite", to append the variable my_string to the end of the file or overwrite the file, respectively. If option is not provided, "append" will be used by default.

This function does not return any data.

Examples

Write an array of numbers to a text file. If you want to overwrite the file, use the "overwrite" option in the command.

a=linspace(0,2*pi,9);
write("testfile.txt",num2str(a), "overwrite");

The write command can output 2D matrices in a single command. Each column will be separated with a TAB character.

# define the variables to export
a=linspace(0,2*pi,9);
b=sin(a);
# combine both vectors into a single 2D matrix to be output to file
data_to_print=[a,b];
# write the data to the file
write("testfile.txt",num2str(data_to_print));

Generally, more complicated formatting is required. For example, suppose you want to have a header section that describes what the variables are. You also want to use comma separated columns (CSV), rather than TAB separated. Finally, you want to output the full double precision numbers, rather than just the first 5 digits.

# define the variables to export
a=linspace(0,pi,9);
b=sin(a);
# remove the file if it already exists
rm("testfile.txt");
# write the file header
write("testfile.txt","theta, sin(theta)");
# set num2str() to return 16 digits of precision
format long;
# write the data to the file
for (i=1:length(a) ) {
 str= num2str(a(i))+", "+num2str(b(i));
 write("testfile.txt",str);
}

The contents of testfile.txt will be:

theta, sin(theta)

0.0000000000000000, 0.0000000000000000

0.3926990816987241, 0.3826834323650898

0.7853981633974483, 0.7071067811865475

1.178097245096172, 0.9238795325112867

1.570796326794897, 1.000000000000000

1.963495408493621, 0.9238795325112867

2.356194490192345, 0.7071067811865476

2.748893571891069, 0.3826834323650899

3.141592653589793, 1.224646799147353e-016

Touchstone files

touchstoneload - Script command

Loads passive network data from a file containing Touchstone file formatted s-parameters. For more information about the Touchstone specification refer to this page.

Syntax	Description
out = touchstoneload (filename);	It returns a matrix where the first column contains the frequency values in Hz. S-parameters are returned using MA format, where M is the magnitude and A is the angle in radians.

Example

In this simple example, an s2p formatted touchstone file is loaded.

#filename PA3-110.s2p
out=touchstoneload('PA3-110.s2p');
#display loaded values
?out
result: 
2e+009 0.933287 -0.363001 0.01969 0.641089 0.000111993 1.32332 0.978723 -0.583973 
3e+009 0.930915 -0.519211 0.0985939 0.0471047 0.000391381 -1.06654 0.950211 -0.84896 
4e+009 0.930101 -0.670744 0.246948 -0.680015 0.000315715 1.6003 0.903597 -1.08584 
5e+009 0.926808 -0.840421 0.716968 -2.01287 0.000155772 -0.796779 0.887657 -1.24546 
6e+009 0.899653 -0.98587 0.426378 2.38857 0.00010399 -1.82364 0.914271 -1.43473 
...

VTK files

vtksave - Script command