7 Scripting Language
7.1.27 Excape key
Interrupts a script or long block of commands.
Syntax Description
ESCAPE key To interrupt a script file from running or a long block of commands from executing. A warning will be generated. Sometimes you may need to press escape several times,
109 119 119 115 117 117
109 120 120
or hold it down to interrupt the script.
See Also
System level , break , pause
7.1.28 format
The two format commands toggle the script interpreter between 2 output precision states. The commands print (?) and num2str() use this state to determine how many digits of precision to output.
Syntax Description
format long; Set script interpreter to 16 digits of precision. format short; Set script interpreter to 6 digits of precision.
See Also
System level , num2str , ?
7.1.29 loaddata
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.
Syntax Description
loaddata("filename"); Reads data script variables or d-card data from the specified file.
This function does not return any data.
See Also
System level , savedata , savedcard , workspace , load , fileexists
7.1.30 savedata
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.
109 120 120
109 175 157
savedata("filename", var1, var2,...);
Saves only variables with the specified names to file.
See Also
System level , savedcard , loaddata , workspace , matlabsave
7.1.31 savedcard
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 no norm 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.
See Also
System level , savedata , loaddata , matlabsave
7.1.32 readdata
You can import numerical values stored in text files with the readdata command. This command will read a file with data in a row/column format. 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.
Syntax Description
M=readdata("filename.txt"); Will load the text file filename into matrix variable M. Any lines starting with a letter are ignored.
See Also
System level , rm , write , str2num , findstring , replace , replacestring ,
substring , fileexists
109 122 121 136 124
109 121 121 124
109 114 123 176 177 177 178
7.1.33 write
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 be appended to the end of 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);
Will write the contents of the string variable my_string to testfile.txt.
This function does not return any data.
See Also
System level , readdata , rm , num2str , ? , endl , format , fileexists
7.1.34 asapexport
Exports the desired monitor to a file for interfacing with BRO's ASAP. These files are called fld files. The monitor must be a frequency power or a frequency profile monitor.
This command is available in FDTD and MODE.
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.
See Also
System level , asapload , asapimport , addimportedsource
109 122 114 175 157 157 121 117
7.1.35 asapload
Load 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
This command is available in FDTD and MODE.
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.
See Also
System level , asapexport , asapimport , addimportedsource , fileexists
7.1.36 asapimport
Import 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.
This command is available in FDTD only.
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.
See Also
System level , asapexport , asapload , addimportedsource , fileexists
7.1.37 matlabsave
Save workspace data to Matlab .mat data files.
Note: On some Windows computers with a newer version of MATLAB installed, the
109 123 124 217 117
matlabsave script command will cause the GUI to crash. We are working to resolve the problem. Until this issue is resolved, there are two potential solutions:
- downgrade to MATLAB 2010B
-use the matlabsavelegacy script command.
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.
See Also
System level , matlabput , matlabsavelegacy , matlabload , vtksave
7.1.38 matlabsavelegacy
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.
See Also
System level , matlabsave
7.1.39 matlabload
Load Matlab .mat data into workspace
Syntax Description
matlabload("filename"); Load to the workspace the data of the specified .mat file.
See Also
System level , matlabput , matlabsavelegacy , matlabsave ,
7.1.40 matlab
Runs a MATLAB command from the Lumerical script prompt. This gives access to extended mathematical and visualization functionality from the Lumerical script
environment. If the MATLAB script integration is not enabled, this function will return an error.
109 127 125 125 128
124
109 124
The first time a MATLAB function (matlab, matlabget or matlabput) is called, a MATLAB session will be started and a connection will be established with the Lumerical scripting environment. Once this connection is established, MATLAB commands can be run using the matlab function. It is important to understand that the MATLAB and the Lumerical script variable workspaces are completely separate and independent. A MATLAB command cannot act on a variable defined in the Lumerical workspace, and vice-versa. Variables must be passed between the workspaces using the matlabget and matlabput functions. At any time you may examine the MATLAB workspace or interact with the MATLAB environment by typing commands at the MATLAB script prompt.
The output from the MATLAB commands will be printed at the Lumerical script prompt. One limitation of the matlab function is that no error reporting is provided to either the Lumerical script prompt or the MATLAB prompt. MATLAB commands should be tested by typing them directly into the MATLAB prompt before they are called from a Lumerical script. The output buffer length is roughly 1e5 characters. Additional output will be truncated.
When you have a long sequence of MATLAB commands, you may find it more convenient to save them in a MATLAB m-file. Then, you can simply call the m-file by running a single command.
Setup instructions and system requirements for the MATLAB script integration feature can be found in the online Knowledge Base. See the Setup and Configuration section of the Installation Guide. Additional tips (particularly for plotting data in Matlab) can be found in the MATLAB section of the online User Guide.
Syntax Description
matlab("command"); command: a string containing one or more valid MATLAB commands.
matlab(" command_1 command_2 ");
Multi-line strings can be used in script files to contain a block of MATLAB commands. Multi-line strings are not supported at the script command prompt.
See Also
7.1.41 matlabget
Copies a variable from the MATLAB workspace to the script variable workspace. The resulting variable will have the same name as the MATLAB variable, and will overwrite any existing variable with the same name. If the variable does not exist in MATLAB, the command will return an error. For more information, please see the matlab command description.
Note: Matlab script integration must be enabled in order to use this command. For more information on how to set this up see the Matlab script integration page.
Syntax Description
matlabget(var1, var2,...varN); The arguments to this command are one or more variable names that refer to variables in the MATLAB workspace. This function does not return any data.
See Also
System level , matlab , matlabput
7.1.42 matlabput
Copies a variable from the FDTD/MODE Solutions workspace to the MATLAB workspace. The resulting variable in the MATLAB workspace will have the same name as in FDTD/ MODE Solutions, and will overwrite any existing variable with the same name. If the variable does not exist in the Lumerical workspace, the command will return an error.
For more information, please see the matlab command description.
Syntax Description
matlabput(var1, var2,...varN); The arguments to this command are one or more variable names that exist in the Lumerical variable workspace. This function does not return any data.
See Also
System level , matlab , matlabget
7.1.43 copytoclipboard
Copies the selected objects into the system clipboard. Equivalent to 'Ctrl-C'.
Syntax Description
109 125 127
copytoclipboard Copies selected objects to the system clipboard
See Also
System level , pastefromclipboard , copy
7.1.44 pastefromclipboard
Paste the contents of the system clipboard into the layout environment. Equivalent to 'Ctrl- V'.
Syntax Description
pastefromclipboard Paste contents of system clipboard
See Also
System level , copytoclipboard , copy
7.1.45 debug
Opens the debug utility window.
This command is available in FDTD only.
Syntax Description
debug; Opens the debug utility window.
See Also System level
7.1.46 vtksave
The script command vtksave saves a Lumerical dataset into the VTK format. The command only saves rectilinear and unstructured datasets. The “filename” will have .vtr appended for rectilinear dataset, .vtu appended for unstructured dataset. The freely available data visualization program Paraview can then be used to create sophisticated plots of your data.
Syntax Description
vtksave(“filename”, dataset); Save the dataset in vtk file of the name specified.
See Also
System level , datasets , rectilineardataset , matlabsave , data visualization with ParaView (User Guide)
109 128 230
109 127 230
109
7.1.47 lookupread
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.
See Also
System level , lookupclose , lookupopen , lookupwrite
7.1.48 lookupopen
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.
See Also
System level , lookupclose , lookupread , lookupwrite
7.1.49 lookupclose
Closes a 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.
See Also
System level , lookupopen , lookupread , lookupwrite
109 129 129 130
109 129 129 130
7.1.50 lookupwrite
Writes to a lookup table a design and an extracted parameter pair.
Syntax Description
out = lookupwrite (filename, , design, extracted);
Writes to a lookup table 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.
See Also
System level , lookupclose , lookupopen , lookupread