DEVICE Reference Guide

DEVICE
Reference Guide
Release 3.1
Contents
Table of Contents
Part I New Features
11
1 New features
............................................................................................................
for version 1.5
11
2 New features
............................................................................................................
for version 2.0
12
3 New features
............................................................................................................
for version 3.1
13
Part II Solver physics
15
1 FDTD ............................................................................................................ 15
FDTD
.................................................................................................................................................
and Maxw ell's equations
16
Meshing
.................................................................................................................................................
in FDTD
18
2 Eigenmode
............................................................................................................
Solver
19
Meshing
.................................................................................................................................................
in the Eigenm ode solver
20
3 Propagator
............................................................................................................ 21
2.5D.................................................................................................................................................
FDTD
21
Eigenm
.................................................................................................................................................
ode expansion
23
Meshing
.................................................................................................................................................
in the propagator
23
4 INTERCONNECT
............................................................................................................ 24
Tim.................................................................................................................................................
e Dom ain Sim ulator
24
Frequency
.................................................................................................................................................
Dom ain Sim ulator
25
5 DEVICE
............................................................................................................ 25
System
.................................................................................................................................................
of Equations
25
Meshing
.................................................................................................................................................
in DEVICE
28
Part III CAD layout editor
29
1 Main title
............................................................................................................
bar
29
2 Toolbars
............................................................................................................ 30
Main
................................................................................................................................................. 30
Edit ................................................................................................................................................. 31
Mouse
.................................................................................................................................................
m ode
33
View
................................................................................................................................................. 34
Sim.................................................................................................................................................
ulation
35
Search
.................................................................................................................................................
bar
36
3 View ports
............................................................................................................ 36
4 Object............................................................................................................
Tree
37
Enable/Disable
.................................................................................................................................................
Sim ulation Object
37
5
6
7
8
9
Results............................................................................................................
View
Optimization
............................................................................................................
and Sweeps
Script ............................................................................................................
Prompt and Script Editor
Script ............................................................................................................
Workspace and Script Favorites
Changing
............................................................................................................
the CAD layout
Part IV Material database

2003 - 2013 Lumerical Solutions, Inc
38
38
38
39
39
42
Reference Guide
1 Material
............................................................................................................
database
42
2 Electrical
............................................................................................................
models
43
Conductors
................................................................................................................................................. 44
Insulators
................................................................................................................................................. 44
Sem.................................................................................................................................................
iconductors
44
3 Mesh order
............................................................................................................ 54
Part V Simulation objects
56
1 Structures
............................................................................................................ 58
Prim.................................................................................................................................................
itives
58
Geom
.................................................................................................................................................
etry tab
59
Material
.................................................................................................................................................
tab
59
Rotations
.................................................................................................................................................
tab
60
Graphical
.................................................................................................................................................
Rendering tab
60
Im port
.................................................................................................................................................
Data tab
60
Properties
.................................................................................................................................................
tab
65
Script
.................................................................................................................................................
tab
65
2 Simulation
............................................................................................................ 65
General
.................................................................................................................................................
tab
66
Mesh
.................................................................................................................................................
tab
67
Geom
.................................................................................................................................................
etry tab
67
Transient
.................................................................................................................................................
tab
67
Results
................................................................................................................................................. 68
Advanced
.................................................................................................................................................
options tab
68
Solver
.................................................................................................................................................
type
69
Ferm
.................................................................................................................................................
i statistics
70
3 Monitors
............................................................................................................ 70
General
.................................................................................................................................................
tab
71
Geom
.................................................................................................................................................
etry tab
72
4
5
6
7
Generation
............................................................................................................
Doping............................................................................................................
Contacts
............................................................................................................
Equation
............................................................................................................
interpreter
Part VI Running simulations and analysis
72
72
74
76
77
1 Resource
............................................................................................................
Manager
77
Resources
.................................................................................................................................................
Advanced Options
79
2 Running
............................................................................................................
a simulation
80
3 Analysis
............................................................................................................
tools
81
Analysis
.................................................................................................................................................
tools and the sim ulation environm ent
82
Figure
.................................................................................................................................................
w indow s for plots and im ages
82
Data.................................................................................................................................................
export
83
Visualizer
................................................................................................................................................. 83
Results
.................................................................................................................................................
Manager
93
4 Optimization
............................................................................................................
and parameter sweeps
97
Contents
Optim
.................................................................................................................................................
ization
99
Particle
.................................................................................................................................................
Sw arm Optim ization
101
Param
.................................................................................................................................................
eter Sw eeps
103
Nested
.................................................................................................................................................
Sw eeps
104
Yield
.................................................................................................................................................
Analysis
105
Part VII Scripting Language
108
1 System
............................................................................................................ 109
new
.................................................................................................................................................
project
112
new
.................................................................................................................................................
m ode
112
save
................................................................................................................................................. 113
load
................................................................................................................................................. 113
del................................................................................................................................................. 113
rm................................................................................................................................................. 114
dir................................................................................................................................................. 114
ls ................................................................................................................................................. 114
cd ................................................................................................................................................. 115
pw.................................................................................................................................................
d
115
cp ................................................................................................................................................. 115
m v................................................................................................................................................. 116
exit
................................................................................................................................................. 116
system
................................................................................................................................................. 116
fileexists
................................................................................................................................................. 117
currentfilenam
.................................................................................................................................................
e
117
filebasenam
.................................................................................................................................................
e
117
fileextension
................................................................................................................................................. 118
filedirectory
................................................................................................................................................. 118
getcom
.................................................................................................................................................
m ands
118
Run
.................................................................................................................................................
script
118
getpath
................................................................................................................................................. 119
addpath
................................................................................................................................................. 119
w hich
................................................................................................................................................. 119
pause
................................................................................................................................................. 120
break
................................................................................................................................................. 120
Excape
.................................................................................................................................................
key
120
form
.................................................................................................................................................
at
121
loaddata
................................................................................................................................................. 121
savedata
................................................................................................................................................. 121
savedcard
................................................................................................................................................. 122
readdata
................................................................................................................................................. 122
w rite
................................................................................................................................................. 123
asapexport
................................................................................................................................................. 123
asapload
................................................................................................................................................. 124
asapim
.................................................................................................................................................
port
124
m atlabsave
................................................................................................................................................. 124
m atlabsavelegacy
................................................................................................................................................. 125
m atlabload
................................................................................................................................................. 125
m atlab
................................................................................................................................................. 125
m atlabget
................................................................................................................................................. 127
m atlabput
................................................................................................................................................. 127
Reference Guide
copytoclipboard
................................................................................................................................................. 127
pastefrom
.................................................................................................................................................
clipboard
128
debug
................................................................................................................................................. 128
vtksave
................................................................................................................................................. 128
lookupread
................................................................................................................................................. 129
lookupopen
................................................................................................................................................. 129
lookupclose
................................................................................................................................................. 129
lookupw
.................................................................................................................................................
rite
130
2 Manipulating
............................................................................................................
variables
130
= ................................................................................................................................................. 132
: ................................................................................................................................................. 132
[] ................................................................................................................................................. 132
% ................................................................................................................................................. 133
linspace
................................................................................................................................................. 133
m atrix
................................................................................................................................................. 133
randm
.................................................................................................................................................
atrix
133
randnm
.................................................................................................................................................
atrix
134
histogram
................................................................................................................................................. 134
m eshgridx
................................................................................................................................................. 134
m eshgridy
................................................................................................................................................. 135
m eshgrid3dx
................................................................................................................................................. 135
m eshgrid3dy
................................................................................................................................................. 135
m eshgrid3dz
................................................................................................................................................. 136
m eshgrid4d
................................................................................................................................................. 136
clear
................................................................................................................................................. 136
w orkspace
................................................................................................................................................. 136
Accessing
.................................................................................................................................................
and assigning m atrix elem ents
137
Matrix
.................................................................................................................................................
operators
138
Pre-defined
.................................................................................................................................................
constants
138
m atrixdataset
................................................................................................................................................. 139
rectilineardataset
................................................................................................................................................. 139
addparam
.................................................................................................................................................
eter
140
addattribute
................................................................................................................................................. 140
getparam
.................................................................................................................................................
eter
140
getattribute
................................................................................................................................................. 141
eye................................................................................................................................................. 141
Datasets
................................................................................................................................................. 141
struct
................................................................................................................................................. 146
cell................................................................................................................................................. 147
unstructureddataset
................................................................................................................................................. 147
3 Operators
............................................................................................................ 148
. ................................................................................................................................................. 149
* ................................................................................................................................................. 150
/ ................................................................................................................................................. 150
+ ................................................................................................................................................. 150
- ................................................................................................................................................. 150
^ ................................................................................................................................................. 151
== ................................................................................................................................................. 151
alm.................................................................................................................................................
ostequal
151
!= ................................................................................................................................................. 152
Contents
<= ................................................................................................................................................. 152

>= ................................................................................................................................................. 152
< ................................................................................................................................................. 153
> ................................................................................................................................................. 153
& ................................................................................................................................................. 153
and
................................................................................................................................................. 153
| ................................................................................................................................................. 154
or ................................................................................................................................................. 154
! ................................................................................................................................................. 154
~ ................................................................................................................................................. 155
" ................................................................................................................................................. 155
' ................................................................................................................................................. 156
endl
................................................................................................................................................. 157
? ................................................................................................................................................. 157
com
.................................................................................................................................................
m ents
157
4 Functions
............................................................................................................ 157
sin................................................................................................................................................. 162
cos................................................................................................................................................. 162
tan................................................................................................................................................. 162
asin
................................................................................................................................................. 162
acos
................................................................................................................................................. 163
atan
................................................................................................................................................. 163
atan2
................................................................................................................................................. 163
real
................................................................................................................................................. 164
im ag
................................................................................................................................................. 164
conj
................................................................................................................................................. 164
abs................................................................................................................................................. 164
angle
................................................................................................................................................. 165
unw
.................................................................................................................................................
rap
165
log................................................................................................................................................. 165
log10
................................................................................................................................................. 165
sqrt
................................................................................................................................................. 166
exp
................................................................................................................................................. 166
size
................................................................................................................................................. 166
length
................................................................................................................................................. 166
pinch
................................................................................................................................................. 167
sum
................................................................................................................................................. 167
m ax
................................................................................................................................................. 168
m in
................................................................................................................................................. 168
dot................................................................................................................................................. 168
cross
................................................................................................................................................. 168
eig................................................................................................................................................. 169
m ult
................................................................................................................................................. 169
flip................................................................................................................................................. 170
perm
.................................................................................................................................................
ute
170
reshape
................................................................................................................................................. 170
inv................................................................................................................................................. 171
interp
................................................................................................................................................. 171
interptri
................................................................................................................................................. 172
spline
................................................................................................................................................. 172
Reference Guide
integrate
................................................................................................................................................. 173
integrate2
................................................................................................................................................. 173
find
................................................................................................................................................. 174
findpeaks
................................................................................................................................................. 174
transpose
................................................................................................................................................. 175
ctranspose
................................................................................................................................................. 175
num
.................................................................................................................................................
2str
175
str2num
................................................................................................................................................. 176
eval
................................................................................................................................................. 176
feval
................................................................................................................................................. 176
substring
................................................................................................................................................. 176
findstring
................................................................................................................................................. 177
replace
................................................................................................................................................. 177
replacestring
................................................................................................................................................. 178
splitstring
................................................................................................................................................. 178
fft ................................................................................................................................................. 178
fftw
................................................................................................................................................. 180
fftk................................................................................................................................................. 181
invfft
................................................................................................................................................. 182
czt................................................................................................................................................. 183
polyarea
................................................................................................................................................. 183
centroid
................................................................................................................................................. 184
polyintersect
................................................................................................................................................. 184
inpoly
................................................................................................................................................. 185
polygrow
................................................................................................................................................. 185
polyand
................................................................................................................................................. 186
polyor
................................................................................................................................................. 186
polydiff
................................................................................................................................................. 186
polyxor
................................................................................................................................................. 187
lineintersect
................................................................................................................................................. 187
linecross
................................................................................................................................................. 188
ceil................................................................................................................................................. 188
floor
................................................................................................................................................. 188
m od
................................................................................................................................................. 189
sign
................................................................................................................................................. 189
round
................................................................................................................................................. 189
rand
................................................................................................................................................. 190
lognrnd
................................................................................................................................................. 190
randn
................................................................................................................................................. 190
randreset
................................................................................................................................................. 191
finite
................................................................................................................................................. 191
solar
................................................................................................................................................. 191
stackrt
................................................................................................................................................. 192
m ean
................................................................................................................................................. 192
all ................................................................................................................................................. 192
any................................................................................................................................................. 193
var................................................................................................................................................. 193
std................................................................................................................................................. 194
m apfind
................................................................................................................................................. 194
quadtri
................................................................................................................................................. 195
expand
................................................................................................................................................. 195
Contents
norm
................................................................................................................................................. 196
5 Loop ............................................................................................................
and conditional statements
196
for................................................................................................................................................. 196
if ................................................................................................................................................. 197
6 Plotting
............................................................................................................
commands
197
plot
................................................................................................................................................. 198
plotxy
................................................................................................................................................. 199
polar
................................................................................................................................................. 200
polar2
................................................................................................................................................. 200
polarim
.................................................................................................................................................
age
201
histc
................................................................................................................................................. 202
legend
................................................................................................................................................. 202
im age
................................................................................................................................................. 202
visualize
................................................................................................................................................. 203
selectfigure
................................................................................................................................................. 204
setplot
................................................................................................................................................. 204
exportfigure
................................................................................................................................................. 204
closeall
................................................................................................................................................. 205
vectorplot
................................................................................................................................................. 205
7 Adding
............................................................................................................
Objects
205
sw.................................................................................................................................................
itchtolayout
208
layoutm
.................................................................................................................................................
ode
209
addgroup
................................................................................................................................................. 209
addstructuregroup
................................................................................................................................................. 209
addanalysisgroup
................................................................................................................................................. 210
addobject
................................................................................................................................................. 210
addcontact
................................................................................................................................................. 210
addcircle
................................................................................................................................................. 211
addcustom
................................................................................................................................................. 211
addim
.................................................................................................................................................
port
211
addpyram
.................................................................................................................................................
id
212
addpoly
................................................................................................................................................. 212
addrect
................................................................................................................................................. 212
addtriangle
................................................................................................................................................. 213
addring
................................................................................................................................................. 213
addsphere
................................................................................................................................................. 213
addsurface
................................................................................................................................................. 214
addfdtd
................................................................................................................................................. 214
addeigenm
.................................................................................................................................................
ode
214
addpropagator
................................................................................................................................................. 214
addm
.................................................................................................................................................
esh
215
addm
.................................................................................................................................................
ode
215
addm
.................................................................................................................................................
odesource
215
adddipole
................................................................................................................................................. 215
addgaussian
................................................................................................................................................. 216
addplane
................................................................................................................................................. 216
addtfsf
................................................................................................................................................. 216
addim
.................................................................................................................................................
portedsource
217
addindex
................................................................................................................................................. 217
addtim
.................................................................................................................................................
e
217
Reference Guide
addm
.................................................................................................................................................
ovie
218
addprofile
................................................................................................................................................. 218
createbeam
................................................................................................................................................. 218
adddevice
................................................................................................................................................. 219
adddope
................................................................................................................................................. 219
adddiffusion
................................................................................................................................................. 219
addim
.................................................................................................................................................
portdope
219
addbulkgen
................................................................................................................................................. 220
addim
.................................................................................................................................................
portgen
220
addgridattribute
................................................................................................................................................. 220
addelem
.................................................................................................................................................
ent
221
addm
.................................................................................................................................................
odeexpansion
222
addeffectiveindex
................................................................................................................................................. 222
addchargem
.................................................................................................................................................
onitor
222
addfieldm
.................................................................................................................................................
onitor
223
8 Manipulating
............................................................................................................
objects
223
groupscope
................................................................................................................................................. 226
deleteall
................................................................................................................................................. 226
delete
................................................................................................................................................. 227
selectall
................................................................................................................................................. 227
unselectall
................................................................................................................................................. 227
select
................................................................................................................................................. 227
selectpartial
................................................................................................................................................. 228
shiftselect
................................................................................................................................................. 228
shiftselectpartial
................................................................................................................................................. 229
flipelem
.................................................................................................................................................
ent
229
rotateelem
.................................................................................................................................................
ent
229
m ove
................................................................................................................................................. 229
copy
................................................................................................................................................. 230
addtogroup
................................................................................................................................................. 230
adduserprop
................................................................................................................................................. 231
set................................................................................................................................................. 231
setnam
.................................................................................................................................................
ed
232
setglobalm
.................................................................................................................................................
onitor
232
setglobalsource
................................................................................................................................................. 233
setm
.................................................................................................................................................
odes
233
setposition
................................................................................................................................................. 233
setrectangle
................................................................................................................................................. 234
getposition
................................................................................................................................................. 234
getrectangle
................................................................................................................................................. 234
get................................................................................................................................................. 235
runsetup
................................................................................................................................................. 235
getnum
.................................................................................................................................................
ber
236
getnam
.................................................................................................................................................
ed
236
getnam
.................................................................................................................................................
ednum ber
237
getglobalm
.................................................................................................................................................
onitor
237
getglobalsource
................................................................................................................................................. 237
getsolver
................................................................................................................................................. 238
haveproperty
................................................................................................................................................. 238
im portsurface
................................................................................................................................................. 238
Contents
im portsurface2
................................................................................................................................................. 240
im portnk
................................................................................................................................................. 241
im portnk2
................................................................................................................................................. 243
im portnkobfuscated
................................................................................................................................................. 245
im portbinary
................................................................................................................................................. 246
im portbinary2
................................................................................................................................................. 248
im portbinaryobfuscated
................................................................................................................................................. 250
updatesourcem
.................................................................................................................................................
ode
251
setsourcesignal
................................................................................................................................................. 252
updatem
.................................................................................................................................................
odes
253
clearsourcedata
................................................................................................................................................. 254
clearm
.................................................................................................................................................
odedata
254
seteigensolver
................................................................................................................................................. 255
geteigensolver
................................................................................................................................................. 256
redraw
................................................................................................................................................. 256
redraw
.................................................................................................................................................
off
257
redraw
.................................................................................................................................................
on
257
redraw
.................................................................................................................................................
m ode
257
setview
................................................................................................................................................. 258
getview
................................................................................................................................................. 259
orbit
................................................................................................................................................. 259
fram
.................................................................................................................................................
erate
260
undo
................................................................................................................................................. 260
redo
................................................................................................................................................. 260
addport
................................................................................................................................................. 261
rem
.................................................................................................................................................
oveport
261
connect
................................................................................................................................................. 262
disconnect
................................................................................................................................................. 262
setexpansion
................................................................................................................................................. 262
rem
.................................................................................................................................................
oveexpansion
263
setactivesolver
................................................................................................................................................. 263
getnam
.................................................................................................................................................
e
263
setnam
.................................................................................................................................................
e
263
im portdataset
................................................................................................................................................. 264
cleardataset
................................................................................................................................................. 264
9 Running
............................................................................................................
simulations
265
runparallel
................................................................................................................................................. 265
addjob
................................................................................................................................................. 266
runjobs
................................................................................................................................................. 266
clearjobs
................................................................................................................................................. 266
runsw
.................................................................................................................................................
eep
267
10 Measurement
............................................................................................................
and optimization data
267
getsw
.................................................................................................................................................
eepdata
268
getsw
.................................................................................................................................................
eepresult
269
getdata
................................................................................................................................................. 269
getresult
................................................................................................................................................. 270
runanalysis
................................................................................................................................................. 270
havedata
................................................................................................................................................. 271
haveresult
................................................................................................................................................. 271
havesw
.................................................................................................................................................
eepdata
272
10
Reference Guide
havesw
.................................................................................................................................................
eepresult
272
copydcard
................................................................................................................................................. 273
clearanalysis
................................................................................................................................................. 273
cleardcard
................................................................................................................................................. 274
getelectric
................................................................................................................................................. 274
getm
.................................................................................................................................................
agnetic
274
Read
.................................................................................................................................................
and w rite data to files
275
loadsw
.................................................................................................................................................
eep
275
savesw
.................................................................................................................................................
eep
275
11 Material
............................................................................................................
database
276
addm
.................................................................................................................................................
aterial
276
copym
.................................................................................................................................................
aterial
277
setm
.................................................................................................................................................
aterial
277
getm
.................................................................................................................................................
aterial
277
getindex
................................................................................................................................................. 278
getfdtdindex
................................................................................................................................................. 278
getm
.................................................................................................................................................
odeindex
279
getnum
.................................................................................................................................................
ericalperm ittivity
280
12 GDSII............................................................................................................ 281
gdsopen
................................................................................................................................................. 282
gdsclose
................................................................................................................................................. 282
gdsbegincell
................................................................................................................................................. 283
gdsendcell
................................................................................................................................................. 283
gdsaddpoly
................................................................................................................................................. 284
gdsaddcircle
................................................................................................................................................. 284
gdsaddrect
................................................................................................................................................. 285
gdsaddref
................................................................................................................................................. 286
gdsim
.................................................................................................................................................
port
286
13 User defined
............................................................................................................
GUIs
288
m essage
................................................................................................................................................. 288
new
.................................................................................................................................................
w izard
289
new
.................................................................................................................................................
w izardpage
289
w izardw
.................................................................................................................................................
idget
289
w izarddata
................................................................................................................................................. 290
runw
.................................................................................................................................................
izard
291
w izardgetdata
................................................................................................................................................. 291
killw
.................................................................................................................................................
izard
291
w izardoption
................................................................................................................................................. 292
fileopendialog
................................................................................................................................................. 292
filesavedialog
................................................................................................................................................. 292
14 Creating
............................................................................................................
your own script commands
293
Index
295
New Features
11
New Features
DEVICE is constantly being upgraded. See the following sections for a list of the latest
new features.
New features for version 1.5
1.1
11
12
13

New solver option
In the initial versions of the software, the Gummels method was used in the solver, in
which the voltage and charge were solved sequentially (one was used as a input to the
other) until the two were consistent. In DEVICE 1.5, the Newton solver has been
introduced, which solves for the charge and voltage simultaneously. The Newton solver is
more sensitive to the initial conditions (it may not converge), but will converge much faster
for a wider variety of problems if its given a good initial guess.
Advanced contact models

Several modifications
have been made to the
contact models for
DEVICE:
Lumped element
loads (R and C) can
now be added on
device terminals.
Custom
specification of DC
sweep bias voltages
is available.
Non-ohmic contacts
will use a Schottky
barrier model
accounting for
barrier lowering due
to the applied
electric field.
12
Reference Guide
Adaptive transient simulation

Transient simulations now employ adaptive time-stepping to optimally vary the simulation
interval while maintaining accuracy. Coupled with the full Newton solver, a wider variety of
transient simulations can now be performed efficiently with DEVICE. To view the new
settings associated with the transient simulation, consult the "Transient" tab in the Device
region properties. Here, the user may specify time step constraints, down-sampling, and
shuttering for optical generation objects.
Results selection
In the Device region properties, users now how the option to retain a reduced set of spatial
data. Under the "Results" tab, a list of all available results can be viewed, and may be
toggled on or off to reduce memory requirements. By default all results are included.
1.2

Results manager and Visualizer
The Results Manager 93 is a tool for analyzing simulation data. This includes a Results
View window which displays all the results for the simulation object that is currently
selected in the Object Tree. The Results Manager also includes a Script Workspace and a
Script Favorites window, providing additional GUI-based functionalities.
Also featured in DEVICE 2.0 is the more improved Visualizer 83 , which significantly
simplifies the process of visualizing simulation data. When used in conjunction, Results
Manager and the Visualizer provide a very useful and intuitive way of analyzing and
visualizing variables and results through the GUI, greatly reducing the need for scripting.
Datasets
Lumerical datasets are structured data objects that collect a set of related matrices into a
single convenient object. See Dataset introduction 141 for more information.
Yield analysis tool

A new yield analysis tool is available in the Optimization and Sweeps window. The yield
analysis tool gives users the ability to run extensive Monte Carlo analysis, sweeping
New Features
13
across multiple parameters to assess statistical variations of circuit elements on overall

circuit performance.
Please see the Yield analysis 105 page in the Reference Guide for more details, and the
Running a yield analysis task example in the User Guide.
Other new script commands

The following script functions were added in DEVICE 2.0. For more information, see the
function descriptions in the scripting section of the Reference Guide.
. operator 149 , addattribute 140 , addparameter 140 , eig 169 , debug 128 ,
getattribute 141 , getparameter 140 , getresult 270 , getsweepresult 269 ,
integrate2 173 , matrixdataset 139 , addmodeexpansion 222 , mult 169 ,
permute 170 rectilineardataset 139 , reshape 170
1.3

3D solver
DEVICE is now capable of simulating fully three dimensional geometries. The solver type
can be chosen by the user to be 2D or 3D. This means that arbitrary structures particularly
where slicing or averaging of imported 3D data is not valid can now be solved for in 3
dimensions.
Visualization
The visualizer has been updated for 3D simulations to allow the user to better view the
results, enabling image plots, arbitrary slices of the 3D geometry or line plots of various
types of data.
Field and charge monitors

A new object type, monitor, has been added to DEVICE. 2D/3D monitors can be placed
anywhere within the simulation region to record the total charge within the monitor and/or
electric field through the monitor boundaries.
Continue from previous solution

It is now possible to specify a project file that has already been run as a reference project
for solving another simulation. The initialization step in the solver can be skipped with this
feature, using the converged solution of the specified file. This will save a lot of time in
memory intensive simulations.
14
Reference Guide
Electron-hole density grid attribute

FDTD Solutions 8.7 and MODE Solutions 6.6 (and beyond) can import electron-hole
density data recorded on a finite-element mesh directly from a DEVICE simulation. This
approach, which offers significant improvement over the previous (n, k) import option,
reduces simulation memory requirements and interpolation errors.
XML lookup table support

As of version 3.0, users can simulate a wide range of device designs with Lumerical's
TCAD tools, the results of which get incorporated into an XML lookup table. This XML
lookup table can then be associated with a specific element as the basis for a validated
compact model within an INTERCONNECT project. Please see Parameter Extraction and
PDKs for detailed examples.
Export viewports to image

As of version 3.1, users can export CAD viewports into JPEG figures by selecting "View ->
Export view" from the main title bar.
new script commands

The following script functions were added in DEVICE 3.0. For more information, see the
function descriptions in the scripting section of the Reference Guide.
all, any, quadtri, unstructuredataset, loadsweep, savesweep,
var, std
Solver physics
15
Solver physics
This chapter describes the basic physics and algorithms used in Lumerical's various
'Physics' based solvers:
FDTD Solutions
15
The Finite-Difference Time-Domain method, which is the method behind both FDTD
Solutions and MODE Solutions' Propagator.
MODE Solutions Eigenmode Solver
19
The method behind MODE Solutions' Eigenmode Solver and FDTD Solutions' Integrated
MODE Solver.
MODE Solutions Propagator 21

The method behind MODE Solutions' omnidirectional propagator for planar integrated
systems.
INTERCONNECT
24
The method behind Lumerical's INTERCONNECT circuit simulator.
DEVICE
25
The method behind Lumerical's DEVICE electronic device simulator.
2.1
FDTD
The finite-difference time-domain (FDTD) method1,2,3 is a state-of-the-art method for solving
Maxwell's equations in complex geometries. Being a direct time and space solution, it
offers the user a unique insight into all types of problems in electromagnetics and
photonics. In addition, FDTD can also obtain the frequency solution by exploiting Fourier
transforms, thus a full range of useful quantities can be calculated, such as the complex
Poynting vector and the transmission / reflection of light.
This section will introduce the basic mathematical and physics formalism behind the FDTD
algorithm used in FDTD Solutions and MODE Solutions' propagator, starting from the linear
Maxwell's equations. The simulator can be used for advanced research and development or
as an ideal teaching and learning environment in photonics, optics, and electromagnetics.
See the FDTD Numerical methods video for additional information: http://www.lumerical.
com/support/courses/fdtd_numerical_methods/video.html
16
Reference Guide
1 Dennis M. Sullivan, Electromagnetic simulation using the FDTD method. New York: IEEE
Press Series, (2000).
2 Allen Taflove, Computational Electromagnetics: The Finite-Difference Time-Domain
Method. Boston: Artech House, (2005).
3 Stephen D. Gedney, Introduction to the Finite-Difference Time-Domain (FDTD) Method for
Electromagnetics. Morgan & Claypool publishers, (2011).
2.1.1 FDTD and Maxwell's equations

FDTD solves Maxwell's curl equations in non-magnetic materials:
D
t
D( )
H
t
H
0 r
( )E( )
where H, E, and D are the magnetic, electric, and displacement fields, respectively, while
r
( )
is the complex relative dielectric constant (
( )
n2
, where n is the refractive
index).
In three dimensions, Maxwell equations have six electromagnetic field components: Ex , Ey ,
Solver physics
17
Ez and Hx , Hy , and Hz. If we assume that the structure is infinite in the z dimension and
that the fields are independent of z, specifically that
r
( , x, y , z )
E
z
H
z
( , x, y )
then Maxwell's equations split into two independent sets of equations composed of three
vector quantities each which can be solved in the x-y plane only. These are termed the TE
(transverse electric), and TM (transverse magnetic) equations. We can solve both sets of
equations with the following components:
TE: Ex , Ey , Hz
TM: Hx , Hy , Ez
For example, in the TM case, Maxwell's equations reduce to:
Dz
t
Hy
x
Dz ( )
0 r
Hx
t
Hy
t
Hx
y
1
0
1
0
( ) Ez ( )
Ez
y
Ez
x
FDTD Solutions can solve the two and three dimensional Maxwell's equations in dispersive
media and some simple non-linear media, where the user can specify arbitrary geometric
structures and various input excitation sources. The two dimensional FDTD simulator
solves the TE and/or TM Maxwell equations.
FDTD is a time domain technique, meaning that the electromagnetic fields are solved as a
function of time. In general, FDTD Solutions is used to calculate the electromagnetic fields
as a function of frequency or wavelength by performing Fourier transforms during the
simulation. This allows it to obtain complex-valued fields and other derived quantities such
as the complex Poynting vector, normalized transmission, and far field projections as a
function of frequency or wavelength. The field information can be returned in two different
normalization states, please see the section on frequency domain normalization for more
details.
18
Reference Guide
Dispersive materials with tabulated refractive index (n,k) data as a function of wavelength
can be solved using the multi-coefficient models with auto-fitting. Alternatively, specific
theoretical models such as Plasma (Drude), Debye or Lorentz can be used. See the
chapter on the Material Database 42 for details.
Boundary conditions are very important in electromagnetics and simulation techniques.
FDTD Solutions/propagator supports a range of boundary conditions, such as PML,
periodic, and Bloch. See the boundary conditions section here for the complete list.
Sources are another important component of a simulation. FDTD Solutions/propagator
supports a number of different types of sources such as point dipoles, beams, plane waves,
a total-field scattered-field (TFSF) source, a guided-mode source for integrated optical
components, and an imported source to interface with external photonic design softwares.
Detailed information about each of these sources is contained in the Radiation sources
section.
Unless otherwise specified, all quantities in FDTD Solutions/propagator are calculated in SI
units. Please see Units and Normalization for more information.
The online User Guide at http://docs.lumerical.com/en/fdtd/knowledge_base.html has many
more details about the physics of FDTD and how to obtain advanced results. Please see,
for example, the sections on coherence, and far field calculations in the online User Guide.
2.1.2 Meshing in FDTD

FDTD Solutions uses a rectangular, Cartesian style mesh, like the one shown in the
following screenshot. It's important to understand that of the fundamental simulation
quantities (material properties and geometrical information, electric and magnetic fields) are
calculated at each mesh point. Obviously, using a smaller mesh allows for a more
accurate representation of the device, but at a substantial cost. As the mesh becomes
smaller, the simulation time and memory requirements will increase. FDTD Solutions
provides a number of features, including the conformal mesh algorithm, that allow you to
obtain accurate results, even when using a relatively coarse mesh.
By default, the simulation mesh is automatically generated.
To maintain accuracy, the meshing algorithm will create a
smaller mesh in high index (to maintain a constant number
of mesh points per wavelength) and highly absorbing
(resolve penetration depths) materials. In some cases, it is
also necessary to manually add additional meshing
constraints. Usually, this involves forcing the mesh to be
smaller near complex structures (often metal) where the
fields are changing very rapidly.
Solver physics
2.2
19
Eigenmode Solver
The Eigenmode Solver (Eigensolver) solves for optical modes in a cross-section of an
arbitrary waveguide geometry. The waveguide mode as a transverse field distribution that
propagates along the waveguide without changing shape.
In the z-normal eigenmode solver simulation example shown in the figure above, we have
the vector fields:
E ( x, y )e i (
z)
H ( x, y )e i (
z)
and
where is the angular frequency and is the propagation constant. The modal effective
neff
index is then defined as
c
.
MODE Solutions find these modes by solving Maxwell's equations on a cross-sectional

mesh of the waveguide. The finite difference algorithm is the current method used for
meshing the waveguide geometry, and has the ability to accommodate arbitrary waveguide
structure. Once the structure is meshed, Maxwell's equations are then formulated into a
matrix eigenvalue problem and solved using sparse matrix techniques to obtain the effective
index and mode profiles of the waveguide modes. This method is based on Zhu and Brown1
, with proprietary modifications and extensions.
20
Reference Guide
Z. Zhu and T. G. Brown, Full-vectorial finite-difference analysis of microstructured optical

fibers, Opt. Express 10, 853864 (2002), http://www.opticsexpress.org/abstract.cfm?
URI=OPEX-10-17-853
2.2.1 Meshing in the Eigenmode solver

The MODE Solutions Eigenmode Solver uses a rectangular, Cartesian style mesh, like the
one shown in the following screenshot. It's important to understand that of the fundamental
simulation quantities (material properties and geometrical information, electric and
magnetic fields) are calculated at each mesh point. Obviously, using a smaller mesh
allows for a more accurate representation of the device, but at a substantial cost. As the
mesh becomes smaller, the simulation time and memory requirements will increase.
MODE Solutions provides a number of features, including the conformal mesh algorithm,
that allow you to obtain accurate results, even when using a relatively coarse mesh.
By default, the simulation will use a uniform mesh.
You simply set the number of mesh points along
each axis. In some cases, it is necessary to add
additional meshing constraints. Usually, this involves
forcing the mesh to be smaller near complex
structures where the fields are changing very rapidly.
Note: In FDTD-based simulations, it's important to
use a smaller mesh in high index materials, and to
maintain a minimum number of mesh points per
wavelength. This constraint does not exist for the
Eigenmode solver.
Solver physics
2.3
21
Propagator
MODE Solutions currently supports 2 methods of propagating fields.
1) The 2.5D FDTD 21 propagator. This propagator accurately describes the propagation of
light in planar integrated optical systems, from ridge waveguide-based systems to more
complex geometries such as photonic crystals. The propagator allows for planar (omnidirectional) propagation without any assumptions about an optical axis, which allows for
structures like ring resonators and photonic crystal cavities to be efficiently modeled
devices that have been traditionally treated with 3D FDTD. The propagator can model
devices on the scale of hundreds of microns quickly.
2) The eigenmode expansion 23 propagator. This script based, unidirectional eigenmode
expansion propagator allows you to decompose one input or waveguide mode onto the
modes of another waveguide section and propagate the modes an arbitrary distance. It is
useful for waveguide couplers, long tapers and other devices where the propagation can be
assumed to be essentially unidirectional.
2.3.1 2.5D FDTD

The FDTD propagator is based on collapsing a 3D geometry into a 2D set of effective
indices that can be solved with 2D FDTD 15 . This works best with waveguides made from
planar structures. For additional information on the 2.5D Propagator, see the Lumericals
2.5D FDTD Propagation Method whitepaper on our website.
The main assumption of this method is that there is little coupling between different
supported slab modes. For many devices, such as SOI based slab waveguide structures,
that only support 2 vertical modes with different polarizations, this is an excellent
assumption.
The calculation steps involve:
1. Identification of the vertical slab modes of the core waveguide structure, over a desired
range of wavelengths.
2. Meshing of the structure and collapse of the 3rd dimension by calculation of the
corresponding effective 2D indices (taking into account the vertical slab mode profile).
There are currently two approaches to doing this in the Propagator:
Variational
A variational procedure based on Hammer and Ivanova1. Here, the effective permittivities of
the TE and TM-like modes have the form:
22
Reference Guide
TE
eff
( x, y , )
( x, y , z )
( z , ) M ( z , ) dz
z
2
M ( z , ) dz
z
1
2
TM
eff
( x, y , )
k
z
| M | dz
1
| M |2 dz
( x, y , z )
k2
z
1
M
dz
( x, y , z )
z
1
2
M dz
( x, y , z )
where r, M and r are the 1-D reference permittivity profile, the associated guided slab
mode and the propagation constant.
Reciprocity Based
This is a procedure based on the reciprocity theorem, as described in Snyder and Love2:
neff ( x, y, )
( x, y , z )
1
2
r ( z , ) E ( z , ) dz
P ndz
z
Note that in both cases, the generated effective materials are also dispersive, where the
dispersion comes both from the original material properties (material dispersion) and the
slab waveguide geometry (waveguide dispersion). These new materials are then fitted using
Lumerical Solutions' multi-coefficient model into a time-domain form that can be used in the
2D FDTD simulation in step 3. Note that the effective index treatment may lead to
generated materials that have properties that are unphysical (for example, having an
artificial negative imaginary index). In this case, one has the option of restricting the range
of generated indices to the min/max values defined by the physical material properties of
the original materials. All of these settings can be found under the Effective index tab of the
Propagator simulation region.
3. Simulation of the structure in 2D by FDTD 15 .
4. If desired, re-expansion of the fields into 3D.
The Ring resonator getting started example contains step-by-step instructions and
discussions on how to carry out a propagator simulation using the variational FDTD
method.
1 Manfred Hammer and Olena V. Ivanova, MESA Institute for Nanotechnology, University of
Twente, Enschede, The Netherlands
Solver physics
23
"Effective index approximation of photonic crystal slabs: a 2-to-1-D assessment", Optical

and Quantum Electronics ,Volume 41, Number 4, 267-283, DOI: 10.1007/s11082-009-93493
2 Allan W. Snyder and John D. Love, Optical Waveguide Theory. Chapman & Hall, London,
England, 1983.
2.3.2 Eigenmode expansion

This unidirectional eigenmode expansion method is implemented in the propagate
command.
The propagate command calculates the resulting mode profile of an arbitrary mode after it
has propagated through a waveguide for some distance. This is done by decomposing the
mode into modes supported by the waveguide (ie. the currently calculated modes) using
overlap integrals. Each supported mode is then propagated through the waveguide. The
resulting modes are then added coherently to give the final mode profile.
This technical is useful for waveguide couplers, long tapers and other devices where the
propagation can be assumed to be essentially uni-directional. Please see MODE Solutions'
applications library for some use case examples:
Evanescent waveguide couplers
Tapered waveguides
Polarization rotator
2.3.3 Meshing in the propagator

The MODE Solutions Propagator uses a rectangular, Cartesian style mesh, like the one
shown in the following screenshot. It's important to understand that of the fundamental
simulation quantities (material properties and geometrical information, electric and
magnetic fields) are calculated at each mesh point. Obviously, using a smaller mesh
allows for a more accurate representation of the device, but at a substantial cost. As the
mesh becomes smaller, the simulation time and memory requirements will increase.
MODE Solutions provides a number of features, including the conformal mesh algorithm,
that allow you to obtain accurate results, even when using a relatively coarse mesh.
By default, the simulation mesh is automatically
generated. To maintain accuracy, the meshing
algorithm will create a smaller mesh in high index (to
maintain a constant number of mesh points per
wavelength) and highly absorbing (resolve penetration
depths) materials. In some cases, it is also
necessary to manually add additional meshing
constraints. Usually, this involves forcing the mesh to
be smaller near complex structures (often metal)
24
Reference Guide
where the fields are changing very rapidly.
Note: meshing time
The general meshing algorithm can take a reasonable amount of time compared to the
simulation because the mesh must be effectively completed in 3D. It is possible for the
user to specify if the structure is composed of purely extruded structures - that is
structures that are extruded along z with perfectly vertical sidewalls. In this case, the
meshing can be accomplished much faster.
2.4
INTERCONNECT
INTERCONNECT is a circuit simulator that can support mixed signal representation of
optical single and multi-mode signals as well as electrical signals. The signals can
propagate fully bidirectionally through the circuit topology for both Time Domain 24 and
Frequency Domain 25 simulations.
Users can choose elements from an extensive list of pre-defined PIC elements, as well as
create custom elements from pre-defined primitives or via Lumericals powerful script
language. In addition, elements can also be characterized accurately using results directly
from Lumerical's electromagnetic simulators (FDTD Solutions and MODE Solutions).
2.4.1 Time Domain Simulator

Time domain simulation is performed using a data flow system simulator, allowing for more
flexibility than using traditional discrete time or time-driven simulators. The simulator
scheduler calculates each element in order to generate time domain waveform samples and
propagate them bidirectionally. Very close coupling between components can be simulated
allowing, for example, the analysis of optical resonators.
Solver physics
25
2.4.2 Frequency Domain Simulator

Frequency domain simulation is performed using scattering data analysis to calculate the
overall circuit response.
The circuit is composed a series of elements connected by an arbitrary number of input/

output (or bidirectional) ports. Users can define all the modes supported by the device and
their frequency dependent properties.
Once all the ports are defined, INTERCONNECT carries out the scattering data analysis for
the entire circuit by solving a sparse matrix that represents the circuit as connected
scattering matrices, each one of them representing the frequency response of an individual
element.
2.5
DEVICE
DEVICE is an physics-based electrical simulation tool for semiconductors, which selfconsistently solves the system of equations describing the electrostatic potential and
density of free charge (electrons and holes). DEVICE solves the drift-diffusion equation to
describe the spatial distribution of electrons and holes, and solves the Poisson equation to
establish the electrostatic potential. Solving the drift-diffusion (DD) equations is an
established and robust method that will produce accurate results for a wide range of
semiconductor devices under common operating conditions.
This section will introduce the basic mathematical and physics formalism behind the selfconsistent algorithm used in DEVICE, starting from the non-linear Poisson and driftdiffusion equations. The simulator can be used for advanced research and development or
as an ideal teaching and learning environment in semiconductor electronics and
optoelectronics.
2.5.1 System of Equations

DEVICE solves the drift-diffusion equations for electrons and holes (carriers)
Jn
n E qDn n
Jp
p E qD p p
where Jn,p is the current density (A/cm2), q is the positive electron charge, n,p is the
mobility, E is the electric field, Dn,p is the diffusivity, and n and p are the densities of the
26
Reference Guide
electrons and holes, respectively (the subscripts n and p indicate quantities that are
specific to the carrier type). Each carrier (electron or hole) moves under the influence of two
competing processes: drift due to the applied electric field, and random thermal diffusion
due to the gradient in the density. These processes are represented in the drift-diffusion
equations as the sum of two terms.
The mobility n,p describes the ease with which carriers can move through the
semiconductor material, and is related to the diffusivity Dn,p through the Einstein relation
Dn , p
n, p
k BT
q
where kB is the Boltzmann constant. The mobility is a key property of the material, and
may be modeled as a function of temperature, impurity (doping) concentration, carrier
concentration, and electric field. For further details, please see the section on material
models.
To solve the drift-diffusion equations, the electric field must be known. To determine the
electric field, Poisson's equation is solved:
where is the dielectric permittivity, V the electrostatic potential

net charge density,
(E
V)
and the
p n C
which includes the contribution C from the ionized impurity density.
Finally, the auxiliary continuity equations are required to account for charge conservation
n
t
p
t
1
q
Jn
1
q
Jp
Rn
Rp
where Rn,p is the net recombination rate (the difference between the recombination rate
and generation rate). The physical processes associated with the material are assumed to
act equivalently when applied to electrons or holes, and as a result, R = Rn = Rp. The
recombination and generation processes are important factors in the material-specific
calculation of carrier behavior. Multiple recombination and generation processes are
modeled, which may depend on temperature, impurity (doping) concentration, carrier
concentration, electric field, and current density. For further details, please see the section
on material models.
Solver physics
27
DEVICE discretizes and solves the drift-diffusion and Poissons equations on an

unstructured finite-element mesh in one and two dimensions. The simulation region is
partitioned into multiple domains along boundaries between materials with unique physical
descriptions. The materials used in the simulation may be categorized as insulators,
semiconductors, or conductors; each type of material has an associated user-specified
model or collection of models that describe its behavior. In particular, specialized multicoefficient models are provided for semiconductors that describe the fundamental
properties, mobility, and recombination processes inherent to that material.
The system of equations solved by DEVICE admits both a steady-state and time-varying
result. By enforcing the condition
n
t
p
t
in the continuity equations, the carrier density and electrostatic potential can be solved at
steady-state. Steady-state simulations can be used to examine the systems behavior at a
fixed operating point, and are also useful when extracting small-signal parameters for a
component (e.g. for frequency response analysis). Alternately, by specifying an initial
condition for the carrier density and electrostatic potential, the equations can be solved in a
sequence of discrete times. The time-dependent behavior of the component can then be
used to directly evaluate its large-signal time-domain response or extract large-signal AC
parameters.
Boundary conditions are very important in an accurate semiconductor device simulation.
Two categories of boundary condition are present in DEVICE: those that relate to the
electrostatic potential (Poissons equation) and those that relate to the carrier densities
(the drift-diffusion equations). Poissons equation and the drift-diffusion equations are
second-order partial differential equations (PDE), and each requires that the solution be
explicitly specified for at least one location. This is known as a Dirichlet boundary
condition. For the electrostatic potential, the Dirichlet condition takes the form of a
boundary (internal or external) with a fixed voltage specified,
V ( x)
V1
as is typical of an electrical contact. For the carrier densities, the majority carrier
concentration is set to its equilibrium value at the interface between a contact and the
semiconductor, such that
p n C
At internal boundaries between two domains that are not contacts, the boundary conditions
are determined from the physical properties of the interface. In the case of the electrostatic
potential, the electric flux density must be continuous across the boundary in the absence
of a surface charge. For the electron and hole densities, boundary conditions between the
28
Reference Guide
semiconductor and adjacent materials may be specified in terms of a surface
recombination current density, which will default to zero (no carrier flux across the
boundary) for insulators or an infinite recombination velocity (forcing the carrier density to
its equilibrium value) for contacts. At the external (open) boundaries of the simulation
domain, homogenous Neumann boundary conditions are applied: the electric field normal to
the boundary is set to zero as is the surface recombination current density. Physically, this
corresponds to an insulating boundary across which no charge can flow.
By convention, the length units in semiconductor models are chosen to be centimeters.
This is reflected in the semiconductor device literature, and in the parameter coefficients for
the material models. Energies are calculated in electron Volts (eV), where the electron
energy E is related to the local electrostatic potential (voltage) as E = -qV. All energies
(and voltages) are referenced from the (equilibrium) Fermi level of an electrical contact in
the system.
2.5.2 Meshing in DEVICE

DEVICE uses an unstructured, finite-element mesh, like the one shown in the following
screenshot. The solution to the system of equations used to determine the physical
quantities of interest is estimated from the discrete formulation of those equations.
Consequently, it's important to understand that of the fundamental simulation quantities
(material properties, geometry information, electrostatic potential, and carrier
concentrations) are calculated at each mesh vertex.
A finer mesh (with shorter edge lengths and smaller
elements) will better approximate the exact solution
to the system of equations, but at a substantial cost.
As the mesh features become smaller, the simulation
time and memory requirements will increase.
DEVICE provides a number of tools, including the
automatic and guided mesh refinement, that allow
you to obtain accurate results, while minimizing
computational effort.
CAD layout editor
29
CAD layout editor

The image below shows a typical Lumerical CAD Layout Editor. This tool is used to setup
and analyze all simulations, and to run all script files.
In this screenshot,
different regions of the
CAD in Layout mode
are highlighted. They
include:
Main title bar 29
Toolbars 30
View ports 36
Object Tree 37
Optimization and
Sweeps 38
Script Prompt 38
The Layout Editor has two modes of operation: Layout mode and Analysis mode. Layout
mode is used to setup your simulation. Simulation objects can be added, modified and
deleted in this mode. After a simulation runs, the Layout Editor automatically switches to
Analysis mode. In analysis mode, it is not possible to edit the simulation objects, since
we want the object settings to match the data from the simulation. To edit simulation
objects, switch back to layout mode with the
3.1
button.
Main title bar

The menus on the main title bar are listed below. If any of the options can be selected
using a button on a toolbar, the icon is drawn to the left of the name. Similarly, shortcut
keys are located to the right.
File
The file menu includes options to create, save and load simulation files. The Import menu
allows users to import structural data stored in GDSII files 60 files.
30
Reference Guide
Edit
The edit menu allows users to undo/redo their actions, and to copy/paste/edit object in the
simulation.
View
The view menu provides options to control the layout and visibility windows and toolbars.
Setting
This setting menu contains options to change the unit setting within the graphical interface.
These option only apply to the GUI. Scripts always use SI units.
Simulation
This menu contains settings for configuring resources and running simulations.
Help
The help menu provides links to local PDF copies of the product documentation and links
to the larger set of online documentation, as well as options for checking which version of
the software is installed.
3.2
Toolbars
The following sections describe the various toolbars. Toolbars visibility can be controlled in
the View - Toolbars menu.
3.2.1 Main
The main toolbar contains buttons to add various Simulation objects, open the Material
database 42 and import files, as described below. When available, clicking the arrow to the
right of the icon expands a drop-down menu containing related buttons. If one of the related
buttons is pressed, it replaces the default button in the toolbar. See the Simulation objects
chapter for information about specific objects.
Material Database
This button opens material database window. For more information, see the Material
database 42 chapter.
Structures
This button will insert the shown structure primitive into the simulation. Pressing the arrow
will show all available primitives.
CAD layout editor
31
Groups
This button will add an analysis, container or structure group into the simulation. Pressing
the arrow will allow selection of which group to add.
Simulation
This button will insert simulation or mesh override regions. Pressing the arrow will allow
selection of which simulation object to add.
Import
This button will open a window for importing files from other programs. Pressing the arrow
will allow selection of which kind of import.
Doping
This button will insert various doping regions into the simulation. Pressing the arrow will
allow selection of which monitor to add.
Generation
This button will insert various generation rate objects into the simulation. Pressing the
arrow will allow selection of which monitor to add.
3.2.2 Edit
The edit toolbar contains tools used to copy, delete, or modify settings of simulation
objects.. When applicable, the shortcut key used to run the function from the keyboard is
given in brackets next to the name of the tool. An object must be selected in order to use
these tools.
Edit properties (E)

This command opens the edit properties window. See the Simulation objects chapter for
information about specific properties for each object.
Tip: Group edit of multiple objects
32
Reference Guide
The properties of multiple structure objects can be edited together by selecting multiple
objects prior to entering edit mode. This option is only available for structure objects, not
sources or monitors. Any properties which are identical between all of the selected
objects results in the common value being displayed in the edit dialog box.
Duplicate (D)
This command makes a duplicate of the currently selected object. The copies that are
created are identical to the originals, apart from a one grid cell offset in their x position
which allows the user to distinguish between the original and the copy. When multiple
objects are selected, all of the selected objects will be copied. When copying sources and
monitors, it is important to rename the copies so that each object has a unique name.
Move
The move command allows shifting a single or multiple selected objects by a specified
distance in each of the x,y,z dimensions. A pop-up window appears with field entries to
specify the shift amount.
Array
The array command allows the user to create an array or arrays of objects.
The array edit window that pops up contains several properties :
A1 LATTICE: the distance between adjacent elements in the a1 direction
A2 LATTICE: the distance between adjacent elements in the a2 direction
ANGLE BETWEEN A1 AND X-AXIS: the angle (in degrees) between the a1 direction and
the x-axis
ANGLE BETWEEN A1 AND A2: the angle (in degrees) between the a1 and the a2
directions.
COLUMNS, ROWS: the number of rows and columns that comprise the array.
AZ LATTICE: the distance between adjacent elements in the z direction (valid for 3D
simulations only)
LAYERS: the number of elements in the z direction (valid for 3D simulations only)
The parameters in the edit window below produce the resulting array shown in the diagram.
CAD layout editor
33
Delete (Del)
The delete command removes the currently selected object, or objects, from the
simulation.
3.2.3 Mouse mode

The mouse mode allows you to control the behavior of the mouse. Depending on the
mode, the user can edit objects, pan or zoom in the view ports or measure the distance
from one point to another. When applicable, the shortcut key used to run the function from
the keyboard is given in brackets next to the name of the tool. Only one mouse mode may
be selected at a time.
Select (S)
This function puts the mouse into the select mode. This allows objects to be selected
through the view ports (objects may be selected in the objects tree regardless of whether
the mouse is in select mode or not).
For reference, the current location of the mouse within the view ports is shown in the field at
the bottom right-hand corner of the CAD window (see the image below). The < and >
buttons at the right decrease or increase the number of decimal places shown.
Changing aspect ratio settings

A feature available when in the select mode is changing aspect ratio settings. Right click
in one of the view windows to see the menu, and then select Change aspect ratio
settings.
Zoom (Z)
34
Reference Guide
This function sets the mouse to be in the zoom mode. The default aspect ratio of the XY
view and perspective views are locked at 1:1, which means circles always appear round
(rather than as ovals). The aspect ratio for the XZ and YZ is not locked. Use the left click
to zoom in and the right click to zoom out. To zoom to a particular area, drag diagonally
across the desired region. Finally, double clicking either button zooms to extent. To
adjust the view, it's easiest to set the XY view first, then adjust the Z view in the XZ or YZ
views.
Pan view (P)

The pan view mode allows the user to drag the view in the plane of the view port. In the
Perspective window, the pan mode is used to rotate the view.
Scrolling in the view ports
The other method of adjusting the view ports is by using the arrow buttons on your
keyboard. Each press of a button results in the view shifting in the direction indicated by
the arrow.
Ruler (R)
Once the ruler mode is selected, a distance measurement can be made by pressing the
left mouse button and then dragging the mouse. A non-permanent triangle is drawn
between the locations where the mouse button was pressed (A) and released (B). The
distances are given in the lower left-hand corner of the CAD window (see the image below).
The dx and dy fields correspond to the horizontal and vertical distance between A and B,
and the AB field corresponds to the length of the hypotenuse.
3.2.4 View
The view toolbar contains tools to zoom to the extents of objects, edit grid settings and
view the mesh used for the simulation. When applicable, the shortcut key used to run the
function from the keyboard is given in brackets next to the name of the tool.
Zoom Extent (X)

Selecting this tool centers and scales the view ports around the selected simulation
objects. For instance, pressing zoom extent while a structure is selected arranges the
view such that only the structure are shown, while other simulation objects may appear
outside the extent of the view. When no objects are selected, pressing this button zooms
to the the largest object in the model. This function is also accessed via double-clicking
either the left- or right-hand mouse button while in zoom mode.
CAD layout editor
35
Drawing Grid
Clicking on the drawing grid brings up a window in which the following options can be
edited:
SHOW GRID: when checked, the grid will be plotted in the drawing palette
SNAP TO GRID: when checked, objects can only be moved so that their centers align
with intersection points of the grid
A1 LATTICE: the distance between grid lines in the a1 direction
A2 LATTICE: the distance between grid lines in the a2 direction
AZ LATTICED: the distance between grid lines in the z direction
ANGLE BETWEEN A1 AND X-AXIS: the angle (in degrees) between the a1 direction and
the x-axis
ANGLE BETWEEN A1 AND A2: the angle (in degrees) between the a1 and the a2
directions
Recalculate simulation mesh (F5)
Mesh generation is too computationally intensive to be done constantly as the simulation
setup is modified. If you wish to see the current mesh, use this option to update and
recalculate the mesh. The mesh is always recalculated before running a simulation.
3.2.5 Simulation
The simulation tools are:
Resources
Opens the resource configuration manager. This window can add/remove and enable/
disable computational resources. It also contains a useful configuration test tool to check
the resource setup.
Run
Run the current simulation. For more information on how to run simulation, see Running a
simulation.
Run scripts
This function will allow the user to run a Lumerical script file (*.lsf) to perform automated
commands such as plotting and saving data. This button is located in the CAD environment
twice if the script editor is open: once in the simulation toolbar and once at the top of the
script editor. Pressing the button on the toolbar brings up an open file dialog. Pressing the
button in the script editor runs the script that is selected in the editor window.
36
Reference Guide
Switch to layout editor

This function returns the simulation environment from analysis mode back to the layout
editor mode. If you switch to layout editor and then save the file, the data from the
simulation will be overwritten and lost.
3.2.6 Search bar

The search toolbar can be used to quickly search for topics in the online product
documentation knowledge base. This will bring up the search results in a new tab in your
default browser.
Online help toolbar

Search the online knowledge base for the specified term. Requires internet connection. If
an internet connection is not available, some product documentation is available in the Help
- Reference Guide menu.
3.3
View ports
The view ports show a graphical
representation of the simulation from
an XY, XZ, YZ and 3D perspective
view.
Depending on the current mouse
mode, the mouse pointer will either
have the shape of an arrow (select),
a hand (pan), a magnifying glass
(zoom) or a ruler (measurement).
You can toggle between these
options with the mouse mode
toolbar. When objects are selected,
the vertices are drawn with red
squares (also, the object will be
highlighted in the Object tree. It is
possible to copy and paste selected
objects between different CAD
windows using the standard Ctrl+C
and Ctrl+V shortcut keys.
CAD layout editor
3.4
37
Object Tree
As previously discussed, a simulation requires that
the user define a set of objects, simulation region,
sources and monitors. As a complete setup may
contain a large number of objects, the object tree was
designed to allow for organization and easy selection.
All simulation objects are within the group, model,
which represents the current simulation. Within
'model', objects are listed as they are inserted by the
user. Press F2 or double-click to change the name.
To move the objects up and down the tree as well as into groups, we use the orange arrows
at the top of the window. The up and down arrows shift the objects relative to each other,
while the left and right arrows move them out of and into groups. To add groups, we use
the button called groups in the main toolbar. Structure groups can only contain structures
and likewise, analysis groups can only contain monitors. See the online user guide section
for more information and examples about Structure groups and Analysis groups. The third
group, "Containers" act like folders and can hold any type of object. In the image above,
the 'Sources/Monitors' container group has both individual sources and monitors as well as
an analysis group.
Note that there are buttons with green crosses at the top of the objects tree. These buttons
can be used to hide or display certain types of objects. When objects are selected, they
are highlighted blue in the objects tree and the vertices are marked with red squares in the
view ports. Objects can always be selected by left-clicking on their name in the object tree
or edited by right-clicking. Using the tree is the preferred method of selection especially in
complicated simulation setups with many overlapping elements. In the image above, the
power monitor, above, is selected.
3.4.1 Enable/Disable Simulation Object

User can enable/disable simulation objects by right-clicking on each and selecting
"Enable/Disable". Disabled simulation objects will remain in the object tree (and can be
38
Reference Guide
re-enabled), they will have no effect on the simulation.
See also
setnamed 232 , set 231
3.5
Results View
See the Results View
3.6
93
section of the Reference Guide for more information.
Optimization and Sweeps

See the Optimization and parameter sweeps
information.
3.7
97
section of the Reference Guide for more
Script Prompt and Script Editor

The scripting language is useful for setting up complex structures and advanced data
analysis. See the Scripting chapter for a list of all the script commands, as well as
examples on how to use them.
By default the script editor is located on the right hand side of the view ports and shares
the same frame as the analysis window. When both windows are open, it is possible to
toggle between the two through tabs located at the right side of the frame. The script file
editor contains buttons to create, open, save and run script files. When multiple script files
are open, pressing on the run script button runs the one in the forefront. Note that when
entering scripting code in the script file editor, each command must be followed with a
semicolon.
When running a script file in the a different directory using the GUI, the current working
directory is unchanged, but the directory of the script file is added to the scripting path.
This way, any files called by that script will be found. However, the search order is the
current directory first, then any other folders in the path, and then the directory of the script
file.
CAD layout editor
39
By default the script prompt is

located at the bottom of the CAD
window. Script commands are
executed as soon as the ENTER
button is pressed on the command
line. If a semicolon is missing at the
end of the command line, it is
automatically inserted it for you.
Multiple lines can be pasted into the
script prompt, and will run as in the
script editor. In this case though,
only the last semicolon can be
neglected.
3.8
Script Workspace and Script Favorites

See the Script Workspace and Script Favorites
information.
3.9
95
section of the Reference Guide for more
Changing the CAD layout

There are pre-defined CAD layouts that can be accessed through main title toolbar. Change
between the default layouts by selecting the drop-down menu VIEW->SET DEFAULT
LAYOUT, and choosing one of them. In addition, have control over hiding and docking
location of the the windows and toolbars. The current layout is saved when CAD closes so
the next time the program is opened, your previous layout will be used.
40
Reference Guide
Hiding/showing windows and
toolbars
There are two methods to hide or
show windows and toolbars
1) In the main title toolbar select
VIEW->WINDOWS or VIEW>TOOLBARS. The visible windows/
toolbars have a check mark next to
their name; the hidden ones do not.
2) By clicking the right button
anywhere on the main title bar or the
toolbar, the following pop up menu
will show up. As before, check
marks indicate when windows and
toolbars are visible.
Moving and undocking windows

Windows can be undocked by
double clicking the name with the
left mouse button. This is
particularly useful when you want to
make the script file editor window
larger. Non-view-port windows can
be docked on top of each other
either to the right or to the left of the
view ports. If they are placed on top
of each other, tabs on the sides
allow toggling between them.
Tip: To reposition an undock ed
window on Linux, hold down the Alt
k ey before attempting to move the
window.
Moving toolbars
To move a toolbar, hover the mouse over the top of the toolbar, where the dotted line is.
When the mouse cursor becomes a four-headed arrow, press the left mouse button and
CAD layout editor

drag-and-drop the toolbar. If you reach a region where you can place a toolbar, the CAD
environment makes room for the toolbar indicated by a blue void.
41
42
Reference Guide
Material database
This chapter explains the Material Database. See the following pages for details. Users
may also find the Material modeling recorded video to be helpful.
Material database 42
The Materials Database allows for the definition of complex materials using experimental
data or parametrized models. It can be accessed by clicking the material database button
on the Structures tab. The Material Database stores the material data to be used in the
simulation. It also provides an interface to change material properties like color, mesh
order, and model parameters. Experimental data can also be loaded into the database. To
view the resulting index profile, use the Material Explorer.
Electrical models 43
See this section for information on the available material models; insulators,
semiconductors, and conductors.
Mesh order 54
See this section for information on the mesh order property, which defines the meshing
behavior (priority) for overlapping objects.
4.1
Material database
The Materials Database allows you
to manage (create, modify, delete)
the materials that are available for
use in your simulations.
A copy of the database is stored in
each simulation file. A change to
the database in one file does not
automatically change the materials
in any other files. To modify the
default materials that appear when
you create a new simulation, edit
the simulation file in the Defaults
subdirectory of the installation
directory.
Import / Export
The import and export buttons allow you to transfer material data between simulation files
via Material Database Files (.mdf) files.
Material database
43
Material list
The material list shows the materials stored in the material database. A number of
materials are provide with the product installation. To create additional materials, use the
Add button. You can also modify some of the material properties (name, color, mesh
order, etc) in the list view.
Default materials provided with the product installation are write protected, and can not be
directly modified. To modify the properties of a default material, simply use the Copy
button to duplicate the material. The copy will be unlocked. The first column of the list
shows which materials are write protected.
Materials currently used in the simulation can not be deleted. The second column of the
list shows which materials are in use. To delete these materials, first modify the simulation
so they are not used.
Material Properties
Use the Material properties window to view and edit the material model parameters. For
model parameter definitions, see the material models section.
4.2
Electrical models
This section describes the electrical material models supported by the Material Database.
Model parameters can be edited in the Material property panel of the Material Database
window. Materials are categorized by their physical characteristics. The three types of
supported materials are conductors, insulators, and semiconductors.
Conductor
Materials that are defined as conductors are treated as ideal electrical conductors in
DEVICE: they are assumed to have zero resistivity. Consequently, the internal electric field
must be zero, and the voltage applied to the conductor will be constant across its domain.
Materials specified as conductors will be treated as ideal electrical contacts in the
simulation.
See more detailed information on Conductors
44
Insulator
Materials that are defined as insulators are treated as ideal electrical insulators in DEVICE:
they are assumed to be perfect dielectrics without free charge.
See more detailed information on Insulators
44
Semiconductor
Semiconductors, like insulators, are band gap materials. The band gap of a semiconductor
is typically small enough to allow a significant fraction of electrons to be thermally excited
44
Reference Guide
from the valence band to the conduction band at room temperature (300K). The band gap
for a semiconductor typically ranges from 0.5-1.5eV. When energetically excited to a
conduction band state, electrons leave behind a positively charged mobile vacancy, known
as a hole, which behaves much like a free electron in the semiconductor. The mobility of
the electrons and holes and the rates at which they are generated and recombine are
determined by the models described in this section.
See more detailed information on Semiconductors
44
4.2.1 Conductors
Conductor Fundamental Properties
Work Function
The defining characteristic of the conductor is its work function, which describes the energy
cost of removing an electron from the material.
4.2.2 Insulators
Insulator Fundamental Properties
Relative Dielectric Permittivity
The relative permittivity (or dielectric constant) of the material is equal to the square of the
refractive index, and is assumed to be the DC (zero frequency) value.
4.2.3 Semiconductors
In This Section:
Semiconductor Fundamental Properties
Mobility 46
Bulk Recombination and Generation 50
Surface Recombination 53
References 54
44
Semiconductor Fundamental Properties

Relative Dielectric Permittivity
The relative permittivity (or dielectric constant) of the material is equal to the square of the
refractive index, and is assumed to be the DC (zero frequency) value.
Work Function
In a semiconductor, the work function s describes the energy cost of removing an electron
from the intrinsic energy level (the Fermi energy of the undoped semiconductor) and placing
it at "infinity." A related value is the electron affinitiy s, which is the energy cost of
removing an electron from the conduction band edge.
Material database
s ,i
EG
2
45
k BT N C
ln
2
NV
where EG is the band gap and NC and NV are the effective density of states in the
conduction band and valence band, respectively.
Effective Mass
To account for the influence of the crystal lattice potential of the semiconductor, electrons
and holes can be approximated as free charges with an effective mass (relative to the
electron rest mass) that depends on the electronic band-structure of the material. In
DEVICE, the effective mass is treated as a parameter of the material model.
The temperature variation in the effective mass can be accounted for with a quadratic
model
mn*, p (T )
mn*, p (0)
T2
where coefficients and , and the effective mass at T=0K are inputs to the model.
Related to the effective mass is the effective density of states in the conduction and
valence bands
NC
NV
2 mn* k BT
2
h2
3/ 2
2 m*p k BT
3/ 2
h2
where h is Plancks constant.

Band Gap
A key physical property of the material is the band gap, which, like the effective mass, is
derived from the electronic band-structure of the material. In DEVICE, the band gap energy
is treated as a parameter of the material model.
The temperature variation in the band gap can be accounted for with a "universal" empirical
model
EG (T )
EG , 0
T2
T
where coefficients and , and the band gap energy at T=0K are inputs to the model.
Band Gap Narrowing
46
Reference Guide
When impurities are added to the intrinsic (pure) semiconductor, localized allowed energy
states may be introduced at energies that lie within the band-gap. In the case of dopants,
these impurity states will exist with energies near the conduction or valence band edges
(such that the dopants readily ionize at moderate temperatures). When the concentration of
dopants is large, these discrete states will begin to merge and form a thin "band" of allowed
states within the band gap, effectively narrowing the band gap. This can be viewed as a
narrowing of the band gap or an increase in the effective density of states.
The Slotboom model1
effect,
EG
V1 ln
54
ND
for band gap narrowing is provided in DEVICE to account for this
NA
N0
ln 2
ND
NA
N0
where the coefficients V1, N0, and C are inputs to the model, and the effect can be
specified independently for electrons and holes. Note that the sign implies a narrowing
effect for positive coefficients.
Intrinsic Carrier Concentration
The intrinsic carrier concentration is calculated from the effective mass and band gap, and
is only displayed in the Material Database for reference. It is calculated as
ni
N C NV exp
EG / 2k BT
where T=300K is assumed, and the effective density of states and band gap are treated are
treated as intrinsic quantities (before band gap narrowing).
Mobility
The mobility parameter in the drift-diffusion equations is the physical link between the
motion of carriers (electrons and holes) and the semiconductor material. The mobility can
be viewed as a measure of how readily electrons and holes can move through the crystal
lattice of the semiconductor. In the absence of any interactions with the lattice, impurities,
or other carriers, electrons and holes would move freely in the periodic potential of the
lattice; interactions that change the momentum of the carriers are termed scattering
events. Different types of scattering contribute to the mobility of the electrons and holes,
including
lattice scattering,
ionized and neutral impurity scattering, and
carrier-carrier scattering.
In addition, the velocity of the carriers is observed to saturate at high-fields. Each of these
scattering mechanisms can be addressed in DEVICE by applying the appropriate models,
which are detailed in the following sections.
Lattice Scattering
Material database
47
The fundamental process that impedes the free motion of the carriers in the lattice is
thermal scattering off of the lattice itself. The mobility due to lattice scattering is treated as
a basic input into the DEVICE semiconductor model, and may be entered as a constant
value or with a temperature dependence described by the "universal" temperature model,
A(T )
A(300)
T
300
where A(300) is the value of the parameter at T=300K, and is a temperature exponent. In
the case of the lattice scattering mobility L, the temperature dependence reads
L
n, p
L
n, p
(T )
(300)
T
300
.
where subscripts n and p refer to electrons and holes, respectively.
Impurity and Free-Carrier Scattering
Many models exist to account for the influence of impurities on the carrier mobility.
DEVICE provides support for three common models with wide-ranging applicability: the
54
54
54
Caughey-Thomas model2
, the Masetti model3
, and the Klaassen model4
. Each
model requires a variety of coefficients; default values are provided with DEVICE for
common semiconductors.
For general modeling purposes, the Caughey-Thomas model or Masetti models are often
sufficient, and coefficients are available for multiple semiconductor materials. The Klaassen
model is primarily tuned for silicon at T=300K, and coefficients for other materials are not
available. At moderate doping densities, the mobility predicted by all models reduces to
that of the Caughey-Thomas model.
The most basic model is the Caughey-Thomas model,
LI
n, p
min
n, p
L
n, p
min
n, p
N / N ref
where N is the total doping concentration (N = NA + ND ), L is the lattice scattering mobility

(as determined from the model chosen in the previous section), and min, Nref, and are
temperature-dependent coefficients described the universal temperature model.
To account for extremely large doping concentrations, the Masetti model can be selected,
which adds a correction to the Caughey-Thomas model for large N:
LI
n, p
min
n, p
L
n, p
min
n, p
N / Cr
( 2)
n, p
Cs / N
.
Again, N is the total doping concentration (N = NA + ND ) and L is the lattice scattering
48
Reference Guide
mobility. Parameters min, (2), Cr (replacing Nref of the Caughey-Thomas model), Cs , ,
and are each temperature-dependent coefficients described the universal temperature
model.
Finally, the mobility model proposed by Klaassen can be used to account for the
aforementioned doping effects (at moderate and high impurity concentrations), as well as
the influence of carrier-carrier scattering. The Klaassen model combines the basic lattice
scattering with the impurity and carrier-carrier scattering using Matthisens rule
LIC
n, p
L
n, p
IC
n, p
where L is the lattice scattering mobility and IC is Klaassens impurity and carrier-carrier
(IC) scattering mobility. The formulation of the IC scattering mobility is complex and
involves multiple levels of coefficients and models accounting for
majority carrier scattering by dopants,
minority carrier scattering by dopants, and
electron-hole scattering.
To begin, the IC mobility is defined as a function of the dopant and carrier concentrations,
L 2
L
min
N nsc, p
N ref 1
n p
n, p
n, p n, p
IC
N
,
N
,
n
,
p
n, p D
A
L
min
sc.eff .
L
min
sc.eff .
N nsc, p
n, p
n, p N n, p
n, p
n, p N n, p
where L is the lattice scattering mobility, and coefficients min, Nref 1 (equivalent to Nref or C
r
), and are defined as for the Caughey-Thomas or Masetti models. Note that the Klaassen
model accounts for temperature dependence separately, therefore constant a constant

value should be used for the lattice scattering mobility.
In the preceding equation, the "scattering densities" are
N nsc
ND
NA
sc
p
NA
ND
where the donor and acceptor densities, ND and NA respectively, are corrected according to
the clustering function:
ND
ND
NA
NA
ND
CD
N ref , D / N D
NA
CA
N ref , A / N A
Material database
49
Here, CD , Nref ,D , CA, and Nref ,A are coefficients of the model.

The "effective scattering densities" are defined as (using the same clustering-corrected
acceptor and donor concentrations)
N nsc.eff .
ND
G Pn N A
p
F Pn
N psc.eff .
N A G Pp N D
n
F Pp
The function G describes the ratio of scattering cross-sections between repulsive and
attractive screened Coulomb potentials as a function of the factor P (itself a function of
carrier density and majority dopant density). The factor P accounts for the screening effect,
and is calculated as the weighted harmonic mean of two parameters accounting for the
free-carrier and ionized impurity screening,
1
Pn N D , n
f CW
PCW ,n N D
Pp N A , p
f CW
PCW , p N A
f BH
PBH ,n n
1
f BH
PBH , p p
Weights fCW and fBH are coefficients of the model.

The same factor P is used in the calculation of the function F, which describes the mobility
ratio between stationary, infinite-mass secondary scatters (e.g. ionized impurities) and
mobile, finite-mass secondary scatters (e.g. free carriers). Both functions F and G are
parameterized fitting functions to physical processes, and the coefficients of those
functions (r1 to r6 for function F and s 1 to s 7 for function G) are also coefficients of the
model.
High-Field Saturation
As the electric field within the semiconductor increases, the drift-velocity of the carriers is
commonly observed to saturate, reducing the mobility accordingly. To account for this
effect, DEVICE includes a saturation velocity mobility model
LIC
n, p
LICE
n, p
LIC
n, p
n, p
sat
n, p
where LIC is the mobility accounting for lattice, impurity, and carrier-carrier scattering (as
50
Reference Guide
calculated using the active models for those processes) and vsat is the model coefficient
that determines the saturation velocity. The product of the low-field mobility LIC and the
gradient of the quasi-Fermi level is equivalent to the velocity in the context of the driftdiffusion equations.
Bulk Recombination and Generation

Recombination describes the processes by which an electron from the conduction band
makes an energetic transition and neutralizes a hole in the valence band. Generation
describes the complementary behavior, where an electron is excited from the valence band
to the conduction band, creating a hole in the process (often, the term electron-hole-pair is
used when referring to generation). The models for bulk recombination and generation
processes relate to the physical mechanisms by which the carriers make the energetic
transition. DEVICE provides models describing
trap-assisted (Shockley-Read-Hall) recombination,
Auger recombination, and
radiative recombination.
These models and their parameterizations are the subject of the following sections.
Trap-Assisted (Shockley-Read-Hall) Recombination
The recombination process in the trap-assisted model assumes that there are unoccupied
"trap" states (also referred to deep-level defect states) within the band gap. Typically, these
states result from impurities (either intentional or unintentional), and the most active have
energy levels near the middle of the band gap. Recombination occurs when an electron
relaxes (transfers energy to the lattice or emits a photon) to the trap state from the
conduction band, and sequentially, a hole from the valence band relaxes to the same trap
state. This process is modeled using the Shockley-Read-Hall (SRH) equation,
RSRH
p
np ni2
n n1
n p
p1
where n and p are the electron and hole lifetimes, respectively, and n1 and p1 are the
effective densities of carriers in the trap states. The trap states are characterized by their
densities Nt , capture cross-section t , and energy level Et - Ei (commonly abbreviated as
Et and referenced to the intrinsic energy level). The constants n1 and p1 are calculated as
n1
niee Et / k BT
p1
niee
Et / k B T
The carrier lifetime can be determined from the capture cross-section and trap density as
1
n, p
n, p
Nt
3k BT
mn*, p
Material database
51
but is commonly taken as an input to the model.

DEVICE provides a temperature dependent model for the SRH carrier lifetime, as well as
models that include corrections for doping density. The basic temperature-dependent model
for the carrier lifetime follows the usual power-law relation
srh, 0
n, p
srh, 0
n, p
(T )
(300)
n,p
T
300
Alternately, a constant value can be supplied for both electrons and holes.
To account for doping concentration effects, DEVICE provides two correction models that
use the previous expression for the SRH carrier lifetime as an input. First, a modified model
in the form proposed by Fossum is described by
srh, 0
n, p
srh
n, p
n, p
n, p
N n, p
n, p
N n, p
n,p
, where N n , p
N A ND
N nref, p
The original model of Fossum can be obtained by setting coefficients , , and to one (1)
and setting to zero (0), and this is the default model used in DEVICE.
Alternately, a formulation proposed by Klaassen can be selected, where the SRH carrier
lifetime correction is given by the equation
srh
n, p
srh, 0
n, p
srh, 0
n, p n, p
N n, p
T
300
n,p
where N n , p
N A ND
N nref, p
Note that this model explicitly includes the temperature dependence, and should only be
used in concert with a constant value for the baseline SRH carrier lifetime.
Auger Recombination
Auger transitions are three-particle transitions (two carriers scatter and transfer energy and/
or momentum to a third carrier) that describe four related processes, which are illustrated in
the figures below. Each process has an associated rate coefficient. According to the
principle of detailed balance, the net rate for each type of carrier must be zero at
equilibrium, such that
CcnAU ni2
CenAU and CcpAU ni2
CepAU
Assuming that the value of the rate coefficients does not change as the system moves from
equilibrium, the net Auger recombination rate is
RAU
CcnAU n CcpAU p np ni2
Note that Auger transitions depend only on carrier density, differentiating them from other
recombination processes.
52
Reference Guide
Recombination by
electron excitation
RnAU
Recombination by hole
Generation by
Generation by
excitation
electron relaxation hole relaxation
CcnAU n 2 p
R pAU
CcpAU np 2
GnAU
CenAU n
G pAU
CepAU p
DEVICE supports three models for the capture rate coefficients, including
the universal temperature model proposed by Klaassen,
an empirical model by White accounting for a reduction in the recombination rate at high
carrier concentrations, and
a model by Clugston and Basore accounting for both high and low injection conditions.
The universal temperature model proposed by Klaassen takes the usual power-law form,
Cn0, p
Cn , p (300)
T
300
n,p
and is suitable for devices where Auger recombination is moderate (low injection
conditions). The Auger rate coefficients are only weakly dependent on temperature, and
constant values may be used as well.
An alternate empirical model proposed by White can be used as a correction to the
previous model, taking that coefficient as an input. The White model accounts for the
reduction in the Auger recombination rate observed at high carrier densities (due to strong
screening effects), and is expressed as
Cn
Cn0
1
, Cp
C p0
1
where the coefficient determines the transition density.
Material database
53
A related model proposed by Clugston and Basore is designed to account for the two
regimes related to minority carrier injection:
Cn
Cn0
Cp
0
p
ND
ND
CnHI
p
2 ND p
NA
C pHI
NA n
NA n
DEVICE will use the Auger capture rate coefficient defined in the Klaassen model (or a
constant value) for the low injection conditions, and apply a second coefficient when strong
minority carrier injection dominates according to the preceding formulations.
Radiative Recombination
In a radiative transition, a conduction band electron will relax directly, emitting a photon
whose energy approximately equals that of the band gap, and then recombine with a hole
in the valence band. The opposite process occurs when a photon is absorbed by an
electron in the valence band, promoting it to the conduction band and leaving a hole in its
place. Radiative recombination transitions are typically significant only in materials with a
narrow bandgap, or a bandstructure that permits direct transitions in momentum (e.g.
GaAs). Radiative recombination is typically negligible in bulk silicon.
The recombination rate is determined from the product of a capture rate coefficient and the
carrier density product,
ROPT
CcOPT np
and the corresponding generation rate is simply the emission rate constant,
GOPT
CeOPT
Once again, the coefficients are related by the principle of detailed balance at thermal
equilibrium, such that
ROPT
CcOPT np ni2
The optical capture rate coefficient can be modeled in DEVICE either as a constant or
using the universal temperature power-law,
CcOPT (T ) CcOPT (300)
T
300
Surface Recombination
Trap-Assisted Model
Like bulk Shockley-Read-Hall (SRH) recombination, the presence of deep-level trap states
54
Reference Guide
at the semiconductor surface catalyzes recombination. The surface recombination process
is modeled by a formula similar to that of the bulk case,
Rsurf
np ni2
1
1
n n1s
p
sp
sn
p1s
but differs slightly from the bulk process since it is occurs on a two-dimensional surface.
The trap density Nts is now given per unit area, such that the carrier lifetime of the bulk
case is replaced by a surface recombination velocity,
sn , p
n, p
N ts
3k BT
mn*, p
The surface recombination velocity is treated as an input parameter in DEVICE, chosen to

reflect the non-ideal nature of the material surface. The surface recombination velocity may
be temperature dependent. Like the bulk case, the constants n1s and p1s are calculated as
n1s
niee Ets / k BT
p1s
niee
Ets / k BT
References
1.
2.
3.
4.
4.3
Slotboom, J.W., Solid-State Electron., 20, 279 (1997)

Caughey, D. M. and Thomas, R. E., Proc. IEEE, 52, 2192 (1967)
Masetti, G., et al., IEEE Trans. Electron Devices, ED-30, 764 (1983)
Klaassen, D. B. M., Solid State Electronics, 35, 953 (1992); Klaassen, D. B. M.,
Solid State Electronics, 35, 961 (1992)
Mesh order
The mesh order property governs how overlapping objects are meshed in the simulation. It
serves no role for objects which do not overlap. The mesh order can be set at the material
level (in the material database), or the object object level (in the object properties).
Materials with a lower mesh order take priority over materials with a higher priority number
(i.e. order 1 takes priority over 2). Areas which overlap are assigned the material
properties of the higher priority material (see the following figure).
Material database
55
In the figure to the left, there are two

objects that partially overlap.
Depending on their mesh orders, the
object that is actually being
simulated will be different.
In the event that both overlapping materials have the same order, the mesh order will be
inferred from the Object tree. Objects at the bottom of the tree will take priority over objects
at the top of the tree. To ensure your simulation is well defined, it is recommended that
you avoid situations where two different overlapping structure have the same mesh order.
Tip: Plot the geometry after meshing to confirm that the structures was meshed as
intended.
56
Reference Guide
Simulation objects
There are several types of simulation objects in
FDTD Solutions, MODE Solutions' propagator,
MODE Solutions' Eigenmode Solver and DEVICE.
These objects are used to model the physical
structure, define the solver region, any sources of
light or doping/generation regions as well as
monitors to collect data.
The following sections provide detailed descriptions

of each simulation object. Each simulation object
can be added by clicking on the corresponding
icon in the GUI.
For example, in the screen shot on the right,
clicking on the
button would add a circle
physical structure object.
Once the object is selected, pressing the EDIT
button will bring up a window where it
is possible to modify the properties of the simulation object. The corresponding window for
the circle object is shown below.
TIP: In-field equation interpreter

The fields for numeric parameters can be used as a simple calculator. For instance, if you
Simulation objects
57
wish to set a value to the square root of 3 divided by e, just enter sqrt(3)/exp(1) into the
field. For more information, see the Equation interpreter 76 section.
Notes:
Structure objects support Multi-object editing. If you select multiple objects then click
EDIT, you can edit properties that are common to all of the selected objects.
Monitors and sources have some global properties that apply to many objects. For
example, the global source frequency range can be applied to all sources. The global
properties can be edited with the GLOBAL PROPERTIES
button.
Groups
Simulation objects can be organized into various types of groupings.
Container Group
A container group is the simplest type and can contain all object types as well as other
groups. This object acts like a simple folder allowing the user to collapse and expand its
contents in the object tree. Its only user setting is a position offset in x,y,z for all
contained objects.
Structure Group
Structure groups are one step above container groups in that they allow scripting
commands of structures properties. This group contains user-generated variables and
scripts that can be utilized to edit and set up parts of the structure. For example, a script
can be set up to insert many circles to create a photonic crystal cavity of a certain shape
and size. See the Properties tab 65 and Script tab 65 sections for more information.
Structure groups can contain other structure groups.
The purpose of this section of the Reference Guide is to describe all of the available
simulation objects and their properties. This section is organized as follows. There are five
subsections. The first four subsections correspond to the four types of object categories.
Each of these sections begins with a brief overview of the simulation objects followed by a
description of their property settings. The properties are organized according to the tab that
they are located in when the EDIT button is pressed. The last of the five subsections
describes the syntax for the equation interpreter.
58
Reference Guide
5.1
Structures
Structures in a simulation interact with light/electrical sources to produce interesting
effects. They are split into 3 groups:
Structures (Primitives)
These are the primitive shapes that make up all structure setups.
Imports
These options open windows that can be used to import structure data from other sources
such as pictures or text files.
5.1.1 Primitives
The
button includes options to to add the following primitive structures:
Triangle
Triangular objects denote physical objects that appear triangular from above. For 2D
simulations, these objects represent triangles while in 3D these objects are extruded in the
z direction to a specific height. They are actually polygon objects, with the number of
vertices set to 3.
Rectangle
Rectangular regions denote physical objects that appear rectangular from above. For 2D
simulations, these objects represent rectangles while in 3D these objects are extruded to a
specific height.
Polygon
Polygons allow the user to define a custom object with a variable number of vertices. The
location of each vertex can be independently positioned within a plane, and the vertices are
connected with straight lines. For 3D simulations, the object is extruded in the z
dimension. In DEVICE, the vertices have to be entered in a counter clock wise manner for
the structure to be defined and meshed properly.
Simulation objects
59
Circle
Circles denote physical objects which appear circular or ellipsoid from above. They are
either circles/ellipses in 2D, or circular/ellipsoid cylinders in 3D.
Ring
Ring regions represent physical objects that consist of full or partial rings when viewed from
above. Rings in 3D simulations are extruded in the z direction to a specific height.
Sphere
In 3D simulations, users can define spherical regions of constant refractive index through
the spherical physical object. Spherical objects only exist in 3D simulations.
Pyramid
Pyramids can be configured to half flat tops and/or flat bottoms, and either narrow or
expand in the vertical z direction. Pyramids are only available for 3D simulations.
5.1.2 Geometry tab

The geometry tab contains options to change the size and location of the structure.
5.1.3 Material tab

The material options are as follows:
MATERIAL: This field can be set to any material included in the material database. It is
possible to include new materials in the database, or edit the materials already included.
See the material database section for more information.
OVERRIDE MESH ORDER FROM MATERIAL DATABASE: Select to override the mesh
order from the material database and manually set a mesh order. The mesh order is used
by the simulation engine to select which material to use when two materials overlap. See
the mesh order 54 section for more details.
MESH ORDER: Set the mesh order in this field if the OVERRIDE MESH ORDER FROM
MATERIAL DATABASE option is selected. If the option is not selected, the field displays
the material's default mesh order from the database. For example, a material of mesh
order 1 will take precedence over a material of mesh order 2.
60
Reference Guide
5.1.4 Rotations tab

Rotate objects by setting the following variables:
FIRST, SECOND, THIRD AXES: Select rotation axis. Up to three different rotations can
be applied.
ROTATION 1,2,3: The rotation of the object in a clockwise direction about each axis,
measured in degrees.
5.1.5 Graphical Rendering tab

The graphical rendering tab is used to change how objects are drawn in the layout editor.
The options are:
RENDER TYPE: The options for drawing the objects are detailed or wireframe. Detailed
objects are shaded and their transparency can be set using OVERRIDE COLOR
OPACITY FROM MATERIAL DATABASE.
DETAIL: This is a slider which takes values between 0 and 1. By default it is set to 0.5.
Higher detail shows more detail, but increases the time required to draw objects. This
setting has no effect on the simulation.
OVERRIDE COLOR OPACITY FROM MATERIAL DATABASE: When unselected the
opacity is determined from the material database. When selected, you can specify a
value for ALPHA between 0 (transparent) and 1 (opaque) for the object, depending on
how transparent you want the object to be.
5.1.6 Import Data tab
The
button includes options to import from a variety of formats:
GDSII
This file format is commonly used to store 2-dimensional geometric data. For details, see
GDSII Import 60 .
5.1.6.1 GDSII Import
The GDSII import function allows you to import structures from a GDSII file into the layout
editor. The GDSII file format is commonly used to store 2-dimensional geometric data. This
data can be directly imported into a 2D layout environment, or it can be used to import 3D
objects into a 3D layout environment by extruding the 2D data in the Z dimension.
Characteristics of the GDSII file

Simulation objects
61
Lumerical products support most, but not all features of the GDSII file format. Unsupported
features should not prevent the file from being imported, however, the results may not be as
expected. The following table details the supported and unsupported features.
Features
Supported
General
Multiple cells in GDSII library file
Yes
Layer numbers for drawing objects
Yes
Primitives/Objects
Box/Rectangle
Yes
Polygon
Yes
Path (see note below)
Yes
Node
No
Text
No
Symbolic cell reference
Yes
Array cell reference
Yes
Advanced
Cell references in external library/file
No
Magnifications in array and symbolic

references
Yes
Rotations and mirroring in array and

symbolic references
Yes
Note: Path corners

Path objects in GDSII files are piecewise linear lines plus a width and optionally some
information on how to handle corners and ends. In general, GDSII files support several
types of corner style options (squared, rounded, extended squared, etc). Our import
function supports type 0 (squared ends flush to the end-point) and will default to type 2
62
Reference Guide
(square ends with 1/2 the width added to the end-point) for all other types.
Note: Flattened GDSII files
While we do include scale, rotate, flip, and automatic flattening of references, not all
features of GDSII are currently supported. If you run into any problems, you may have
better results by flattening the file first.
GDSII Import
Import using GUI
GDSII import is initiated by accessing the IMPORT->GDSII option from the FILE menu, or
by pressing the Import GDS button located on the main toolbar. This will bring up a
standard file browser, which will allow you to select a file with the extension .gds or .db.
Selecting a GDSII file will bring up the Single layer GDSII Import window as shown below.
The following 3 input parameters control how the GDSII data is imported:
Cell name: This selection menu contains the valid cells available in the GDSII library.
Select the cell you wish to import.
Layer number: This selection menu contains all of the layer number present in the GDSII
file. Only structures with the selected layer number will be imported by this operation.
Material: This selection menu contains a list of the valid materials in your current
simulation environment. This material will be assigned to the imported structures.
Selecting the Import layer button imports all the structures with the selected layer number
in the selected cell into the layout environment. These structures are automatically inserted
Simulation objects
63
into a structure group. The material is set as an input parameter for the structure code, and
the script in the structure group sets all the objects to the desired material. The name of
the structure group includes the original number of layers. For 3D simulations, the structure
group contains a variable "z span". This used to set the width of the layer in the z direction.
The origin of the structures, as well as their orientation, can be changed by changing the
properties of the structure group.
Import using script command
The GDSII file can also be imported via script, the command gdsimport can be used. For
more information of the script commands, please visit Reference Guide - GDSII chapter 281 .
See Also
Userguide - GDSII - Import and export
5.1.6.2 Surface import window
Options in the surface import window include:

After surface data has been imported, the Import data tab allows the following properties to
be modified:
IMPORT: You can import new data into the object, or clear the imported data via a
simple GUI. For properties of the import GUI, see bottom of page.
X,Y FINE SCALE ADJUSTMENTS: Re-scale the object X,Y span. Modifying these
properties will change the X,Y span properties. Z SCALE property not used for surface
import.
DATA SIZE: These properties provide some information about the imported data. They
are read-only.
LOWER, UPPER REF HEIGHT: Set the vertical location of the reference plane (height=0
in the imported data). Modifying these properties will change the Z, Z span properties.
Note: Related properties
It is important to notice that the 'x, y scale' and 'x, y span' properties are linearly related.
Doubling the object 'x span' will automatically double the 'x scale' property.
Similarly, the 'lower, upper ref height' properties are related to the 'z and z span' properties,
although the relationship is slightly more complex. See the following figure for details. The
surface's can be truncated by setting the 'z span' property to a small value.
64
Reference Guide
Note: Overlapping surfaces

If the z span is small enough such that the upper and lower surfaces overlap (as shown
below), no structure will be included in the simulation in that region.
For additional information and example files, see the Import object surfaces page in the
User Guide section of the Online help.
Import surface GUI settings:
SELECT FILE: let the user specify the data file to be imported.
X0, Y0, Z0: the data origin in the global coordinates of the Graphical Layout Editor.
X,Y: This defines the span of surface that you are importing.
INVERT X AND Y AXIS: It is often easy to invert the x and y axis when exporting the file.
Selecting this checkbox means that the x and y axes are automatically reversed.
UPPER SURFACE, LOWER SURFACE: Choose which surface is being imported.
FILE UNITS: Select units for the data in your file.
Simulation objects
65
5.1.7 Properties tab

The properties tab is only available for structure groups. The properties tab is used to set
the origin of the group, and to create the custom properties of the group that are the inputs
of the group script. Custom user property variables may be added with the ADD button,
and removed with the REMOVE button. Each user property has a name and a type
(number, frequency ect). The user properties can be set manually in the edit GUI or through
script commands. For more information and examples, see the Structure groups page of
the User Guide section of the Online Help.
5.1.8 Script tab

The script tab is only available for structure groups. The script tab can contain script
commands that are used to set up a structure or edit the properties of structures located
within the structure group. The structure group has access to the user variables defined in
the PROPERTIES tab, and can change properties of any objects that are contained in the
group. The script does not have access to objects which are not located in the group, and
does not share the same variable space as the script prompt.
The script is run every time the TEST or OK button is pressed, or when one of the user
properties is changed with a script command.
The following buttons and regions are available in the script tab:
SCRIPT: This is where the script commands are written. To find a list of script
commands, see the Scripting Language 108 section of the Reference Guide.
TEST/SCRIPT OUTPUT: Press the TEST button to run the script. If there are no syntax
errors in the script the SCRIPT OUTPUT will read <script complete>.
For more information and examples, see the Structure groups page of the User Guide
section of the Online Help.
5.2
Simulation
Simulation objects are used to define simulation parameters like boundary conditions and
mesh size.
Simulation region
The simulation region defines most simulation parameters including the size and mesh
size.
Mesh Constraint
The mesh constraint region is used to override the default mesh element area in some part
of the simulation region. Normally the meshing parameters are set in the Simulation
66
Reference Guide
region. However, if some specific meshing conditions are required in part of the simulation
region, a mesh constraint region can be specified.
Note that only one simulation region per simulation is supported, but multiple mesh
constraint regions may be used.
TIP: Objects which lie outside the simulation region.
Any simulation objects contained or partly contained within the simulation region are
included in the simulation, while any objects which fall completely outside of the
simulation region are not included in the simulation. Those physical structures (and
portions thereof) lying within the simulation region are included in the simulation (i.e. the
simulation is performed on that portion of the physical structure lying within the simulation
region). Physical monitors and sources are treated in a similar fashion, such that any
portion of a monitor or source lying within a simulation region will be used. The user is
warned when at least one source or monitor falls completely outside the simulation
region.
5.2.1 General tab

The options in the general tab depend on whether the item being edited is a simulation
region or a mesh refinement region.
Simulation region
The simulation region contains several settings:
SIMULATION TEMPERATURE (K): The temperature in Kelvin at which the simulation will
be done.
SOLVER GEOMETRY: This drop down menu gives the choice of a 2D simulation plane
or a 3D simulation.
NORM LENGTH: The length of the device in the direction perpendicular to the plane of
the simulation; any normalizations length will be with respect to this value.
SOLVER MODE: DC mode for dc simulations and transient mode for time dependant
simulations. The color of the simulation region will change depending on which option is
picked. Also, the available options in the contacts table will change accordingly.
CONTINUE FROM PREVIOUS SOLUTION: If this option is checked, the user has the
choice to specify a file that has already been run with a solution. This solution will be
used as the starting point for the Newton solver. In simulations where the starting point
isn't at zero volts, this can be very useful to save time.
.
Mesh Constraint region
For the mesh constraint region, the maximum element area can be set.
Simulation objects
67
5.2.2 Mesh tab

Global Mesh Constraints
The global mesh settings section contains several settings:
MAXIMUM EDGE LENGTH: The maximum length of an edge of a triangle (in 2D) used in
the mesh.
MAXIMUM EDGE LENGTH: The minimum length of an edge of a triangle (in 2D) used in
the mesh.
TRIANGLE QUALITY: The quality of mesh triangle, defined the minimum angle used in
the triangular mesh cells. The higher the angle, the higher the quality of the triangle
Auto Refinement Settings
The auto refinement settings section contains several settings:
MAX REFINE STEPS: The automatic refinement proceeds in multiple stages, creating a
quality triangulation and refining the mesh according to the change in doping density and,
if present, optical generation rate. This setting limits the number of refinements at each
stage, and corresponds to the number of vertexes that can be added to the mesh at each
stage.
SENSITIVITY: This setting controls the threshold at which the mesh will be refined due to
the gradient in the doping density or optical generation rate. The default value will roughly
correspond to a limit of a factor of 2 change in the doping density or generation rate over
the span of an element in the mesh.
5.2.3 Geometry tab

The geometry tab contains options to change the size and location of the simulation or
mesh refinement region.
5.2.4 Transient tab

Transient Simulation Controls
The transient simulation controls section contains several settings:
MIN TIME STEP: The smallest time step that will be used in the transient simulation
(used as the initial time step)
MAX TIME STEP: The largest time step that will be used in the transient simulation.
Downsampling
DOWN SAMPLE MODE: The type of downsampling to use, None, for no downsampling,
count, for specifying the number of point to downsample at, and interval to specify the
downsample step size.
Global Optical Shutter
68
Reference Guide
The global optical shutter will apply a shutter to all the optical generation objects in the
simulation.
SHUTTER MODE: disabled, for no shutter, step on and step off for step functions, pulse on
and pulse off for a pulse with on and off times. The time shutter function will be plotted as
the option is chosen for ease of use. The on and off times can then be specified.
5.2.5 Results
This tab contains a list of all the spatial results that can be recorded throughout the
simulation. One can pick to enable or disable one or more of the results to save memory as
needed.
5.2.6 Advanced options tab

WARNING: This tab includes options which should only be changed if you are quite
familiar with the meshing algorithm and techniques used .
DEVICE:
DEVICE:
SOLVER TYPE can be set to gummel or newton. Please see this page 69 to learn about
the function of each solver type.
MULTITHREADING if enabled, the user can choose to divide up and run the simulation over
multiple threads
FERMI STATISTICS if enabled, fermi statistics will be used in the solvers. Please see this
page 70 to learn more about the details of the fermi statistics model.
The following applies to both sections on Poisson Solver Controls and Drift-Diffusion Solver
Controls:
USE DEFAULTS: checked by default, will use an iteration limit of 40, absolute tolerance of
1e-06 volts and a maximum update value of 5 volts.
ITERATION LIMIT: Takes a value between 1 and 10000. This limits the number of iterations
of the Poisson or drift-diffusion solver that may be run.
ABSOLUTE TOLERANCE: For a calculation to be considered converged, this determines
the maximum absolute change between iterations that can exist. For the Poisson solver,
the step converges when
Vk
Vk
where is the tolerance and V is the electrostatic potential. For the drift-diffusion solver,
both the electron and hole quasi-Fermi levels must converge:
Simulation objects
69
k 1
k
E Fn
E Fn
k 1
k
E Fp
E Fp
MAXIMUM UPDATE: To help the calculation converge, the maximum change that will be
applied to estimate the solution at the next step can be clamped. This value is in multiples
of the thermal voltage (kT/q).
Initialization:
INITIALIZATION: disabled by default, but can be enabled if the start bias in a voltage sweep
is far from the solver's initial guess. More steps will help bring the initial guess closer to the
start value but will cause the simulation to take longer.
5.2.7 Solver type

DEVICE simultaneously solves the equations for the electrostatic potential (Poissons
equation) and charge (drift-diffusion equations). The solutions to these equations must be
self-consistent, i.e. the charge calculated from the drift-diffusion equations satisfies the
Poisson equation, and vice versa. Two common approaches are used to solve this system
of equations: Gummels method and Newtons method.
Gummels method decouples the charge problem from the electrostatic potential problem
at each step. As both of these equations are non-linear, they must in turn be solved using
an iterative or direct method. First, the electrostatic potential is solved holding the charge
fixed. Next, this solution to the electrostatic potential is used as a fixed input to the charge
equations, and those are updated. This process continues until the solution is selfconsistent. Gummels method is stable and efficient for devices where the currents are
small and the variations in the charge distribution are not too extreme (meeting the criteria
that the charge and electrostatic potential are weakly coupled problems). Gummels
method should not be used for transient simulations or simulations involving high levels of
charge injection.
Newtons method is the classic approach to solving a system of non-linear equations. In
this method, the electrostatic potential and charge are solved for simultaneously, and all
are updated at each step. Newtons method requires a good initial guess in order that it will
converge, and can be more difficult to converge than Gummels method. However, Newtons
method can handle devices where the variations in charge density are large. Newtons
method must be used for transient simulations.
70
Reference Guide
5.2.8 Fermi statistics

Electrons and holes are fermions, and therefore obey Fermi-Dirac statistics. At a finite
temperature, the energy distribution of the electrons is described by the Fermi-Dirac
function,
where k is the Boltzmann constant, T is the temperature, and Ef is the Fermi energy.
When E-Ef>>kT, the Fermi-Dirac distribution can be approximated by the Boltzmann
distribution,
Often in semiconductor devices, when the net doping density is sufficiently low (nondegenerate), the Fermi energy is located within the band gap (carriers are forbidden from
having energies within the range of the band gap), far from the band edges. When the
condition E-Ef>>kT is satisfied (typically for |E-Ef|> 3kT), the Fermi-Dirac distribution can
be replaced with the Boltzmann distribution.
The carrier density is calculated from the integrated product of the Fermi-Dirac distribution
(probability of occupancy) and the density of states (available states to occupy). For
electrons, the equation is
When the Fermi-Dirac distribution is used, this integral does not have an analytic solution,
and must be approximated numerically. However, for non-degenerate conditions, the FermiDirac distribution is approximated by the Boltzmann distribution, and the preceding
equation reduces to
describing the electron density at equilibrium (Nc is the effective density of states and is a
constant related to the specific properties of the semiconductor).
5.3
Monitors
The following types of monitors are available in DEVICE:
Simulation objects
71
Charge monitors
Charge monitor records electron and hole densities in the monitor space. It can also
integrate the total charge within the monitor surface/volume.
Electric Field monitors

Electric field monitor records the electric field within the monitor region as well as the
electrostatic potential. Using this information, it can also calculate the total charge within
the monitor surface/volume.
5.3.1 General tab
Charge monitor
MONITOR TYPE: The monitor geometry can be chosen. It can be a point, a line in any
direction, a plane normal to any of the axis or a 3D monitor.
RECORD ELECTRONS/HOLES: If this option is checked, the electron/hole densities will
be recorded. These will be in units of 1/cm^3 for both n and p.
TRUNCATE MESH: Since the generated mesh is triangular and the monitors are
rectangular, if this option is chosen, the mesh points will be interpolated onto the monitor
boundaries.
INTEGRATE TOTAL CHARGE: The total number of electrons/holes will be calculated
within the monitor surface/volume. This will be in unitless ( total number of charged
carriers) in 3D and in units of 1/m ( number of carriers in a meter) in 2D for both n and p.
Electric field monitor
MONITOR TYPE: The monitor geometry can be chosen. It can be a point, a line in any
direction, a plane normal to any of the axis or a 3D monitor.
RECORD ELECTRIC FIELD: If this option is checked the electric field across the monitor
is recorded.E will be in units of volts/m.
RECORD ELECTROSTATIC POTENTIAL: If this option is checked, the electrostatic
potential across the monitor is recorded. V is in units of volts.
CALCULATE NET CHARGE: If this option is checked, the net charge within the monitor
surface/volume is calculated using Gauss's law by integrating the electric field flux
through the box surface. The results are in units of Coulombs in 3D simulations and
Coulombs/m in 2D simulations.
72
Reference Guide
5.3.2 Geometry tab

The geometry tab contains options to change the size and location of the monitors.
5.4
Generation
The following types of Optical generation objects are available to be superimposed on the
structure in DEVICE:
Bulk Generation
The bulk generation object allows the user to define a region of bulk optical generation. The
region geometry as well as the parameters below can be specified:
ILLUMINATION FACE: The direction of illumination can be chosen by picking one of the six
sides of the cubic region.
SPECTRUM: The spectrum of the illumination can be chosen. For example, solar (AM
1.5G) will import the spectrum of the sun.
MATERIAL: The semiconductor onto which the generation is superimposed can be chosen
from this drop down menu.
INTERFACE REFLECTION: Either an air interface or an anti reflective coating interface can
be chosen as the boundary of the generation region. In the case of the ideal anti reflective
coating, all light will be assumed to penetrate into the semiconductor, whereas in the air
interface case, reflections from the air-semiconductor interface could take place.
A plot of the generation rate versus position will be generated on the bottom right corner of
the edit window.
Import Generation
The Import generation object allows the import of a user defined optical generation region.
The location of the object is specified via the edit window.
IMPORT NEW DATA: opens file browser to select data file. The file must be in Matlab
format (.mat) and contain fields "x", "y", "z", and "G", where "x", "y", and "z" are 1D arrays
specifying the rectilinear grid, and "G" is a 3D array (with dimensions NX x NY x NZ
corresponding to the rectilinear grid) whose entries are the optical generation rate in units of
m-3s -1.
5.5
Doping
The following types of Doping objects are available to be superimposed on the structure in
DEVICE:
Simulation objects
73
Constant Doping Region

The constant doping object allows the user to define a region with constant doping. The
region geometry as well as parameters can be entered.
DOPANT TYPE: The dopant type can be n-type (donors) or p-type (acceptors).
CONCENTRATION: The concentration of the dopant can be entered.
Diffusion Region
The diffusion region object allows the user to define a region with a dopant concentration
profile. The region geometry as well as parameters can be entered.
SURFACE CONCENTRATION: The concentration of the dopant at the surface (the peak
concentration) can be entered.
FACE: The side of the region where the surface concentration is defined (i.e. where the
diffusion source originates). For example, "upper y" refers to the face defined by "y max".
JUNCTION WIDTH: The width of the doping profile from surface (peak) concentration to
reference concentration at the edge of the diffusion region.
DIFFUSION FUNCTION: The doping concentration profile, can be gaussian or the
complementary error function (erfc).
REFERENCE CONCENTRATION: The doping concentration on the exterior of the box
(excluding the originating face).
Import Doping Region

The Import doping object allows the import of a user defined spatial doping profile. The
location of the object is specified via the edit window.
IMPORT NEW DATA: opens file browser to select data file. The file must be in Matlab
format (.mat) and contain fields "x", "y", "z", and "N", where "x", "y", and "z" are 1D arrays
specifying the rectilinear grid, and "N" is a 3D array (with dimensions NX x NY x NZ
corresponding to the rectilinear grid) whose entries are the doping concentrations in units of
cm-3.
74
Reference Guide
5.6
Contacts
The Contacts table allows the user to define electrical contacts in the simulation region and
assign a bias to them.
The add/delete/edit buttons can be used to add a new contact, delete a contact or edit the
properties of a contact respectively.
The name of the contact can be typed in the Name column, the geometry of the contact
can be picked from a drop down menu from the choices available according to the
simulation objects. The contact can be set to Ohmic, Schottky or None.
SOLVER MODE: The mode of the solver is consistent with the mode picked in the
simulation region and can be set to dc to transient.
DC MODE:
In the DC mode, the bias assigned to each contact can either be fixed at a value or swept
over a range of DC values. In the sweep case, the start and stop biases as well as interval
and the number of points in the sweep can be specified. Alternatively, the user can
manually enter a range of values for the voltage to sweep over. Series and shunt resistors
can also be added to the voltage source to model more complicated circuits.
Simulation objects
75
TRANSIENT MODE:
In the transient mode, the bias assigned to each contact can either be fixed at a value
( this is the same as the fixed bias in DC mode) or transient, swept over a range of time
dependant values. In the transient case, the values for each voltage point as well as the
time point can be entered in a table. Series and shunt resistors and capacitors can also be
added to the voltage source to model more complicated circuits. The resistance and
capacitance for these elements can also be specified as a function of time. If only one point
is specified in the table, then a constant value is assumed for that element. The values for
the voltage Rs and Cs will be linearly interpolated in time for consistency.
76
Reference Guide
5.7
Equation interpreter
The fields for numeric parameters can be used as a simple calculator. For instance, if you
wish to set a value to the square root of 3 divided by e, just enter sqrt(3)/exp(1) into the
field. The expression will be automatically evaluated when you press Enter or click on a
different field. Equations which become undefined (i.e. 1/0) should be avoided.
The following table provides a list of available operators and constants.
Category
Syntax
Algebraic operators
+, -, *, /
Trigonometric operators
sin, cos, tan,

asin, acos, atan, atan2,
sinh, cosh, tanh
Power operators
^ or **, exp, log10, log, sqrt
Logical operators
>, <, >=, <=, ==, !=
Other operators
abs, mod
Constants
c - Speed of light in m/s

pi - The value of Pi
Examples
2^10
sqrt(3)/exp(1)
sin(45*pi/180)
Running simulations and analysis
77

This section describes the general operations of running a simulation and performing an
analysis. Information on how to set up optimization and parameter sweep projects is also
described here. The contents are organization into the following chapters. For more
information on datasets, see Introduction to datasets 141 in the Scripting chapter.
Resource Manager 77
Running a simulation 80
Analysis tools 81
Visualizer 83
Results View 93
Optimization and parameter sweeps
6.1
97
Resource Manager
Before running any simulations, the computing resources must be configured. This is done
through the resource manager. It can be easily accessed by pressing the resources button
in the main toolbar. These settings are saved on a per user basis. For more
information, see the Parallel computing video.
In DEVICE, the "Processes" field is disabled since distributed simulations are not
permitted.
Resource Configuration
78
Reference Guide
USERS WITH A SINGLE LICENSE
Resources
This section allows the number of processes for localhost to be changed as well as the
name. For advanced configuration options, see Resources Advanced Options 79 .
Configuration test
Run tests to make sure MPI username and password are set correctly. It also performs
other checks such as engine path verification. If the tests pass, then we can be sure that
the current simulation will run.
USERS WITH EXTRA ENGINE LICENSES
Resources
If you have extra engine licenses and Lumerical software installed on other computers on
the network, they can be added as additional computation resources to perform multiple
simulations in parallel. This is especially useful for parameter sweeps and optimization
projects where many iterations need to be performed. The resources can easily be turned
on and off depending on whether they are free to compute at the time.
Requirements of each additional resource:
Must be the same operating system as localhost
Must be the same system type as localhost (cannot mix 32-bit with 64-bit)
Must have the same version of Lumerical software as localhost
Must have the same version of MPI as localhost
Must have a user account with the same login and password as localhost
Must have access to the simulation files via a network drive
To add a new resource:
1. Click the add button.
2. Set 'active' if you plan to use the resource right away or 'inactive' if you plan to enable it
later
3. Set a name for that resource
4. Specify the IP address of the hostname that the computer uses on the network
5. Set the number of cores that you would like it to use
6. Set any advanced options.
If many resources have advanced options that need to be changed, the 'Duplicate' button
will be useful.
Configuration test
This section of the window is used to test the communication to the additional resources.
It runs a series of tests and will report any warnings or errors that may prevent a distributed
simulation from running such as mismatched software versions, user credentials or
communication problems.
79
6.1.1 Resources Advanced Options

Advanced Options
Each resource can
have customized
settings if required.
Resource advanced options

MPICH OPTIONS
JOB LAUNCHING: Whether or not to tell mpiexec to spawn processes in local session or
via remote job launcher. The default setting is "Bypass mpich daemon on localhost", which
will add the localonly command line option and skip the host command line options (only
if the host name is localhost). The setting "Standard", adds the argument -host <IP/
Hostname>. The last setting "Bypass mpich on localhost" will exclude mpich entirely.
USE PROCESSOR BINDING: Tells mpiexec to specify which CPU each process will run
on, when mpiexec supports it. On Windows, it adds the binding option with the value
computed through the lumnuma class. This option is not supported on Linux and Mac.
Customers interested in this functionality on Linux and Mac should consider using numactl.
EXTRA MPIEXEC OPTIONS: Allows the user to specify advanced options to mpiexec. If
set, the specified mpiexec path is used instead of the default mpiexec co-packaged with
the software.
SUPPRESS ANY DEFAULT MPIEXEC OPTIONS: removes the default arguments in the
mpiexec command
SET MPIEXEC ENGINE PATH: Allows the user to specify the path to their mpi executable.
PRODUCT OPTIONS
CREATE LOG FOR ALL PROCESSES: Each parallel process will create a log file. Adds
80
Reference Guide
the logall command line option.
EXTRA COMMAND LINE OPTIONS: Allows the user to specify advanced options to
engine. Appends the text immediately after the engine command.
SET ENGINE PATH: Allows the user to specify path to product engine. If set, the specified
path is used instead of the default path which is relative to the executable binary.
The bottom window displays the final command which will be used to run the simulation.
6.2
Running a simulation
When the simulation setup is complete and the resource setup passes the configuration
tests, it is time to run the simulation. Clicking on the RUN button

in the toolbar will
launch the job monitor window with the simulation already running. If you have not already
saved your simulation, you will be prompted to do so. The simulation project file must be
saved in order to run after which the data can then be analyzed.
The job monitor window allows you to see the status of your jobs, as well as allowing you
to pause or quit the jobs. Errors that occur during the simulations are displayed here.
Job Manager
The elements of the job monitor window are as follows:
ENGINE: Shows which computational resource is being used. The name is specified by
the user.
STATUS: Shows the state of the job. e.g. running, paused, finished
PROJECT FILE: Shows the location of the file that is being simulated.
MESHING STATUS: Indicates the status of the meshing process; If the mesh has
already been calculated, the status will be "Loaded". If not, the status will calculate the
mesh starting with "Applying global constraints", then "Refining mesh by doping", and
then "Finished".
BIAS POINT: Shows the bias point step as the simulation loops through all the specified
contact bias values. For example 2/25 implies that the simulation is currently running for
the second bias point out of 25 specified points.
PROGRESS: Shows the percentage of the time taken so far as compared to the
81
maximum time remaining.

QUIT & SAVE: Stops the simulations and saves the data obtained up to that point. The
program will be in Analysis mode.
QUIT & DON'T SAVE: Stops the simulations and does not save any data. The program
will be in Layout mode.
FORCE QUIT: Closes the job monitor window and forcefully terminates all simulations.
This option should ONLY be used when the other Quit options don't work properly.
When simulations are stopped with Force Quit, they may not check-in their license,
which means you may have to wait several minutes before another simulation can be run.
No simulation data will be saved.
TOTAL PROGRESS BAR: The progress bar indicates how much of ALL the simulations
are complete, with the length of the progress bar is determined by the sum of the
maximum simulation times.
To access actions for each job, right-clicking anywhere on the row will bring up a context
menu with the following options:
PAUSE: the engine is signaled to go into a wait mode (it will stay running, but not
consume CPU)
CONTINUE: restarts a paused job
QUIT AND SAVE: The engine will stop the current simulation job and attempt to save the
data created so far.
QUIT AND DON'T SAVE: The engine will stop the current simulation job and does not
save any data.
FORCE QUIT: Forcefully terminates the current simulation job and does not save any
data. This options should ONLY be used when other Quit options don't work properly.
When simulations are stopped with Force Quit, they may not check-in their license,
which means you may have to wait several minutes before another simulation can be
run.
VIEW JOB DETAILS: Opens up a modal dialog that contains the standard output
messages from the engine processes.
Note: More information
For more information about running Lumerical simulations, including running on clusters,
using a job scheduler, preparing batch files, and using extra engine licenses, see the
Online Help section User Guide - Running Simulations.
6.3
Analysis tools
This section describes the way in which the integrated analysis routines are used to
visualize and analyze simulation data. The manner in which the analysis routine interacts
with the overall simulation environment is described in the next section:
Analysis tools and the simulation environment 82 . This is followed by sections to
familiarize the user with the operation of the analysis routines.
82
Reference Guide
In the first section, the two general ways in which data can be visualized and analyzed is
detailed. The plotting functions, a central component to the overall analysis routines, are
described in Figure windows 82 section. The section entitled Data export 83 describes
data can be exported to plot in other software packages for further analysis or formal
presentation. More advanced analysis can be performed with the extensive scripting
language, as described in the Scripting language 108 section. Finally, visualization of the
results and data using the Visualizer 83 feature is explained.
6.3.1 Analysis tools and the simulation environment

Before describing how the analysis routines are used for data visualization, it is important
to understand the way in which the integrated analysis tool interacts with the simulation
environment. Following the completion of a simulation, the simulation data is written into
the simulation project file; even premature termination of a simulation results in a partial
dataset being written to the file. When the simulation completes and the EXIT button is
pressed, or the simulation is prematurely terminated by pressing the EXIT button, the
project file will be in Analysis mode, meaning that any modification of the data will require
switching back to the layout mode.
In Analysis mode, simulation object properties can be viewed, but not edited. This ensures
that at any given time, the simulation data results corresponds to the configuration of the
simulation project. Once in the analysis tool, the user continues to analyze the simulation
data until they either wish to close the application, or they decide they would like to alter
the simulation objects and re-perform the simulation. By exiting the analysis routines and
returning to the layout editor, existing simulation data will be erased.
6.3.2 Figure windows for plots and images

Simulation results can be visualized using 1D line, 2D surface and 3D vector field plots.
These plots can be created from within the results visualizer, or from the scripting
language.
The figure window controls are slightly different for each type of plot. For example, only the
3D vector plot provides controls for 3D rotation of the view. All plots support operation such
as axis labels, zoom, export to JPG, etc.
83
6.3.3 Data export

In some cases, the user may wish to export the simulation data to take advantage of the
advanced plotting and data analysis tools not available in Lumerical's products. Data export
can be done in a number of ways, but in general the use of the scripting language will be
required. The write 123 script command can be used export data to a text file, or the
matlabsave 124 command can be used to save data to .mat files. Results stored in
datasets can also be export to Paraview (for sophisticated data visualization) with the
vtk save 128 command.
6.3.4 Visualizer
The Visualizer is a tool for analyzing data. Simulation data from a variety of objects
(monitors, parameter sweeps... etc) can be sent to a Visualizer.
Data that gets added to the Visualizer is retained until it is removed (ie. with the "Remove"
button or by pressing "X" on the top right corner of the window). This is useful for
comparing results across different data sets. The upper-left portion of the window is the
plot area, which displays the current data defined by the settings in the upper-right of the
window (plot settings). The following sections describe the many options available for
controlling what data will be displayed in the plot area. These sections can be minimized if
more area for plotting is required.
Visualizer controls 85
Visualizer attributes 91
Visualizer parameters 92
84
Reference Guide
Visualizer
The surface plot option is also used to plot a number of 3D results. The plot will contain a
3D outline of the structure and the results are shown on a planar cross section of that
outline. To change the plane position and/or orientation, move the arrow perpendicular to
the plane, grabbing it with a mouse left click much like a drag action.
85
See the Visualizer video in the online User Guide for additional information on the visualizer.
6.3.4.1 Visualizer controls
The settings control the overall type

of plot and the labels applied to it.
Plot type: select Line, Surface or
Vector plot
Manual plot: Disable auto-refresh.
Useful when visualizing large
datasets.
Export to: export figure to JPEG,
text file or clipboard
View options: show/hide Attribute &
Parameter panes
Line plot: Choose this option to plot

a 1D vector versus another 1D
vector. For matrices with more than
1 dimension, a slice of the matrix
will be automatically chosen. You
can use the parameters table on the
bottom to choose which dimension
to slice and which to plot on the x or
y axis.
86
Reference Guide
Surface plot: Choose this option to

create a 2D image plot of monitor
data. For matrices with more than 2
dimensions, slices of the matrix will
automatically be chosen. you can
use the parameters table on the
bottom to choose which dimensions
to slice and which to plot on the x or
y axis.
Vector plot: Choose this option to
create a 2D/3D vector plot of monitor
data. Choose the parameters table
to slice a frequency point. It is
possible to create a vector plot of
quantities such as the electric field,
magnetic field, poynting vector, etc.
TIP: It is often more meaningful to
plot the poynting vector rather than
the fields. Plots of the electric field
will often contain vectors pointing in
different directions representing the
oscillation in the field direction. The
more interesting quantity to plot is
the poynting vector where the
direction of power flow can be
visualized.
TIP: It can be helpful to create an
electric field vector plot to study
circularly polarized or elliptically
polarized beams. See the example
on our knowledgebase.
The plot settings can be further edited by click on the pencil icon on the top left corner of
the plot window

For line plots, the following
are available:
TITLE: The title of the plot can
be specified
X/Y LABEL: The x and y
labels for the plot can be
specified
SET AXIS LIMITS: The x and
y limits for the axis can be
set
EDIT LEGENDS: The legends
for the plots can be specified
NUMBER OF TICKS: The
number of axis dividers on the
x and y axis can be specified.
The default is 10.
One can also choose to
show/hide the title and
legends, draw the x and y
axis at (0,0), plot multiple
figures using the same color,
plot the x and/or y axis on a
log scale, show/hide grids for
the axis and choose to show
the plots in grey scale.
87
88
Reference Guide
For surface plots, the
following are available in 2D
simulations:
PLOT TYPE: Can be a 2D
image plot or a 3D surface
plot. In the 2D image plot, the
values are indicated using the
color bar. In the surface plot,
the values are also plotted in
the third dimension.
SHOW: Can be "surface"
which will contain the values
at each mesh point only, or
"surface and mesh" which will
superimpose in black, the
mesh grids on top of the
plots, or "mesh only" which
will only plot the mesh grid in
color.
AXIS SCALE OPTIONS: Can
be "square" which will make
sure the two axis are plotted
to the same size, or "equal"
which will use the same scale
for both such that the plot will
be to scale.
LOG SCALE: Will plot the
result on a log scale.
LABELS: the x/y/z labels can
be specified.
COLOR BAR: The color bar
limits can be specified.
For surface plots, the

following are available in 3D
simulations:
SHOW: Can be "surface"

which will contain the values
at each mesh point only, or
"surface and mesh" which will
superimpose in black, the
mesh grids on top of the
plots, or "mesh only" which
will only plot the mesh grid in
color.
AXIS SCALE OPTIONS: Can
be "square" which will make
sure the two axis are plotted
to the same size, or "equal"
which will use the same scale
for both such that the plot will
be to scale.
LOG SCALE: Will plot the
result on a log scale.
LABELS: the x/y/z labels can
be specified.
COLOR BAR: The color bar
limits can be specified.
CLIP PLANE: The clip plane

can be shown on top of a 3D
surface plot. This plane can
89
90
Reference Guide
be defined by defining 2 (x,y,
z) vectors one of which is the
normal to the plane. For
convenience, there are also
the quick options of choose a
x normal/y normal /z normal
plane. This plane will be able
to cut through the the 3D
structure and give insight into
the inside of the 3D plot. The
inside out option will flip
which side of the plane is
shown.
91
6.3.4.2 Visualizer attributes
An attribute is a quantity to plot (ie. Power transmission vs frequency). Multiple attributes

can be sent to a single visualizer. When using line plots, each attribute will appear as a
separate line. When using image and vector plots, the selected attribute will be shown.
DATA SET: full data set name (can contain multiple attributes)
ATTRIBUTE: attribute name
VECTOR OPERATION: selects a particular component of a vector attribute e.g. (Ex, Ey, |
E|^2)
SCALAR OPERATION: selects a particular component of a scalar attribute e.g. (real,
imag, abs, angle)
92
Reference Guide
SCALE: multiplier for the data being plotted
LEGEND: this name will be shown in the legend of the plot
NOTES: additional information added by the user about the attribute
VIEW DATA: allows users to view the data in a table format as shown below
In this table format, users can select any portion of the data and "Copy" or "Export" it into a
text file. Alternatively, users can also send any portion of the data into the Script
Workspace 95 .
6.3.4.3 Visualizer parameters
In addition to the attributes, data sets also contain the associated position vectors (eg:
position, frequency).
93
ATTRIBUTES: Name of the associated attribute

PARAMETERS: Name of the parameter
ACTION: Control how the parameter is treated in the plot. For example, select which axis
to plot the parameter on.
VALUE: displays the value if it is a singular value or is blank if there is a vector of values
Plotting multi-dimensional attributes
Line plots
One parameter must be selected to plot on the X axis. All other non-singleton parameters
must be set to Slice. A specific slice can then be selected for those parameters.
Surface plots
Two parameters must be selected to plot on the X and Y axis. All other non-singleton
parameters must be set to Slice. A specific slice can then be selected for those
parameters.
Vector plots
The spatial dimensions (x,y,z) are always selected to plot on the X, Y, Z axes. All nonspatial parameters must be set to Slice. A specific slice can then be selected for those
parameters.
6.3.5 Results Manager

The Results Manager is a tool for analyzing simulation data. The Results View 93 window
shows all the results for the simulation object that is currently selected in the Object Tree.
The Script Workspace and Script Favorites 95 windows work in conjunction with the
scripting environment to provide additional GUI-based functionalities.
When used in conjunction with the Visualizer 83 , the Results Manager provides a very
useful and intuitive way of analyzing and visualizing variables and results through the GUI.
6.3.5.1 Results View
The Results View 93 window shows all the results for the simulation object that is currently
selected in the Object Tree. Any simulation object that have results will be displayed with
a symbol on the bottom-right corner. The name of the available results, and the
corresponding dimensions or are displayed. One can right click on any of the results to
display them in the Visualizer 83 , or to send the to the Script Workspace 95 for further
post-processing.
94
Reference Guide
With the use of datasets, allowing one to package raw data into meaningful results that can
be easily parameterized and visualized. The results for all the standard monitors can be
retrieved in the original raw, un-parameterized matrix form (using getdata), or in dataset
form (using getresult). For example, in the Results View figure above, the results listed
under rawdata can be obtained using the getdata command. The results listed under
"results" are datasets, and can be obtained using the getresult command (these
calculations will only be carried out when they are visualized). The icons associated with
each result reflect the type of result:
Matrix: this is a simple matrix result, with no associated parameters
Matrix dataset: this is a parameterized matrix results that contains at least an
attribute (result), and a associated parameter
Rectilinear dataset: this is a parameterized matrix result that is associated with a
rectilinear grid
Unstructured data: This is a set of data that is not structured in form of a dataset or
a matrix and rather consists of several different types of results
String
For more detail on how to work with datasets in the scripting environment, please see
Accessing simulation data in the User Guide. Analysis group objects from the Object
library have been updated to return datasets. For an example of how to define dataset
95
results in an analysis group, please see Using analysis groups.

The raw data results are all un-parameterized, simple matrix results. To create
parameterized matrix datasets from matrices, use the "Send to script" option to copy the
variable into the Script Workspace, and follow the instructions here 95 .
6.3.5.2 Script Workspace and Script Favorites
The Script Workspace shows all the variables in the current scripting environment. The
variables' current values as well as the corresponding dimensions are shown in a list
format. Users can use the Visualizer 83 to visualize any variable listed in the Script
Workspace by right-clicking on the variable and selecting "Visualize".
The icons in the script workspace above shows that while "sigmaabs" and "sigmascat" are
parameterized matrix datasets (since they were the results returned directly by the cross
section analysis groups), "sigmaext" is a result that we defined in the script, and is
therefore a simple un-parameterized matrix. For example, simply right-clicking on
sigmaext and selecting "Visualize" will generate the following plot in the Visualizer:
96
Reference Guide
Here, the extinction cross section is plotted as a function of the index value. To associate it
with the corresponding frequency array, select the "Create visualization" option, which will
open the "Visualization Creator" dialog window:
This window allows users to set the name of the parameterized variable (sigmaext_vs_f)
and its parameters (f). Once this is defined, the visualization creator will generate the
commands necessary for creating the parameterized dataset in the Script Favorites
window. When this command is ran, it will send the new parameterized variable to the
Visualizer, which will plot the variable as a function of the user specified parameter.
Generated Command
Generated Figure
97
In addition to the commands generated by the visualization creator, the Script Favorites
window also allows users to define their own favorite commands by selecting "New
command" and "Edit".
6.4
Optimization and parameter sweeps

This section describes the way in which the optimization and parameter sweeping projects
are set up. This feature allows users to automate the process of finding desirable
parameter values by running a large number of simulations. For additional information, see
the Optimization and sweeps video.
An example Optimization and Sweeps tab is shown in the screenshot below:
At the top of the window is a toolbar containing the following buttons:

Creates a parameter sweeping task.
98
Reference Guide
Creates an optimization task.

Creates a yield analysis task.
Opens an edit window for the selected project where one can modify its properties.
Deletes the selected project.
Runs the selected sweep or optimization with the resources currently set in the
resource manager.
The Animate function allows you to view the structures that will be simulated in a parameter
sweep or optimization in the CAD before you run the project:
99
6.4.1 Optimization
An example Edit Optimization window is shown in the screen shot below:
The optimization project allows users to use built-in algorithms as well as define their own
optimization algorithms. For examples on how to set up and run an optimization project,
please see Optimize a design.
As can be seen from the screenshot above, there is a SETUP tab as well as an
ADVANCED tab.
Setup Tab
There are three sections in the setup tab:
OPTIMIZATION CONFIGURATION:
This section contains the choice of algorithm as well as all the input parameters that are
needed to set up an optimization project using a built-in algorithm:
ALGORITHM: The optimization algorithm used for this project
PARTICLE SWARM: The built-in particle swarm algorithm (see Particle Swarm
Optimization 101 for more details on the algorithm).
USER DEFINED: The user-defined algorithm specified in the ADVANCED TAB.
TYPE: Choice of maximizing or minimizing the figure of merit
MAXIMUM GENERATIONS: The maximum number of generations for this optimization
project.
GENERATION SIZE: The generation size (number of child per generation) for this
100
Reference Guide
optimization project.
RESET RANDOM GENERATOR: If this option is selected, the random number seed to the
same value before starting the optimization. Otherwise a new initial condition is chosen
every time this optimization project is run.
TOLERANCE: The convergence criteria for the optimization to terminate. If set to 0, the
optimization will run until the maximum number of generations has been reached.
PARAMETERS:
This section contains the optimization parameters and the range of values used for this
project. One can ADD/REMOVE parameters via the buttons on the right. The parameters
can be chosen from the simulation model by double-clicking on the selected parameter
field. The types, min/max values and units of the selected parameters can also be set in a
similar fashion.
FIGURE OF MERIT:
This section contains the figure(s) of merit (FOM) used for this project. One can ADD/
REMOVE FOMs via the respective buttons. FOMs are typically defined as output variables
of monitors or analysis groups, which can be selected from the simulation model by
double-clicking on the selected FOM field. Once the FOMs have been defined, one can
select the FOM to be used in this project by clicking SELECT TO OPTIMIZE (note that all
other FOMs will be ignored in this optimization).
Advanced Tab
The ADVANCED tab is shown in the screen shot below:
101
This tab allows users to define their own optimization algorithm, and is only editable if the
USER DEFINED option is selected in the SETUP tab. The Advanced tab is divided into
two sub-tabs:
USER DEFINED ALGORITHM:
This tab contains the scripts which define the customized optimization algorithm (by
specifying the first and next generation scripts). The
SCRIPT OUTPUT shows the output of a test which runs the user defined algorithm with an
analytical function. If there are no syntax errors in the script, you will see the line <script
complete> in the script output, otherwise the location of the error will be given. This test is
conducted every time the TEST button is pressed, and a window showing the Optimization
Status is displayed.
FIGURE OF MERIT SCRIPT:
This tab contains the script which defines the custom FOM. To enable this window, select
the USER FIGURE OF MERIT SCRIPT checkbox. The only variables that can be used in
this script are the ones that are defined in the FOM section of the SETUP tab. For an
example that uses a user-defined optimization algorithm, see User Guide.
6.4.2 Particle Swarm Optimization

Particle Swarm Optimization (PSO) is a population based stochastic optimization
technique, inspired by the social behavior of flocks of birds or schools of fish [1,2], and has
widely been used for various kinds of design optimization problems [2] including
nanophotonic design [3-7]. In PSO, the potential solutions, called particles, are initialized
at random positions, and then move within the parameter search space. The particles are
subject to three forces as they move:
1. Spring force towards the personal best position, p, ever achieved by that individual
particle
2. Spring force towards the global best position, g, ever achieved by any particle.
3. A frictional force, proportional to the velocity.
The algorithm then follows these steps
1. Set the number of particles N and initialize the positions x
2. Evaluate figures of merit (FOM) and find p and g
3. Calculate the new velocities v for each particle based on the forces applied to the
particle
vt
vt
c1
pt
xt
c2
gt
xt
4. Update the positions x of each particle based on the velocity
xt
xt
vt
5. Repeat from step 2 until convergence is achieved
(2)
1 vt
(1)
102
Reference Guide
In Eq. (1), t is the iteration counter; c 1 and c 2 are the cognitive and social factors,
respectively; is called the inertial weight; and 1 and 2 are random number between 0
and 1. Lumerical's PSO implementation uses default values of c 1, c 2 and that have
shown to converge well in many test optimization problems for photonic design problems. A
detailed description of the algorithm and the difference coefficients can be found in Refs. [1]
or [2].
J. Robinson and Y. Rahmat-Samii, "Particle swarm optimization in Electromagnetics,"
IEEE Trans. Antennas and Propagat. 52, pp.397 - 407 (2004).
1. K. E. Parsopoulo and M N. Vrahatis, Particle swarm optimization and intelligence :
advances and applications, Information Science Reference, 2010.
2. J. Pond and M. Kawano, Virtual prototyping and optimization of novel solar cell
designs, Proc. SPIE 7750, 775028 (2010), DOI:10.1117/12.873114
3. M. Kawano and J. Pond, "Design Optimization of Photonic Crystal Organic Solar Cells
using the FDTD method in Combination with Particle Swarm Optimization," 7th
International Conference on Optics-photonics Design & Fabrication, Yokohama, Japan,
19S1-14, 2010.
4. J. G. Mutitu, S. Shi, C. Chen, T. Creazzo, A. Barnett, C. Honsberg and D. W. Prather,
"Thin film silicon solar cell design based on photonic crystal and diffractive grating
structures", Opt. Express 16, 5238, 2008
5. M.Shokooh-Saremi and R. Magnusson, "Leaky-mode resonant reflectors with extreme
bandwidths," Opt. Lett. 35, 1121, 2010.
6. R. Magnusson, M. Shokooh-Saremi,and E. G. Johnson, Guided-mode resonant wave
plates, Opt. Lett. 35, 2472, 2010.
103
6.4.3 Parameter Sweeps

An example Edit Parameter Sweep window is shown in the screen shot below:
For examples on how to set up and run a parameter sweep project, please see Run a
parameter sweep.
There are two sections in the Edit Parameter Sweep window:
PARAMETERS:
This section contains all the input parameters that are needed to set up a parameter sweep
project. There are two ways to specify the inputs to the parameter sweep. If RANGES is
selected, the table above is shown. One can ADD/REMOVE parameters via the respective
button on the right. The parameters can be chosen from the simulation model by doubleclicking on the selected parameter field, and the types, min/max values and units of the
selected parameters can be set in a similar fashion. If VALUES is selected, the following
table is shown:
104
Reference Guide
The behaviour is similar to the description for the RANGES option above, except here every
value of the parameter is shown explicitly and can be edited one-by-one. Pressing the SET
IN MODEL button automatically sets the parameters in the simulation model to have the
same value as the selected one.
NOTE: If two or more parameters are specified, they must have the same dimensions.
Each sweep step will update all parameters values one column at a time (ie. this is not the
same as nested parameter sweeps). For information on how to set up nested parameter
sweeps, please see Nested Sweeps 104 .
RESULTS:
This section contains all the outputs from the parameter sweep.
6.4.4 Nested Sweeps

It is also
possible
to use
nested
paramete
r
sweeping
. To add,
simply
right click
on the
current
optimizati
on or
sweep
and
select
"Insert

paramete
r sweep".
Example
s can be
found in
the User
Guide as
well as in
the
applicatio
n
examples
.
6.4.5 Yield Analysis

An example Edit Yield Analysis window is shown in the screenshot below:
For a tutorial on how to set up and run a yield analysis task, see Run a Yield Analysis.
There are three sections in this edit window:
CONFIGURATION:
105
106
Reference Guide
This section allows users to set the number of trials to use.
NUMBER OF TRIALS: The number of trials to run.
PROPERTIES:
This section allows the user to set the analysis parameters and the distributions. You can
ADD/REMOVE parameters via the buttons on the right. The parameters can then be
chosen from the simulation model by double-clicking on the selected Parameter field. The
Edit Distribution window can be opened by double-clicking on the selected Description
field.
Edit Distribution window:
DISTRIBUTION TYPE:
The following distributions
are available: Uniform,
Gaussian, Lognormal,
Truncated Gaussian,
Truncated Lognormal,
Discrete (uniform distribution
where variables can only
take discrete values
specified by the STEP).
MEAN: Mean value of the
distribution for Gaussian,
Lognormal, Truncated
Gaussian, and Truncated
Lognormal distributions.
STD DEVIATION: Standard
deviation of the distribution
for Gaussian, Lognormal,
Truncated Gaussian, and
Truncated Lognormal
distributions.
MIN: Minimum value or cutoff value for Uniform,
Truncated Gaussian,
Truncated Lognormal, and
Discrete distributions.
MAX: Minimum value or cutoff value for Uniform,
Truncated Gaussian,
Truncated Lognormal, and
Discrete distributions.
STEP: The discrete step
107
size of allowed values for

Discrete distribution.
SEED: The seed value used
to generate parameter
values. The seed used can
either be an automatically
generated random seed, or
the user can specify a value
for the seed so that the
same results can be
achieved each time the yield
analysis is run.
RESULTS:
This section contains the outputs of the yield analysis. Similarly to the parameters, users
can ADD/REMOVE results via the buttons on the right. The results can then be chosen
from the simulation model by double-clicking on the selected result field.
The user can specify whether they want the yield analysis estimate for the result to be
based on the user specified min and max values. If "yes" is selected in the Estimation
field, the trial will be considered a pass if the result falls into this range. If there is more
than one result with a yield estimate, the final yield percentage will be the percent of trials
where all of the results fall within the specified ranges.
108
Reference Guide
Scripting Language
Lumerical provides a powerful scripting language to manipulate simulation objects, launch
simulations and analyze results. Script commands can be entered directly into the script
prompt, be run from a saved script file (.lsf), or entered into structure and analysis objects.
This section of the Reference Guide contains the syntax for each script command.
In addition to this chapter, the Scripting section of the online User Guide provides an
introduction to the scripting language, including examples that show how to export data to
other file formats and tips for plotting in MATLAB.
The script functions have been organized into the following sections. You can also view
the alphabetical list of commands, or watch a recorded video.
Section
System 109
Manipulating variables 130
Operators 148
Functions 157
Loop and conditional statements 196
Plotting commands 197
Adding Objects 205
Manipulating objects 223
Running simulations 265
Measurement and optimization data 267
Material database functions 276
GDSII 281
User defined GUIs 288
Creating your own script commands 293
The online version of this chapter includes examples for many commands.
Scripting Language
7.1
System
System commands for interacting with the OS file system, running script files, etc.
System commands
Command
Description
newproject 112
Creates a new layout environment.
newmode 112
Creates a new MODE layout environment.
new
Creates a new simulation project file.
save 113
Saves an fsp file or lms file.
load 113
Loads an fsp file or lms file.
del 113
rm 114
Deletes a file.
ls 114
dir 114
Lists the files in a directory.
cd 115
Changes the working directory.
pwd 115
Returns the current working directory.
cp 115
Copy a file.
mv 116
Move a file.
exit 116
Exit the application.
system 116
Run command prompts.
fileexists 117
Check if a file exists.
currentfilename 117
Get the current filename.
filebasename 117
Get the file base name from a string.
filedirectory 118
Get the file directory from a string.
fileextension 118
Get the file extension from a string.
copytoclipboard 127
Copy to system clipboard.
pastefromclipboard 128
Paste from system clipboard.
hide
Hides the GUI.
show
Shows the GUI.
clearlogwindow
Clears output log window.
109
110
Reference Guide
version
Returns the current version of the application.
versionfile
Returns the current version of the file loaded by the

application.
List of script commands

Command
Description
getcommands 118
Returns a list of available script commands.
Starting and stopping scripts

Command
Description
running a script 118
Type the script name to run it.
getpath 119
Get the current path.
addpath 119
Add a directory to the path.
which 119
Where in the path is a file.
pause 120
Pauses program for a time.
break 120
Will stop a script file from executing at that line.
ESCAPE key 120
To interrupt a script file from running or a long block

of commands from executing
File input and output

Command
Description
format 121
Set the precision of the script interpreter.
STD OUT
write 123
Writes strings to text files or to standard output.
LDF files
loaddata 121
Load variables or d-card data from ldf file.
savedata 121
Save variables to ldf file.
savedcard 122
Saves d-card data to an ldf file.
Text files
readdata 122
Read text files.
Scripting Language
write 123
111
Writes strings to text files or to standard output.
fld (field) files

asapexport 123
Export monitor data to fld file.
asapload 124
Load data from fld file.
asapimport 124
Import data from fld file to Import source.
VTK files
vtksave 128
Save in .vtk format
Touchstone files
touchstoneload
Loads passive network data from a file containing

Touchstone file formatted s-parameters.
Lookup tables
lookupclose 129
Closes a file previously created with a lookupopen

command.
lookupopen 129
Opens a file to write a lookup table.
lookupread 129
Finds the nearest extracted value from a file

containing a lookup table of design and extracted
parameters.
lookupwrite 130
Writes to a lookup table a design and an extracted

parameter pair.
SPICE Netlist
importnetlist
Imports an optical SPICE netlist
Comma separated value (csv)

exportcsvresults
Exports simulation results to comma separated value

formatted files.
Debugging
Command
Description
debug 128
Opens the debug utility window.
See Also
exportfigure 204 , load 113 , save 113
MATLAB functions
112
Reference Guide
Command
Description
matlabsave 124
Save workspace data to a Matlab .mat file.
matlabsavelegacy 125
Save workspace data to a legacy Matlab .mat file

format.
matlab 125
Execute a MATLAB command
matlabget 127
Get a variable from the MATLAB workspace
matlabput 127
Send a variable to the MATLAB workspace
matlabload 125
Load from MATLAB .mat file into workspace.
7.1.1 newproject
Create a new simulation project file. This command is NOT available in INTERCONNECT,
please use new instead.
Syntax
Description
newproject;

This function does not return any data.
newproject(option);
The options are

1: use default file and material database as template
2: use current file and material database as template
3: open a file browser to select and existing file as a
template
The default option is 1.
See Also
System level 109 , new
7.1.2 newmode
Creates a new MODE layout environment.
Function has been deprecated. Use newproject instead.
Syntax
Description
newmode;

newmode(option);
The options are

1: use default lms file and material database as
Scripting Language
113
template
2: use current lms file and material database as
template
3: open a file browser to select and existing lms file as a
template
See Also
System level 109
7.1.3 save
Saves an simulation project file. If the simulation has been run, the file will also contain the
simulation results.
Syntax
Description
save;
Open a file browser to save the file.

save(filename);
Save with the specified name
See Also
System level 109 , load 113 , loaddata 121 , savedata 121 , savedcard 122
7.1.4 load
Loads an simulation project file. If the simulation has been run, the file will also contain the
simulation results.
Syntax
Description
load(filename);
Loads the simulation file.

See Also
System level 109 , loaddata 121 , save 113 , savedata 121 , savedcard 122 , fileexists 117 , dir 114
7.1.5 del
Delete a file.
Syntax
Description
114
Reference Guide
del("filename");
rm("filename");
Deletes the file "filename".

See Also
System level 109 , delete 227
7.1.6 rm
Delete a file.
Syntax
Description
del("filename");
rm("filename");
Deletes the file "filename".

See Also
System level 109 , delete 227
7.1.7 dir
List files in a directory.
Syntax
Description
out = dir;
out = ls;
The output is a string.

Use ?dir; to write the value to the screen.
out = dir("directory");
out = ls("directory");
Lists the files in the specified directory.
See Also
System level 109 , load 113 , splitstring 178
7.1.8 ls
List files in a directory.
Syntax
Description
out = dir;
out = ls;
The output is a string.

Use ?dir; to write the value to the screen.
out = dir("directory");
out = ls("directory");
Lists the files in the specified directory.
Scripting Language
See Also
System level 109 , load 113 , splitstring 178
7.1.9 cd
Change directory.
Syntax
Description
cd;
Opens a window to browse to a directory.

cd("directory");
Changes the working directory to "directory". Whenever

you open an fsp file or run a script file, it will set the
working directory to the directory of the file opened.
See Also
System level 109
7.1.10 pwd
Returns the current working directory.
Syntax
Description
out = pwd;
Returns the current working directory as a string.
See Also
System level 109 , currentfilename 117
7.1.11 cp
Copy a file.
Syntax
Description
cp("file1","file2");
Makes a copy of file1 called file2.

cp("path1\file1","path2
\file2");
Copies file1 in path1 to file2 in path2.
See Also
System level 109 , mv 116 , pwd 115 , copy (objects) 230
115
116
Reference Guide
7.1.12 mv
Move a file.
Syntax
Description
mv("file1","file2");
Moves file1 to file2.

cp("path1\file1","path2
\file2");
Moves file1 in path1 to file2 in path2.
See Also
System level 109 , cp 115 , pwd 115
7.1.13 exit
Exit the application.
Syntax
Description
exit;
Exits the application. Same as exit(1);

exit(option);
Exits the application. The option can be

1: Prompt user if a file needs saving before exiting.
2: Force the application to exit without prompting the
user.
See Also
System level 109
7.1.14 system
The system command allows you to have the operating system (OS) execute a command,
rather than the Lumerical script interpreter.
The system command does not return any data.
Syntax
Description
system("command");
Run "command" at the OS command prompt.
See Also
Scripting Language
117
System level 109 , readdata 122 , exit 116
7.1.15 fileexists
Check if a file exists. The file extension must be specified. By default, the entire path will
be searched.
Syntax
Description
out = fileexists("filename");
Returns 1 if the file exists

Returns 0 if the file does not exist.
out = fileexists("c:\temp\file.
txt");
Search for a file not in the path
See Also
System level 109 , getpath 119 , which 119 , pwd 115 , load 113 , loaddata 121 , write 123 , readdata
122 , currentfilename 117 , rm 114 ,
7.1.16 currentfilename
Get the current filename and directory.
Syntax
Description
out = currentfilename;
Returns the current filename as a string.

If the current filename is not defined, this function returns
an empty string "".
See Also
System level 109 , fileexists 117 , getpath 119 , which 119 , pwd 115 , fileextension 118 ,
filebasename 117 , filedirectory 118
7.1.17 filebasename
Get the file basename from a string.
Syntax
Description
out = filebasename
( "location/filename.ext" );
Returns the file basename as a string.
See Also
System level 109 , currentfilename 117 , getpath 119 , which 119 , pwd 115
118
Reference Guide
7.1.18 fileextension
Get the file extension from a string.
Syntax
Description
out = fileextension( "name.

ext");
Returns the file extension as a string.
See Also
7.1.19 filedirectory
Get the file directory from a string.
Syntax
Description
out = filedirectory( "location/

filename.ext" );
Returns the file directory as a string.
See Also
7.1.20 getcommands
Returns the list of available script commands in the current script workspace.
Syntax
Description
?getcommands;
Returns a list of available script commands
See Also
System level 109
7.1.21 Run script

Run a script by typing its name. The file must be in the current path. The path always
searches the current directory first. A script file is not passed variables, and does not
return variables. All scripts have access to all of the variables defined in the current
workspace.
It's best to avoid using the names of Lumerical script functions (i.e. plot) for the names of
your script files. If a script file has the same name as a function, the script will be run (not
the function). This allows you to effectively re-define the behavior of a function, but it can
Scripting Language
119
cause confusion when done unintentionally.

Syntax
Description
filename;
Run the script file filename.lsf, if it exists in the current

path.
A script does not have a return type.
See Also
System level 109 , getpath 119 , addpath 119 , which 119 , feval 176
7.1.22 getpath
Get the current path. By default, the current working directory and the script sub-directory
of the installation (eg. C:\Program Files\Lumerical\FDTD\scripts) are in the path.
Syntax
Description
out = getpath;
Returns the current path as a string.

Use ?getpath; to print it to the screen.
See Also
System level 109 , addpath 119 , which 119 , pwd 115
7.1.23 addpath
Add a directory to the path.
Syntax
Description
addpath("directory");
Adds a directory to the path.

See Also
System level 109 , getpath 119 , which 119 , pwd 115
7.1.24 which
Returns the full file pathname for the specified file.
This function can be helpful when you have added several directories to the Lumerical path
variable and you want to check which files are being accessed.
Syntax
Description
120
Reference Guide
out = which("filename");
Returns the pathname of the file "filename" as a string.

Use ?which("filename"); to display the result to the
screen.
See Also
System level 109 , getpath 119 , addpath 119 , pwd 115 , currentfilename 117 , fileexists 117
7.1.25 pause
Pause program for a time.
Hit the space bar to force the script to continue. Hit the ESCAPE key to break the script
at this point.
Syntax
Description
pause(time);
Pauses script for time, measured in seconds.

See Also
System level 109 , break 120 , ESCAPE key 120
7.1.26 break
Stops a script from executing.
Syntax
Description
break;
Will stop a script file from executing at that line. A warning

will be generated.
See Also
System level 109 , ESCAPE key 120 , pause 120
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,
Scripting Language
121
or hold it down to interrupt the script.

See Also
System level 109 , break 120 , pause 120
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 109 , num2str 175 , ? 157
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.
See Also
System level 109 , savedata 121 , savedcard 122 , workspace 136 , load 113 , fileexists 117
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.

122
Reference Guide
savedata("filename", var1,
var2,...);
Saves only variables with the specified names to file.
See Also
System level 109 , savedcard 122 , loaddata 121 , workspace 136 , matlabsave 124
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.
savedcard("filename",
"name1", "name2",...);
Saves only the d-cards with the specified names, "name1",

"name2", etc.
See Also
System level 109 , savedata 121 , loaddata 121 , matlabsave 124
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 109 , rm 114 , write 123 , str2num 176 , findstring 177 , replace 177 , replacestring 178 ,
substring 176 , fileexists 117
Scripting Language
123
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.
See Also
System level 109 , readdata 122 , rm 114 , num2str 175 , ? 157 , endl 157 , format 121 , fileexists 117
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.
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 109 , asapload 124 , asapimport 124 , addimportedsource 217
124
Reference Guide
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
Syntax
Description
asapload;
Select the file to load with the file browser.

asapload( "filename");
Loads data from an fld file called "filename" without a file

browser.
See Also
System level 109 , asapexport 123 , asapimport 124 , addimportedsource 217 , fileexists 117
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.
asapimport( "sourcename",
"filename");
Specify the file to open.
See Also
System level 109 , asapexport 123 , asapload 124 , addimportedsource 217 , fileexists 117
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
Scripting Language
125
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.
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 109 , matlabput 127 , matlabsavelegacy 125 , matlabload 125 , vtksave 128
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
124 for details.
See Also
System level 109 , matlabsave 124
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 109 , matlabput 127 , matlabsavelegacy 125 , matlabsave 124 ,
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.
126
Reference Guide
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
System level 109 , matlabget 127 , matlabput 127
Scripting Language
127
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.
See Also
System level 109 , matlab 125 , matlabput 127
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.
See Also
System level 109 , matlab 125 , matlabget 127
7.1.43 copytoclipboard
Copies the selected objects into the system clipboard. Equivalent to 'Ctrl-C'.
Syntax
Description
128
Reference Guide
copytoclipboard
Copies selected objects to the system clipboard
See Also
System level 109 , pastefromclipboard 128 , copy 230
7.1.44 pastefromclipboard
Paste the contents of the system clipboard into the layout environment. Equivalent to 'CtrlV'.
Syntax
Description
pastefromclipboard
Paste contents of system clipboard
See Also
System level 109 , copytoclipboard 127 , copy 230
7.1.45 debug
This command is available in FDTD only.
Syntax
Description
debug;
See Also
System level 109
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 109 , datasets 141 , rectilineardataset 139 , matlabsave 124 , data visualization with
ParaView (User Guide)
Scripting Language
129
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 109 , lookupclose 129 , lookupopen 129 , lookupwrite 130
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 109 , lookupclose 129 , lookupread 129 , lookupwrite 130
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 109 , lookupopen 129 , lookupread 129 , lookupwrite 130
130
Reference Guide
7.1.50 lookupwrite
Writes to a lookup table a design and an extracted parameter pair.
Syntax
Description
out = lookupwrite (filename, , Writes to a lookup table a design and an extracted

design, 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 109 , lookupclose 129 , lookupopen 129 , lookupread 129
7.2
Manipulating variables
The following commands are used to create and access variables.
Command
Description
= 132
Assignment operator.
: 132
Array operator.
[] 132
Create matrix.
% 133
Create variable with space in the name
linspace 133
Creates a linear spaced array.
matrix 133
Creates a matrix filled with zeros.
randmatrix 133
Creates a matrix with all elements randomly set

between 0 and 1
randnmatrix 134
Creates a matrix with all elements randomly

distributed with mean 0 and standard distribution 1.
histogram 134
Create a matrix containing the histogram count of a

yield analysis result.
meshgridx 134
Create a 2D meshgrid in x direction.
meshgridy 135
Create a 2D meshgrid in y direction.
meshgrid3dx 135
Create a 3D meshgrid in x direction.
Scripting Language
131
meshgrid3dy 135
Create a 3D meshgrid in y direction.
meshgrid3dz 136
Create a 3D meshgrid in z direction.
meshgrid4d 136
Create a 4D meshgrid in any direction
clear 136
Clears all stored script variables from memory.
workspace 136
Returns a string of all the currently defined scripting

variables.
Matrix elements 137
How to assign and access matrix elements.
Matrix operations 138
Describes how operators and functions act on

matrices.
Pre-defined constants 138
List of pre-defined constants.
eye 141
Creates identity matrix
struct 146
Creates unstructured dataset
cell 147
Creates cell array variable
The following commands are used to create, access and manipulate datasets. For an
introduction to datasets, see the dataset introduction 141 page.
Command
Description
rectilineardataset 139
Creates an empty rectilinear dataset associated with

the coordinates x/y/z.
matrixdataset 139
Creates an empty matrix dataset.
unstructureddataset 147
Creates an empty unstructured dataset associated

with the coordinates x/y/z and the connectivity matrix
addparameter 140
Adds a parameter to an existing dataset.
addattribute 140
Adds an attribute to an existing dataset.
getresult 270
Gets the dataset results from a monitor or analyzer.
getparameter 140
Get a parameter from an existing dataset.
getattribute 141
Get an attribute from an existing dataset.
132
Reference Guide
7.2.1 =
Assignment operators.
Syntax
Description
x = 5+2i;
Assign a value to a variable.
See Also
Manipulating variables 130 , == 151
7.2.2 :
Array operator.
Syntax
Description
x = 2 : 10;
x will be an array of numbers that start at 2 and increase

by 1 for each consecutive number. The last entry will be
<= 10. x will equal 2,3,...,9,10.
x = 6 : -1.5 : 2;
x will be the array were the first element is 6, and

consecutive elements decrease by 1.5. All elements will
be >=2. In this example, the array will be [6, 4.5, 3].
See Also
Manipulating variables 130 , linspace 133
7.2.3 []
Specify matrix element by element.
Command
Description
x = [u11,...,u1N; u21,...,u2N;
uM1,...,uMN]
Create an N by M matrix. Columns are separated

with semicolons. Elements in a row are separated
with commas. The entries can either be scalars or
matrices of compatible dimension.
See Also
Manipulating variables 130 , linspace 133 , matrix 133 , Accessing and assigning matrix
elements 137
Scripting Language
133
7.2.4 %
Used to create variables with spaced in the names.
Command
Description
%variable with space%
To create a variable name that contains spaces,

such as "variable with space", put a percentage sign
before and after the variable name.
See Also
7.2.5 linspace
Creates a linearly spaced array.
Syntax
Description
x = linspace(min,max,num);
x will be an array with num elements, linearly spaced

between min and max. If num is set to 1, then x will be the
average of min and max.
See Also
Manipulating variables 130 , : 132 , [] 132
7.2.6 matrix
Initialize a matrix. All elements are set to zero.
Syntax
Description
x = matrix(i,j,k,....);
Initializes an i x j x k x .... matrix.
See Also
Manipulating variables 130 , linspace 133 , [] 132
7.2.7 randmatrix
Initialize a matrix. All elements are random numbers between 0 and 1.
Syntax
Description
x = randmatrix(i,j,k,....);
Initializes an i x j x k x .... matrix. The elements are all
134
Reference Guide
random numbers between 0 and 1.
See Also
Manipulating variables 130 , matrix 133 , rand 190 , randreset 191
7.2.8 randnmatrix
Initialize a matrix. All elements are normally distributed random numbers with mean 0 and
standard distribution 1.
Syntax
Description
x = randnmatrix(i,j,k,....);
Initializes an i x j x k x .... matrix. The elements are all

random normally distributed numbers with mean 0 and
standard deviation 1.
See Also
Manipulating variables 130 , matrix 133 , randn 190 , randreset 191
7.2.9 histogram
Create a matrix containing the histogram count of a yield analysis result.
Syntax
Description
out = histogram(y);
Returns a matrix containing the histogram count of y.
out = histogram(y,n);
Returns a matrix containing the histogram count of y,

using n bins.
out = histogram(y,n,
barplot);
Returns a matrix containing the histogram count of y,

using n bins. If barplot is true (1), the histogram count is
formatted for a bar plot.
See Also
Manipulating variables 130 , histc 202
7.2.10 meshgridx
Create a 2D meshgrid in the x direction
Syntax
Description
out = meshgridx(x,y);
If x and y are single column (or single row vectors), of

dimension nX1 and mX1 respectively, the command
X = meshgridx(x,y);
Scripting Language
135
Will create a 2D matrix of dimension nXm where X(i,j)=x(i).

See Also
Manipulating variables 130 , image 202 , meshgridy 135 , meshgrid3dx 135
7.2.11 meshgridy
Create a 2D meshgrid in the y direction
Syntax
Description
out = meshgridy(x,y);
If x and y are single column (or single row vectors), of

dimension nX1 and mX1 respectively, the command
Y = meshgridy(x,y);
Will create a 2D matrix of dimension nXm where Y(i,j)=y
(j).
See Also
Manipulating variables 130 , image 202 , meshgridx 134 , meshgrid3dx 135
7.2.12 meshgrid3dx
Create a 3D meshgrid in the x direction
Syntax
Description
out = meshgrid3dx(x,y,z);
The 3D version of meshgridx and meshgridy.
See Also
Manipulating variables 130 , meshgridx 134 , meshgridy 135 , meshgrid3dy 135 , meshgrid3dz 136
7.2.13 meshgrid3dy
Create a 3D meshgrid in the y direction
Syntax
Description
out = meshgrid3dy(x,y,z);
See Also
Manipulating variables 130 , meshgridx 134 , meshgridy 135 , meshgrid3dx 135 , meshgrid3dz 136
136
Reference Guide
7.2.14 meshgrid3dz
Create a 3D meshgrid in the z direction
Syntax
Description
out = meshgrid3dz(x,y,z);
See Also
Manipulating variables 130 , meshgridx 134 , meshgridy 135 , meshgrid3dx 135 , meshgrid3dy 135
7.2.15 meshgrid4d
Create a 4D meshgrid in any direction.
Syntax
Description
out = meshgrid4d(dim, x1,

x2, x3, x4);
The 4D meshgrid function.

dim specifies the dimension along which to create the grid
x1,x2,x3,x4 are the position vectors in each direction
See Also
Manipulating variables 130 , meshgridx 134 , meshgridy 135 , meshgrid3dy 135 , meshgrid3dz 136
7.2.16 clear
Clears all stored workspace variables. This will not clear any simulation data stored in dcards. The variables c, pi, eps0, mu0 will be reset to their default values.
Syntax
Description
clear;
Clears all workspace variables.

See Also
Manipulating variables 130 , cleardcard 274
7.2.17 workspace
Returns a list of all the currently defined variables in the scripting workspace.
Syntax
Description
out = workspace;
Returns a string that lists all currently defined variables in

the workspace.
Scripting Language
137
Use ?workspace; to print this to the screen.

See Also
7.2.18 Accessing and assigning matrix elements

Accessing and assigning matrix elements.
Command
Description
x = [u; v; w]
Create a column vector. u,v,w can either be scalars

or matrices of compatible dimension.
x = [u, v, w]
Create a row vector. u,v,w can either be scalars or

matrices of compatible dimension.
x(7) = 5;
Set the 7th element of x to 5.
x(7) = y(2);
Set the 7th element of x to the 2nd element of y.
x(3,1,8) = 3;
Set an element of a multidimensional matrix to 3.
x(2:5,1) = 1:4;
Set a sub-matrix of x to values 1:4. In the

assignment A(I,...) = B, if B is not a scalar, the submatrix A(I,...) must be the same same size as B. If B
is a scalar, then all the values of the sub-matrix are
set to B.
x(2:5,1) = 1;
Set all the values in a sub-matrix of x to 1.
x = y(1:10,2,1:20);
x is equal to a sub-matrix of y.
x = matrix(2,3);
x(4)=7;
Multi-dimension matrices can be accessed with a

single index.
x=y(z);
Indices stored in matrix (z) used to select elements

of matrix y. length(x) will equal length(z).
See Also
138
Reference Guide
7.2.19 Matrix operators

Almost all the scripting functions will act element by element on matrices. Single numbers
are treated as matrices of dimension 1x1. The following table provides some examples.
Dimension of
x
Dimension of
y
Operation
Dimension of
z
Value of z
1x1
N/A
z = sin(x)
1x1
z 11 = sin(x 11)
1x1
1x1
z=x*y
1x1
z 11 = x 11 * y 11
10x10
1x1
z=x*y
10x10
Zij = x ij * y 11
10x10
10x10
z=x*y
10x10
Zij = x ij * y ij
10x10
11x11
z=x*y
Error
Error
See Also
7.2.20 Pre-defined constants

Name
Description
pi
The number .
The speed of light in a vacuum in m/s.
eps0
The permittivity of free space in SI units.
mu0
The permeability of free space in SI units.
The Planck constant.
hbar
The reduced Planck constant.
true
Logical TRUE (1).
false
Logical FALSE (0);
The electron volt.
See Also
Scripting Language
139
7.2.21 matrixdataset
Creates an empty matrix dataset. Matrix datasets are used for data (attributes and
parameters) that don't have any spatial dependence (i.e. Reflection vs frequency). For
datasets that do have x/y/z spatial coordinates (i.e. electric fields), use rectilineardataset
139 .
Matrix datasets can be parameterized, and can contain an arbitrary number of attributes
(see addattribute) 140 and parameters (see addparameter) 140 .
See Dataset introduction 141 for more information.
Syntax
Description
matrixdataset;
Creates an empty dataset.
matrixdataset("name");
Creates an empty dataset with the name "name".
See Also
rectilineardataset 139 , addattribute 140 , addparameter 140 , visualize 203 , datasets 141 ,
getparameter 140 , getattribute 141 , matrixdataset 139 , struct 146
7.2.22 rectilineardataset
Creates an empty rectilinear dataset that is associate with the x/y/z coordinates (ex. E and
H fields). Like matrix datasets, rectilinear datasets can be parameterized, and can contain
an arbitrary number of attributes (see addattribute) 140 and parameters (see addparameter)
140 .
For datasets that are not associated with the x/y/z coordinates (ex. transmission as a
function of frequency), see matrixdataset 139 .
Syntax
Description
rectilineardataset(x,y,z);
Creates a empty rectilinear dataset associated with the

coordinates x/y/z.
rectilineardataset("
dataset_name",x,y,z);
Creates a empty rectilinear dataset named

"dataset_name" associated with the coordinates x/y/z.
See Also
140
Reference Guide
7.2.23 addparameter
Adds a parameter to an existing dataset.
Syntax
Description
R.addparameter("p_name",
p);
Adds the parameter p to the existing dataset R.
R.addparameter("p1_name",
p1, "p2_name", p2);
Adds the interdependent parameter p1_name, p2_name to

the R dataset.
The most common interdependent parameter is frequency
and wavelength. Parameters that are not interdependent
must be added separately.
See Also
getparameter 140 , getattribute 141 , matrixdataset 139
7.2.24 addattribute
Adds an attribute to an existing dataset.
Syntax
Description
R.addattribute("a_name", a); Adds the scalar attribute a to the dataset R.

R.addattribute("a_vector",
a_1, a_2, a_3);
Adds the vector attribute a_vector to the existing dataset

R. The components of the vector are a_1, a_2 and a_3
See Also
getparameter 140 , getattribute 141 , matrixdataset 139
7.2.25 getparameter
Get a parameter from an existing dataset.
Syntax
Description
?getparameter(R);
Returns the names of all the parameters in the dataset R.
Parameter = R.getparameter Retrieves the parameter p from the existing dataset R. The
("p");
result "Parameter" is a scalar matrix.
Scripting Language
Parameter = getparameter
(R,"p");
141
Retrieves the parameter p from the existing dataset R. The

result "Parameter" is a scalar matrix.
See Also
matrixdataset 139 , rectilineardataset 139 , "." operator 168 , getresult 270 , getattribute 141 ,
visualize 203 , datasets 141
7.2.26 getattribute
Get an attribute from an existing dataset.
Syntax
Description
?getattribute(R);
Returns the names of all the attributes in the dataset R.
Attribute = R.getattribute
("a");
Retrieves the attribute a from the existing dataset R. The

result "Attribute" is a scalar matrix.
Attribute = getparameter
(R,"a");
Retrieves the attribute a from the existing dataset R. The

result "Attribute" is a scalar matrix.
See Also
Dataset introduction 141 , matrixdataset 139 , rectilineardataset 139 , "." operator 168 , getresult
270 , getparameter 140 , visualize 203 , datasets 141
7.2.27 eye
The script command eye creates a 2D identity matrix.
Syntax
Description
I = eye;
Returns a 1x1 matrix, value 1.0.
I = eye(n);
Returns nxn identity matrix.
I = eye(n,m);
Returns nxm matrix with ones on main diagonal
See Also
Datasets 141 , matrixdataset 139 , rectilineardataset 139 , matlab 125 , matrix 133
7.2.28 Datasets
Introduction to Lumerical datasets
Lumerical datasets are structured data objects that collect a set of related matrices into a
single convenient object. To introduce this concept, we'll start by providing two examples.
Additional information follows.
142
Reference Guide
Page contents
Example 1) Reflection vs radius and height 142
Example 2) Electric field data from a monitor 143
Attributes and parameters 144
What is in a dataset? Icons and the '?' operator 145
Accessing data in a dataset: the dot '.' operator 145
Dataset types: matrixdataset and rectilineardataset 145
Operations on datasets 146
Scalar and vector attributes 146
Example 1) Reflection vs radius and height (matrix dataset)

Suppose you have a parameter sweep that
measures the reflection from a particle as a
function of particle radius and height.
Saving this information generally requires 3
matrix variables. The 2D matrix R contains
the reflection value from each simulation,
while the 1D vectors radius and height
contain the associated position values.
A dataset object can be used to collect all
three matrices into a single dataset
variable.
The following script code generates some example data, creates a R(radius,height)
dataset, and finally creates several plots of the data.
# create example results
radius = 0:10;
height = 1:0.1:3;
reflection = randmatrix(length(radius),length(height));
# create Reflection dataset
R = matrixdataset("R"); # initialize dataset
R.addparameter("radius",radius); # add radius parameter
R.addparameter("height",height); # add height parameter
R.addattribute("R",reflection); # add reflection attribute
Scripting Language
143
# plot data
image(radius,height,reflection); # use original matrices
image(R.radius,R.height,R.R);
# use dataset
# send dataset to visualizer
visualize(R);
Example 2) Electric field data from a monitor (rectilinear dataset)

Field monitors in FDTD and MODE
Solutions are used to calculate and save
spatial electric field data. The raw electric
field data within the monitor is distributed
between several matrices: Each vector field
component is stored in a matrix (Ex, Ey,
Ez), and the four associated position
vectors (x,y,z,f) are also stored as separate
matrices.
A dataset can be used used to collect all of
this information into a single dataset
variable. The figure to the right shows the
three matrices Ex, Ey, Ez that store each
component of the electric field. It also
shows the associated position vectors x, y,
z. All of this information can be stored
within a single dataset variable.
Note: The electric field matrices usually
have a 4th dimension (time or frequency),
but this dimension is not included in the
figure due to the difficulty of graphically
representing a 4th dimension!
The following script code shows how to get the raw data from a frequency monitor in
FDTD Solutions (using getdata), and how to manually create a dataset from that data. It
also shows how to directly get the electric field dataset from the monitor in a single
command (using getresult). The final section shows how to create a few plots of the data
# monitor name
m="monitor";
# get individual data elements with getdata
144
Reference Guide
x=getdata(m,"x");
y=getdata(m,"y");
z=getdata(m,"z");
f=getdata(m,"f");
Ex=getdata(m,"Ex");
Ey=getdata(m,"Ey");
Ez=getdata(m,"Ez");
# manually create the electric field dataset from the raw data
# initialize dataset and provide spatial position vectors
E_manual = rectilineardataset("E_manual",x,y,z);
# add additional parameter: frequency
E_manual.addparameter("lambda",c/f,"f",f);
# add vector electric field attribute
E_manual.addattribute("E",Ex,Ey,Ez);
# all of the above commands can be avoided with a single
getresult command
E_fromMonitor = getresult(m,"E");
# plot Ex(x,y) at the first z value and first frequency point

to_plot = pinch(pinch(Ex,4,1),3,1);
# use original matrices
image(x,y,to_plot);
# use original matrices
to_plot = pinch(pinch(E_manual.Ex,4,1),3,1);
image(E_manual.x,E_manual.y,to_plot);
# use dataset
# use dataset
# Plot the entire dataset with the Visualizer

visualize(E_manual);
Attributes and parameters

Attribute: The actual data of a dataset. In the examples above, the reflection R and electric
field Ex, Ey, Ez were the Attributes of the dataset.
Parameter: The associated position vectors of a dataset. In the above examples, radius,
height, x, y, z, and f were the parameters.
When creating datasets, the size of the attribute matrices must be consistent with the
lengths of the associated parameters matrices.
Scripting Language
145
What is in a dataset? Icons and the '?' operator

The Results view and Script workspace windows provide a list of current monitor results
and script variables. Different icons are used for each type of variable (dataset, matrix,
string, unstructured data). For datasets, the preview column provides a list of the
attributes and parameters in the dataset. In the screenshot below, the 'E' dataset contains
one attribute (E) that is a function of 4 parameters (x,y,z, lambda/f).
The '?' operator can be used to output the same information to the script prompt.
?E_field = getresult("monitor","E");
> E vs x, y, z, lambda/f
To output the actual attribute or parameter values, do something like:
?E_field.x;
# output the 'x' position vector
> result:
> -6.58393e-006
> -6.5442e-006
> -6.50447e-006
> .....
Accessing data in a dataset: the dot '.' operator

Individual matrices stored in the dataset can be accessed with the dot '.' operator. For
example, to get the raw x, y, and Ex data from an Electric field dataset, do something like:
x = E_field.x;
y = E_field.y;
Ex = E_field.Ex;
Dataset types: matrixdataset and rectilineardataset

146
Reference Guide
Data without spatial parameters (such as example 1) will use matrix datasets.
Data with spatial information from a rectilinear grid (such as the FDTD mesh) will use
rectilinear datasets.
Operations on datasets
Datasets are primarily intended to be a convenient way to manage and store a collection of
related data. It is not possible to apply mathematical operations, such as addition, directly
to dataset objects. Instead, the dot operator must be used to get the desired data into a
matrix. The operation can then be applied to the matrix. You may choose to create a new
dataset to store the result, or you may simply keep the result as a standard matrix.
Scalar and vector attributes

It is possible to add both scalar and vector attributes to datasets.
Scalar
The command
R.addattribute("R",reflection); # add reflection attribute
adds a scalar quantity 'R' to a dataset with the same name. To access the 'R' raw data,
use:
R.R;
Vector
The command
E.addattribute("E",Ex_raw,Ey_raw,Ez_raw); # add vector E field
attribute
adds a vector quantity 'E' to a dataset with the same name. In this case, we can access
the raw 'E' data in the following ways:
E.Ex; # get Ex component
E.Ey; # get Ey component
E.Ez; # get Ez component
E.E2; # get |E|^2
E.E;
# get all components in a single matrix. An extra
dimension of length 3 will be added to the matrix, for each
vector component.
See Also
7.2.29 struct
The script command struct adds an unstructured dataset. Any data type (such as matrix,
string, dataset) can be added to struct objects.
Scripting Language
Syntax
Description
a = struct;
Creates an unstructured dataset.
a.a = "string";
Adds a string field to the structure.
a.b = matrix(5,5);
Adds a field of matrix of 5x5 to the structure.
147
See Also
Datasets 141 , matrixdataset 139 , rectilineardataset 139 , cell 147
7.2.30 cell
The script command cell creates a cell array variable with specified number of elements.
The cell array element can be any data type, such as matrix, string, and dataset.
Syntax
Description
a = cell(n);
Creates a cell array with n elements.
a{n} = "string";
Adds a string to the specified element of the cell array.
a{n} = matrix(5,5);
Adds a field of matrix of 5x5 to the specified element of the

cell array.
See Also
Datasets 141 , matrixdataset 139 , rectilineardataset 139 , struct 146 , splitstring 178
7.2.31 unstructureddataset
Unstructureddataset script command creates an empty dataset that is associated with
arbitrary x/y/z coordinate in space, and with additional matrix, a connectivity matrix to
connect them. The connectivity matrix comes after x, y, and z. Like rectilinear datasets,
unstructured datasets can be parameterized, and can contain an arbitrary number of
attributes (see addattribute) 140 and parameters (see addparameter) 140 .
For datasets that are not associated with the x/y/z coordinates (ex. transmission as a
function of frequency), see matrixdataset 139 .
Syntax
Description
unstructureddataset(x,y,z,
C);
Creates a empty rectilinear dataset associated with the

coordinates x/y/z and a connectivity matrix to connect
148
Reference Guide
them.
See Also
7.3
Operators
Standard mathematical and string operators.
Algebraic operators
Command
Description
* 150
Multiplication. Ex: y = x * z;
/ 150
Division. Ex: y = x / z;
+ 150
Addition. Ex: y = x + z;
- 150
Subtraction. Ex: y = x z;
- 150
Negative. Ex: y = -x;
^ 151
Power. Ex: y = x^3;

In expression A^B, if B is complex, the phase of A is
evaluated from - to .
Logical and relational operators

Command
Description
== 151
Comparison.
almostequal 151
Almost equal comparison operator.
!= 152
Not equal.
<= 152
Less than or equal to.
>= 152
Greater than or equal to.
< 153
Less than.
> 153
Greater than.
& 153
AND.
and 153
AND.
| 154
OR.
Scripting Language
or 154
OR.
! 154
NOT.
~ 155
NOT.
Dataset operators
Command
Description
. 149
Retrieve the parameters and attributes of datasets.
String operators
Command
Description
" 155
Create a string variable.
' 156
Create a string variable.
+ 150
Add strings
endl 157
end of line character.
Output to screen
Command
Description
? 157
Display output on screen.
# script file comments 157
Comment script files with #
7.3.1 .
The dot operator can be used to retrieve the parameters and attributes of datasets.
Syntax
Description
result = A.result;
Retrieves the parameter or attribute "result" from the

existing dataset A. The result is a scalar matrix.
See Also
matrixdataset 139 , rectilineardataset 139 , getparameter 140 , getattribute 141 , visualize 203
149
150
Reference Guide
7.3.2 *
Multiplication. When applied to matrices, this operator does simple element by element
multiplication, not matrix multiplication.
Syntax
Description
y = x * z;
Multiply x and z.
See Also
Operators 148 , * 150 , / 150 , + 150 , - 150 , ^ 151 , mult 169
7.3.3 /
Division.
Syntax
Description
y = x / z;
Divide x by z.
See Also
Operators 148 , * 150 , / 150 , + 150 , - 150 , ^ 151
7.3.4 +
Addition.
Syntax
Description
y = x + z;
Add x and z.
y = string1 + string2;
Concatenate strings together.
See Also
Operators 148 , * 150 , / 150 , + 150 , - 150 , ^ 151
7.3.5 Subtraction, or negative.

Syntax
Description
y = x - z;
Subtract z from x.
y = -x;
Negative
Scripting Language
151
See Also
Operators 148 , * 150 , / 150 , + 150 , - 150 , ^ 151
7.3.6 ^
Power. In expression A^B, if B is complex, the phase of A is evaluated from - to .
Syntax
Description
y = x^3;
x cubed.
See Also
Operators 148 , * 150 , / 150 , + 150 , - 150 , ^ 151
7.3.7 ==
Logical comparison. This operators can be used with complex numbers and strings.
Syntax
Description
out = y == x;
Returns 1 if x and y are equal. Returns 0 otherwise.
See Also
Operators 148 , = 132 , almostequal 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154
, or 154 , ! 154 , ~ 155
7.3.8 almostequal
Almost equal comparison operator. When using floating point numbers (rather than
integers), two values that are meant to be equal may not be exactly equal due to rounding
errors that are always present in floating point calculations. In such cases, the almost
equal function can be useful.
Syntax
Description
out = almostequal(A, B);
Returns 1 if A - B is less than or equal to A + B /2*1e15. Returns 0 otherwise.
out = almostequal(A, B,
relative diff);
Returns 1 if A - B is less than or equal to A + B /2

times relative diff. Returns 0 otherwise.
out = almostequal(A, B,
relative diff, absolute diff);
Returns 1 if A - B is less than or equal to A + B /2

times relative diff or if A - B is less than or equal to
absolute diff. Returns 0 otherwise.
152
Reference Guide
See Also
Operators 148 , = 132 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , !
154 , ~ 155
7.3.9 !=
Not equal to comparison operator. Returns 1 if values are not equal. Returns 0 if values
are equal. This operator can be used in matrix operations. This operators can be used
with complex numbers.
Syntax
Description
out = a!=b;
If a is not equal to b, then out equals 1. Otherwise out

equals 0.
See Also
Operators 148 , == 151 , almostequal 151 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or
154 , ! 154 , ~ 155
7.3.10 <=
Logical less than or equal to. Imaginary components of x and y are ignored.
Syntax
Description
out = y <= x;
Less than or equal to.
See Also
Operators 148 , == 151 , != 152 , almostequal 151 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or
154 , ! 154 , ~ 155
7.3.11 >=
Logical greater than or equal to. Imaginary components of x and y are ignored.
Syntax
Description
out = y >= x;
Greater than or equal to.
See Also
Operators 148 , == 151 , != 152 , <= 152 , almostequal 151 , < 153 , > 153 , & 153 , and 153 , | 154 , or
154 , ! 154 , ~ 155
Scripting Language
153
7.3.12 <
Logical less than. Imaginary components of x and y are ignored.
Syntax
Description
out = y < x;
Less than.
See Also
Operators 148 , == 151 , != 152 , <= 152 , >= 152 , almostequal 151 , > 153 , & 153 , and 153 , | 154 , or
154 , ! 154 , ~ 155
7.3.13 >
Logical greater than. Imaginary components of x and y are ignored.
Syntax
Description
out = y > x;
Greater than.
See Also
Operators 148 , == 151 , != 152 , <= 152 , >= 152 , < 153 , almostequal 151 , & 153 , and 153 , | 154 , or
154 , ! 154 , ~ 155
7.3.14 &
Logical AND. Imaginary components of x and y are ignored.
Syntax
Description
out = y & x;
If the real part of either or both of x,y are zero, then return
0. Otherwise return 1.
y and x;
Same as &.
See Also
Operators 148 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , ! 154 , ~
155
7.3.15 and
Logical AND. Imaginary components of x and y are ignored.
Syntax
Description
154
Reference Guide
out = y & x;
If the real part of either or both of x,y are zero, then return
0. Otherwise return 1.
y and x;
Same as &.
See Also
Operators 148 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , ! 154 , ~
155
7.3.16 |
Logical OR. Imaginary components of x and y are ignored.
Syntax
Description
out = y | x;
If the real part of either or both of x,y is non-zero, then

return 1. Otherwise return 0.
y or x;
Same as |.
See Also
Operators 148 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , ! 154 , ~
155
7.3.17 or
Logical OR. Imaginary components of x and y are ignored.
Syntax
Description
out = y | x;
If the real part of either or both of x,y is non-zero, then

return 1. Otherwise return 0.
y or x;
Same as |.
See Also
Operators 148 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , ! 154 , ~
155
7.3.18 !
Logical NOT operator. If a value is 0, then NOT returns 1. For all other values, NOT returns
0. NOT(A) is equivalent to A==0, where == is the comparison operator.
Syntax
Description
Scripting Language
out = !a;
applies logical not operator to a
out = ~a;
155
See Also
Operators 148 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , ! 154 , ~
155
7.3.19 ~
Logical NOT operator. If a value is 0, then NOT returns 1. For all other values, NOT returns
0. NOT(A) is equivalent to A==0, where == is the comparison operator.
Syntax
Description
out = !a;
out = ~a;
See Also
Operators 148 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , ! 154 , ~
155
7.3.20 "
String operator. Strings can be created with single or double quotes.
The following escape sequences are recognized when creating strings with double quotes:
\"
double quotes in string
\n
newline (linefeed) character in string
\\
backslash in string
Syntax
Description
out="my string";
use double quotes to create strings
NOTE: Literal back slashes and double quotes

It is always possible to create a literal backslash in a string with \\. However, \ also
results in a literal backslash, IF it it will not be interpreted as part of an escape sequence
(\n, \", \\). This note is important when storing paths in strings.
Suppose we want to create the string C:\Program Files\Lumerical. The following
three commands are valid and equivalent:
mystring = 'C:\Program Files\Lumerical';
# use single quotes
156
Reference Guide
mystring = "C:\Program Files\Lumerical";
mystring = "C:\\Program Files\\Lumerical";
and \\ escape character
# use double quotes

# use double quotes
However, suppose we want to create the string C:\Program Files\Lumerical\.

The only difference is the additional backslash at the end of the string. The following two
commands are valid and equivalent:
mystring = 'C:\Program Files\Lumerical\';
# use single
quotes
mystring = "C:\\Program Files\\Lumerical\\"; # use double
quotes and \\ escape character
The other potential command, where we use a single backslash, is not valid syntax and
will result in an error.
mystring = "C:\Program Files\Lumerical\";
# use double
quotes
The problem is that the script interpreter will interpret the final \" as an escape character
for a literal double quote, rather than as a single backslash and a closing double quote.
When interpreted this way, the command results in a syntax error because there is no
double quote character closing the string.
See Also
Operators 148 , ' 156 , num2str 175 , + 150 , endl 157 , write 123 , eval 176
7.3.21 '
String operator. Strings can be created with single or double quotes.
The following escape sequences are recognized when creating strings with single quotes:
''
single quote in string (two single quote characters)
Syntax
Description
out='my string';
use single quotes to create strings
See Also
Operators 148 , " 155 , num2str 175 , + 150 , endl 157 , write 123 , eval 176
Scripting Language
157
7.3.22 endl
Add an end of line character to a string
Syntax
Description
out = "line1"+endl+"line2";
Add an end of line character to the string.
See Also
Operators 148 , num2str 175 , + 150 , " 155 , write 123
7.3.23 ?
Print output to the screen. Use the format script command to change the precision of the
output.
Syntax
Description
?command;
Displays the output of the command on the screen

See Also
System level 109 , write 123 , format 121 , # 157
7.3.24 comments
Use the # character to comment script files. Anything after the # character is ignored. The
comments are not displayed when the script file is run. Comments can not be used when
typing commands directly into the script prompt.
Syntax
Description
x=1; # set x to 1
Anything after the # character is ignored.
See Also
System level 109
7.4
Functions
Standard mathematical and matrix functions.
Trigonometric and complex
Command
Description
sin 162
Trigonometric sin function.
158
Reference Guide
cos 162
Trigonometric cos function.
tan 162
Trigonometric tan function.
asin 162
Inverse trigonometric sin function.
acos 163
Inverse trigonometric cos function.
atan 163
Inverse trigonometric tan function.
atan2 163
Same as atan, but returns angle in correct quadrant.
real 164
Returns the real part of variable
imag 164
Returns the imaginary part of variable
conj 164
Complex conjugate
abs 164
Absolute value
angle 165
Phase of a complex number.
unwrap 165
Removes phase difference of more than 2
Logarithmic, exponential and power

Command
Description
log 165
The natural logarithm. Input can be complex or

negative.
log10 165
The log, base 10. Input can be complex or negative.
sqrt 166
The square root.
exp 166
The exponential.
Matrix functions
Command
Description
size 166
Returns the dimensions of a matrix.
length 166
Returns the total number of elements in a matrix.
pinch 167
Remove singleton dimensions from a matrix.
sum 167
The sum of a matrix.
max 168
The max value in a matrix.
min 168
The min value in a matrix.
Scripting Language
159
dot 168
The dot product of two vectors.
cross 168
The cross product of two vectors.
flip 170
Flip a matrix in one dimension.
interp 171
Linear interpolation function.
spline 172
Cubic spline interpolation.
integrate 173
Integrate a matrix.
integrate2 173
Integrate a matrix, ignore singleton dimensions.
find 174
Find values that satisfy a condition in a matrix.
findpeaks 174
Find peaks in a matrix.
transpose 175
Transpose a matrix.
ctranspose 175
Transpose a matrix, and do complex conjugate.
mult 169
Perform matrix multiplication of two or more

matrices.
reshape 170
Reshape the matrix to have different dimensions

conserving the overall product of the dimensions.
eig 169
Calculate the eigenvalues and/or eigenvectors of a

matrix.
permute 170
Rearrange the dimensions of a matrix.
inv 171
Calculate the inverse of a matrix.
mean 192
Return the mean value of a matrix
var 193
Returns the variance
std 194
Returns the standard deviance
mapfind 194
Returns a string value associated to specified point,

given a file containing a map of values to a string
See also
String functions
Command
Description
num2str 175
Convert number to a string.
160
Reference Guide
str2num 176
Convert a string into a floating point number.
eval 176
Execute string containing Lumerical scripting

language.
feval 176
Run a Lumerical script file.
length 166
Returns the total length of the string.
substring 176
Returns a substring of a string, as a specified

position and length.
findstring 177
Returns the position of a substring in a string.
replace 177
Replaces a part of a string with another, at a

specified position.
replacestring 178
Replaces all instances of a substring with another

string.
splitstring 178
Split a single long string into a cell (string) array

based on a delimiting character.
Frequency and time-domain

Command
Description
fft 178
Fast Fourier transform.
fftw 180
Returns the angular frequency vector.
fftk 181
Returns the spatial wavevector kx.
invfft 182
Inverse fft.
czt 183
Chirped z-transform.
Line and polygon functions

Command
Description
polyarea 183
Returns the area of a polygon.
centroid 184
Returns the center of mass of a polygon.
polyintersect 184
Determines if two polygons intersect.
inpoly 185
Determines if a series of points are inside our outside

a polygon.
polygrow 185
Grows or shrinks a polygon by a specified amount.
polyand 186
Combines two polygons into one with an and
Scripting Language
161
operation.
polyor 186
Combines two polygons into one with an or

operation.
polyxor 187
Combines two polygons into one with a xor

operation.
lineintersect 187
Returns the intersection of line segments.
linecross 188
Determines if line segments cross each other.
Miscellaneous
Command
Description
ceil 188
Round up.
floor 188
Round down.
mod 189
Modulus after division.
round 189
Rounds to the nearest integer.
rand 190
Returns a uniformly distributed random number

between 0 and 1.
lognrnd 190
Returns a lognormal distributed random number.
randn 190
Returns a normally distributed random number.
randreset 191
Resets the random number seed.
finite 191
Determines if a number is finite or NaN.
solar 191
Returns the solar power spectrum
stackrt 192
Calculates reflection and transmission of multi-layer

stacks
all 192
Returns 1 if all of the specified matrix entries are

nonzero and returns 0 otherwise.
any 193
Returns 1 if any of the specified matrix entries are

nonzero and returns 0 otherwise.
quadtri 195
Returns approximated integration (first order

quadrature) of data on a 2D finite element mesh.
precision
Returns truncated value to a user specified precision.
162
Reference Guide
7.4.1 sin
Trigonometric sine function. Angle units are in radians. Function is defined for complex
angles. Phase of a complex number is evaluated between - and .
Syntax
Description
out = sin(x);
Returns the complex sine of x.
See Also
Functions 157 , asin 162
7.4.2 cos
Trigonometric cosine function. Angle units are in radians. Function is defined for complex
Syntax
Description
out = cos(x);
Returns the complex cosine of x.
See Also
Functions 157 , acos 163
7.4.3 tan
Trigonometric tangent function. Angle units are in radians. Function is defined for complex
Syntax
Description
out = tan(x);
Returns the complex tangent of x.
See Also
Functions 157 , atan 163 , atan2 163
7.4.4 asin
Inverse trigonometric sine function. Angle units are in radians. Function is defined for
complex values. Phase of a complex number is evaluated between - and . If x is
complex, or abs(x) > 1, the following equation is used:
asin(x) = -i ln( ix + sqrt(1-x^2))
Syntax
Description
Scripting Language
out = asin(x);
163
Returns the complex arcsine of x.
See Also
Functions 157 , sin 162
7.4.5 acos
Inverse trigonometric cosine function. Angle units are in radians. Function is defined for
acos(x) = -i ln( x + i sqrt( 1-x^2))
Syntax
Description
out = acos(x);
Returns the complex arccosine of x.
See Also
Functions 157 , cos 162
7.4.6 atan
Inverse trigonometric tangent function. Angle units are in radians. Function is defined for
atan(x) = 0.5 i ln( (i+x)/(i-x) )
Syntax
Description
out = atan(x);
Returns the complex arctangent of x.
See Also
Functions 157 , atan2 163 , tan 162
7.4.7 atan2
Inverse trigonometric tangent function, calculates the arctangent of y/x, but returns the
angle in the correct quadrant. Angle units are in radians. Function is defined for real
values only.
Syntax
Description
out = atan2(y,x);
x,y must be real.
See Also
164
Reference Guide
Functions 157 , atan 163 , tan 162
7.4.8 real
Returns the real part of a number or matrix.
Syntax
Description
out = real(x);
Returns the real part of x.
See Also
Functions 157 , imag 164
7.4.9 imag
Returns the imaginary part of a number or matrix.
Syntax
Description
out = imag(x);
Returns the imaginary part of x.
See Also
Functions 157 , real 164 , conj 164
7.4.10 conj
Returns the complex conjugate of a number or matrix.
Syntax
Description
out = conj(x);
Returns the complex conjugate of x.
See Also
Functions 157 , real 164 , imag 164
7.4.11 abs
Returns the absolute value of a number or matrix.
Syntax
Description
out = abs(x);
Returns the absolute value of x.
See Also
Functions 157 , real 164 , imag 164
Scripting Language
165
7.4.12 angle
Returns the angle or phase of a complex number or matrix in radians.
Syntax
Description
out = angle(x);
Returns the phase of x.
See Also
Functions 157 , real 164 , imag 164 , unwrap 165
7.4.13 unwrap
Removes changes of more than 2 from a 1D array. It can be useful after angle(x) to see
phase without discontinuities.
The unwrap function is primarily intended for 1D arrays. Care must be taken when applying
it to matrices with more than one dimension.
Syntax
Description
out = unwrap(x);
Return the values of x without discontinuities.
See Also
Functions 157 , real 164 , imag 164 , angle 165
7.4.14 log
The natural logarithm. Input can be complex or negative.
Syntax
Description
out = log(x);
The natural logarithm. Input can be complex or negative.
See Also
Functions 157 , log10 165
7.4.15 log10
Syntax
Description
out = log10(x);
See Also
Functions 157 , log 165
166
Reference Guide
7.4.16 sqrt
The square root.
Syntax
Description
out = sqrt(x);
The square root.
See Also
Functions 157 , ^ 151
7.4.17 exp
The exponential.
Syntax
Description
out = exp(x);
The exponential.
See Also
Functions 157 , log 165 , ^ 151
7.4.18 size
Returns the size of a matrix.
Syntax
Description
y = size(x);
y is a matrix which shows the dimensions of x.
See Also
Functions 157 , length 166 , flip 170 , transpose 175
7.4.19 length
Returns the number of elements in a matrix. If the argument is a string, it will return the
length of the string.
Syntax
Description
y = length(x);
y the number of elements in a matrix. For example, if x is

an n by m matrix, y = length( x ) = n * m.
See Also
Functions 157 , size 166 , transpose 175 , flip 170 , substring 176 , findstring 177 , replace 177 ,
Scripting Language
167
replacestring 178
7.4.20 pinch
Removes all singleton dimensions from a matrix.
Syntax
Description
out = pinch(x);
Removes all singleton dimensions. For example, if x is a

matrix of dimension 1x1x1xM, then
y=pinch(x);
will return a Mx1 matrix where
y(i) = x(1,1,1,i);
pinch(x,i);
Removes a specified dimension. If x is an NxMxKxP

matrix then
y=pinch(x,2);
will return an NxKxP matrix where
y(i,j,k) = x(i,1,j,k)
pinch(x,I,j);
Removes a specified dimension but keeps a specific index

for the dimension being removed. If x is an NxMxKxP
matrix then
y=pinch(x,2,4);
will return an NxKxP matrix where
y(i,j,k) = x(i,4,j,k)
See Also
Functions 157 , find 174 , size 166 , flip 170
7.4.21 sum
Sum of elements in a matrix.
Syntax
Description
out = sum(x);
Sum of all the elements in a matrix, over all dimensions.
out = sum(x,2);
Sum x over the specified dimension.
See Also
Functions 157 , integrate 173 , mean 192
168
Reference Guide
7.4.22 max
The maximum value in a matrix. For complex numbers, only the real part is considered.
Syntax
Description
out = max(x);
The maximum value in a matrix.
See Also
Functions 157 , min 168 , abs 164 , mean 192
7.4.23 min
The minimum value in a matrix. For complex numbers, only the real part is considered.
Syntax
Description
out = min(x);
The minimum value in a matrix.
See Also
Functions 157 , max 168 , abs 164 , mean 192
7.4.24 dot
Dot product.
Matrix A, B must have the same number of elements. The dot product will be calculated
with the following formula.
A(i ) B (i )
i
Syntax
Description
C = dot(A, B);
Returns the dot product of A and B
See Also
Functions 157 , cross 168 , * 150 , length 166 , size 166
7.4.25 cross
Vector cross product.
Matrix A, B must be the same size. The cross product will be computed on the first
dimension that has a size of 3. There must be at least one dimension with a size of 3.
Scripting Language
169
Assume that A,B are 2D matrices, where the second dimension contains the vector
components. The size of the second dimension must be 3. Then the elements of C will be
calculated with the standard cross product formulas.
C (i,1)
A(i,2) B(i,3) A(i,3) B(i,2)
C (i,2)
A(i,1) B(i,3) A(i,3) B(i,1)
C (i,3)
A(i,1) B(i,2) A(i,2) B(i,1)
Syntax
Description
C = cross(A, B);
Returns the cross product of A and B
See Also
Functions 157 , dot 168 , * 150 , length 166 , size 166
7.4.26 eig
Find the eigen value and/or eigen vector of a matrix. The matrix has to be square.
Syntax
Description
out = eig(A);
out = eig(A, 1);
Returns the eigenvalues of matrix A.
out = eig(A, 2);
Returns the eigenvectors of matrix A.
out = eig(A, 3);
Returns both the eigenvalues and eigenvectors of matrix

A.
See Also
Operators 148 , = 132 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , !
154 , ~ 155 , mult 169 , permute 170 , reshape 170 , inv 171
7.4.27 mult
Perform matrix multiplication of two or more matrices. The dimensions of the matrices have
to match
Syntax
Description
out = mult(A,B,...)
Returns the matrix multiplication of matrices, A x B x C ...
170
Reference Guide
See Also
Operators 148 , = 132 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , !
154 , ~ 155 , eig 169 , permute 170 , reshape 170 , inv 171
7.4.28 flip
Flip a matrix along one dimension.
Syntax
Description
C = flip(A, dim);
Flips the matrix A along the dimension dim.
See Also
Functions 157 , size 166 , length 166 , pinch 167 , transpose 175 , reshape 170 , permute 170
7.4.29 permute
This function is a more general version of the transpose function. It allows matrix
dimensions to be rearranged as needed.
Syntax
Description
out = permute(A, [i,j,k, ...])
Returns a matrix with the same elements as A but with

rearranged dimensions i,j,k, etc.
See Also
Operators 148 , = 132 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , !
154 , ~ 155 , eig 169 , reshape 170 , mult 169 , inv 171 , flip 170 , transpose 175 , size 166
7.4.30 reshape
Reshapes the matrix A to have the size i,j,k.The product of the specified dimensions,
i*j*k*..., must be the same as that of the original matrix A.
Syntax
Description
out = reshape(A, [i,j,k, ...])
Returns an array with the same elements as A but

reshaped to have the size i by j by k by ...
Scripting Language
171
See Also
Operators 148 , = 132 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , !
154 , ~ 155 , eig 169 , permute 170 , mult 169 , inv 171 , flip 170 , transpose 175 , size 166
7.4.31 inv
Calculate the inverse of a matrix. The matrix has to be invertible.
Syntax
Description
out = Inv(A)
Returns the inverse of matrix A
See Also
Operators 148 , = 132 , == 151 , != 152 , <= 152 , >= 152 , < 153 , > 153 , & 153 , and 153 , | 154 , or 154 , !
154 , ~ 155 , eig 169 , mult 169
7.4.32 interp
Linear interpolation of a data set. The data can be complex.
Syntax
Description
out = interp(Ex, xold,

xnew);
Does a linear interpolation of a 1D function.

Ex is existing data
xold specifies the points where Ex is sampled
xnew specifies new point to interpolate the data.
The xnew does does not have to be within the bounds of
xold.
interp(Ex, xold, yold, xnew,

ynew);
The 2D version of interp.
interp(Ex, xold, yold, zold,

xnew, ynew, znew);
interp(Ex, xold, yold, zold,

told, xnew, ynew, znew,
tnew);
See Also
Functions 157 , spline 172
172
Reference Guide
7.4.33 interptri
The script command interpolates a data set from triangular to linear grid. The data can be
complex.
Syntax
Description
out = interptri(tri, vtx,u, xi, yi, Does a triangular to linear interpolation of a function and
extrap_val);
outputs a PxQ array of interpolated values, z(xi,yi).
u is existing data of the finite element mesh (Nx1).
xi (length P) / yi (length Q) specifies the points where u
is to be sampled on the rectilinear mesh, in the xdirection and the y-direction
tri is the elements of the triangular mesh taken from the
simulation region, the connectivity array, Mx3,
containing row entries that index the three vertices of M
triangles
vtx are the vertices of the triangular mesh, Nx2,
containing row entries of (x,y) pairs, taken from the
simulation region
extrap_val(optional): if an interpolation point is outside of
the finite element mesh, the point will be assigned this
value (default is Inf)
See Also
quadtri
7.4.34 spline
Does a cubic spline interpolation of a data set.
Syntax
Description
out = spline(Ex,xold,xnew);
Cubic spline interpolation of a 1D function.

Ex is existing data
xold specifies the points where Ex is sampled
xnew specifies new point to interpolate the data.
The xnew does does not have to be within the bounds of
xold.
See Also
Functions 157 , interp 171
Scripting Language
173
7.4.35 integrate
Returns the integral over the specified dimension of a matrix.
Integrals over singleton dimensions will return zero (i.e. the area under a single point is
zero). See integrate2 for an alternate behavior.
Syntax
Description
out = integrate(A, n, x1);
Integrates A over the nth dimension in the matrix.

x1 is the corresponding position vector for that dimension.
out = integrate(A, d, x1,

x2, ...);
Calculates the integral of A over the specified list of

dimension(s) d.
d is a vector containing the dimensions over which to
integrate.
xi are the position vectors corresponding to the dimensions
of A over which the integration is occurring.
For example
power = integrate(A,1:2,x,y) will integrate A over an x-y
surface.
See Also
Functions 157 , integrate2 173 , max 168 , min 168 , interp 171 , find 174 , pinch 167 , round 189 ,
getdata 269 , sum 167 , length 166
7.4.36 integrate2
Very similar to the standard integrate function, except that singleton dimensions are
ignored.
As described in the integrate function description, integrating over dimensions with a single
value (singleton dimensions) returns zero because the area under a single point is zero. In
some cases, particularly when you are not sure which dimensions are singleton, this
behavior can cause difficulties. The integrate2 function automatically ignores all
dimensions with a size of one, which avoids the problem of a zero valued integrals due to
singleton dimensions.
Syntax
Description
out = integrate2(A, 1, x1);
Integrates A over the first dimension in the matrix.

x1 is the corresponding position vector.
out = integrate2(A, d, x1, x2, Calculates the integral of A over the specified dimension(s)
...);
d.
174
Reference Guide
d is a vector containing the dimensions over which to
integrate.
xi is the position vector corresponding to the dimensions of
A over which the integration is occurring. If any of the xi
vectors only have 1 element, integrate returns 0.
For example
power = integrate2(A,1:2,x,y) will integrate A over an x-y
surface.
See Also
Functions 157 , integrate 173 , max 168 , min 168 , interp 171 , find 174 , pinch 167 , round 189 ,
getdata 269 , sum 167 , length 166
7.4.37 find
This function will search for entries in a matrix that meet some condition. The indices of
those values are returned.
For multi-dimensional matrixes, the find function will still return a single index. This is
useful when using the output from find in a loop.
Syntax
Description
out = find(x,5e-6);
Will return the index of x that corresponds to the closest

value to 5e-6.
out = find(x>5);
Will return indices of all values of x that are greater than 5.
See Also
Functions 157 , pinch 167 , findpeaks 174 , integrate 173 , length 166 , size 166 , mod 189 ,
meshgrid3dx 135 , meshgrid3dy 135 , meshgrid3dz 136
7.4.38 findpeaks
Returns the position of peaks in a matrix. A peak is defined as a data point that is larger
than its nearest neighbors.
Syntax
Description
out = findpeaks(y);
Returns the position of the peak with the largest value in y.

The length of y must be at least 2. If no peak is found in
the data, a value of 1 is returned.
findpeaks(y,n);
Returns a matrix containing the positions of the largest n

peaks found in the data. The returned values are ordered
Scripting Language
175
from largest to smallest. The returned matrix is always of

dimension nX1. If less than n peaks are found, the
remaining values of the returned matrix are 1.
See Also
Functions 157 , find 174
7.4.39 transpose
Transpose a 1D or 2D matrix.
Syntax
Description
y = transpose(x);
If x is an N x M matrix, then y will be M x N, where the

entries are y(j,i)=x(i,j).
See Also
Functions 157 , ctranspose 175 , reshape 170 , flip 170 , permute 170 , size 166
7.4.40 ctranspose
Transpose a 1D or 2D matrix and take the complex conjugate of each element.
Syntax
Description
y = ctranspose(x);
If x is an N x M matrix, then y will be M x N, where the

entries are y(j,i)=x(i,j)* .
See Also
Functions 157 , transpose 175
7.4.41 num2str
Convert an integer, floating point number, or matrix into a string. Use the format script
command to change the precision of the output.
Syntax
Description
out = num2str(x);
Converts the number x into a string. x can also be a 1D or

2D matrix.
See Also
Operators 148 , " 155 , + 150 , ? 157 , endl 157 , write 123 , format 121 ,str2num 176 , findstring 177 ,
replace 177 , replacestring 178 , substring 176 , eval 176
176
Reference Guide
7.4.42 str2num
Convert a string into a floating point number. Use the format script command to change the
precision of the output.
Syntax
Description
out = str2num(string);
Converts string into a number.
See Also
Operators 148 , " 155 , + 150 , ? 157 , endl 157 , write 123 , format 121 , findstring 177 , replace 177 ,
replacestring 178 , substring 176
7.4.43 eval
Execute string containing Lumerical scripting language.
Syntax
Description
eval(string);
Execute string containing Lumerical scripting language at

the Lumerical script prompt.
See Also
Operators 148 , feval 176 , str2num 176 , num2str 175
7.4.44 feval
Evaluates a string as script file. This function is useful for running script files that are not in
your path and files with spaces in the name.
Syntax
Description
feval(filename);
Execute string containing the name of a script file at the

Lumerical script prompt.
See Also
Operators 148 , eval 176 , str2num 176 , num2str 175
7.4.45 substring
Can be used to extract a substring from a string.
Syntax
Description
Scripting Language
177
s1 = substring(s,pos);
Returns a substring of s, starting at position pos to the end

of s. The position pos can be 1 to length(s).
s1 = substring(s,pos,len);
Returns a substring of s, starting at position pos, with len

characters. If len is -1 (or any value less than 0) it returns
the substring at position pos to the end of s. The default
value of len is -1.
See Also
Functions 157 , length 166 , findstring 177 , replace 177 , replacestring 178 , str2num 176 , num2str
175 , splitstring 178
7.4.46 findstring
Returns the position of a given substring in a string.
Syntax
Description
pos = findstring(s,s1);
Returns the position of the first instance substring s1 in s.

If s1 is not found in s, it returns -1.
pos = findstring(s,s1,p0);
Returns the position of the first instance substring s1 in s,

starting at position p0. If s1 is not found in s, starting from
p0, it returns -1.
See Also
Functions 157 , length 166 , substring 176 , replace 177 , replacestring 178 , str2num 176 , num2str
175 , splitstring 178
7.4.47 replace
Replaces a substring of a string with a new string.
Syntax
Description
snew = replace(s,pos,len,
s1);
Replaces len characters of s, starting at position pos, with

the string in s1. If len is 0, it will insert the string s1
between pos-1 and pos. If len is -1 (or any values less than
0) it will replace all remaining characters in s with s1,
starting at pos. The position pos can be 1 to length(s).
See Also
Functions 157 , length 166 , substring 176 , findstring 177 , replacestring 178 , str2num 176 ,
num2str 175 , splitstring 178
178
Reference Guide
7.4.48 replacestring
Replaces a substring of a string with a new string.
Syntax
Description
snew = replacestring(s,s1,
s2);
Replaces all instances of s1 in s with s2.
See Also
Functions 157 , length 166 , substring 176 , findstring 177 , replace 177 , str2num 176 , num2str 175 ,
splitstring 178
7.4.49 splitstring
Split a long string into a series of substrings, where the substrings are stored in a cell (ie.
string) array.
Syntax
Description
S2 = splitsting(S1,endl);
Split the string S1 into a series of strings, using the end of

line character as the delimiter between strings. S2 is a
cell array.
See Also
Functions 157 , length 166 , substring 176 , findstring 177 , replace 177 , str2num 176 , num2str 175 ,
cell 147 , dir 114 , getresult 270
7.4.50 fft
Compute the 1D, 2D or 3D Fast Fourier Transform (fft) of a matrix. In the 1D case the
transform is given by
N
E w [ m]
fft( E x )
E x [ n] e
2 i
)( n 1)( m 1)
N
n 1
The fft, inverse fft and all associated functions have an option (option 1 below) that controls
the format used to store the frequency domain data. When working with spectral data it is
not possible to switch between formats; there are no functions to convert between formats.
This implies that if you use option 1=n to produce a spectrum with fft, then you must also
use option 1=n if you want to pass that same spectral data to invfft. Similarly, if you use
option 1=n for fft, then you also need to use option 1=n with fftw to get the proper frequency
vector corresponding to your spectrum. invfft and fftk work in the same way.
Scripting Language
179
Syntax
Description
out = fft(Ex);
Returns the fast Fourier transform of Ex. Ex can be 1D, 2D

or 3D.
out = fft(Ex,option1,
option2);
option1
This option controls the format used to store the frequency
domain data. The options are:
1 : the standard fft (zero frequency is at the first element
of the matrix).
2 : zero frequency is the first element, but only data up
to and including the Nyquist frequency is stored. This
option is only useful for real valued, 1D time/spatial
signals.
3 : the fft is shifted so zero frequency is the central
element of the spectrum (precisely, this means the zero
frequency point is at element floor(N/2 + 1), where N is
the number of samples).
option2
This option is either a 1, 2 or 3 element vector depending
on whether Ex is 1D, 2D or 3D. For each dimension,
specify a value of either 0, 1 or N to obtain the desired 0
padding options.
0: no zero padding
1: zero padding up to the next power of 2 longer than the
length of Ex (default)
N: zero pad up to length N if N > length(Ex), where
length of Ex is the length in a specific dimension. If N <=
length(Ex), it will zero pad up to the next power of 2
longer than the length of Ex. For the fastest results, N
should be a power of 2 and can be entered, for example,
as 2^12.
Note: FFT Conventions

There are different, but equivalent conventions for defining Fourier transforms. Lumerical
defines the forward FFT using a positive sign in the exponential term, and the inverse FFT
using a negative sign in the exponential term. However, some other packages (e.g.
MATLAB) use the opposite convention, with a negative sign in the exponential for the
forward FFT and a positive sign in the exponential for the inverse FFT. To convert between
the different FFT conventions, switch the invfft and fft and rescale the results. For a signal
y with N elements this can be done as follows:
180
Reference Guide
Lumerical
MATLAB
fft(y,1,0)
invfft(y,1,0)
ifft(y)*N
fft(y)/N
See Also
Functions 157 , invfft 182 , fftw 180 , fftk 181 , czt 183
7.4.51 fftw
Returns the angular frequency vector corresponding to time vector t.
fftw(t )
2
0,
dt M
, ( M 1)
,
where M=length(t).
fftw and all related functions have an option (option 1 below) that controls the format used to
store the frequency domain data. When working with spectral data it is not possible to
switch between formats; there are no functions to convert between formats. This implies
that if you use option 1=n to produce a spectrum with fft, then you must also use option
1=n if you want to pass that same spectral data to invfft. Similarly, if you use option 1=n
for fft, then you also need to use option 1=n with fftw to get the proper frequency vector
corresponding to your spectrum. Invfft and fftk work in the same way.
Syntax
Description
out = fftw(t);
Returns the angular frequency vector corresponding to time

vector t.
fftw(t,option1,option2);
Option1
1 : the standard fft (default)
2 : frequencies above the Nyquist frequency are
removed
3 : the fft is shifted so both positive and negative
frequencies are seen
Option2
0: no zero padding
N: zero pad up to length N if N > length(t). If N <= length
(t), it will zero pad up to the next power of 2 longer than
the length of t. For the fastest results, N should be a
power of 2 and can be entered, for example, as 2^12.
Scripting Language
181
See Also
Functions 157 , fft 178 , fftk 181 , invfft 182
7.4.52 fftk
Returns the spatial wavevector kx associated with a fourier transform of a function of x.
fftk( x)
2
0,
dx M
, ( M 1)
,
where M=length(x).
fftk and all related functions have an option (option 1 below) that controls the format used to
store the frequency domain data. When working with spectral data it is not possible to
switch between formats; there are no functions to convert between formats. This implies
that if you use option 1=n to produce a spectrum with fft, then you must also use option
1=n if you want to pass that same spectral data to invfft. Similarly, if you use option 1=n
for fft, then you also need to use option 1=n with fftw to get the proper frequency vector
Syntax
Description
out = fftk(x);
Returns the spatial wavevector kx associated with a fourier

transform of a function of x..
fftk(x,option1,option2);
Option1
1 : the standard fft (default)
2 : frequencies above the Nyquist frequency are
removed
3 : the fft is shifted so both positive and negative
frequencies are seen
Option2
0: no zero padding
N: zero pad up to length N if N > length(x). If N <= length
(x), it will zero pad up to the next power of 2 longer than
the length of x. For the fastest results, N should be a
power of 2 and can be entered, for example, as 2^12.
See Also
Functions 157 , fft 178 , fftw 180 , invfft 182
182
Reference Guide
7.4.53 invfft
Compute the 1D,2D or 3D inverse Fast Fourier Transform (fft) of a matrix. In the 1D case
the transform is given by
E x [ m]
invfft( E w )
1
N
E w [ n] e
2 i
)( n 1)( m 1)
N
n 1
The inverse fft, fft and all related functions have an option (option 1 below) that controls the
format used to store the frequency domain data. When working with spectral data it is not
possible to switch between formats; there are no functions to convert between formats. This
implies that if you use option 1=n to produce a spectrum with fft, then you must also use
option 1=n if you want to pass that same spectral data to invfft. Similarly, if you use option
1=n for fft, then you also need to use option 1=n with fftw to get the proper frequency vector
Syntax
Description
out = invfft(x);
Returns the inverse fast Fourier transform of x. x can

1D,2D or 3D.
invfft(x,option1,option2);
option1
This option controls the format used to store the frequency
domain data. The options are:
1 : the standard fft (zero frequency is at the first element
of the matrix).
2 : zero frequency is the first element, but only data up
to and including the Nyquist frequency is stored. This
option is only useful for real valued, 1D time/spatial
signals.
3 : the fft is shifted so zero frequency is the central
element of the spectrum (precisely, this means the zero
frequency point is at element floor(N/2 + 1), where N is
the number of samples).
option2
This option is either a 1, 2 or 3 element vector depending
on whether Ex is 1D, 2D or 3D. For each dimension,
specify a value of either 0, 1 or N to obtain the desired 0
padding options.
0: no zero padding
N: zero pad up to length N if N > length(Ex), where
Scripting Language
183
length of Ex is the length in a specific dimension. If N <=

length(Ex), it will zero pad up to the next power of 2
longer than the length of Ex. For the fastest results, N
should be a power of 2 and can be entered, for example,
as 2^12.
See Also
Functions 157 , fft 178 , fftw 180 , fftk 181
7.4.54 czt
Returns the chirped z-transform of a set of data. The czt function is often more convenient
than the standard fft functions because you can specify an arbitrary range of k.
E k [ m]
E x [n] e ix[ n ]k [ m ]
czt ( E x , x, k )
n
E k [m1, m2]
E x [n1, n 2] e ix[ n1]k [ m1]
czt ( E x , x1, x 2, k1, k 2)
ix[ n 2 ] k [ m 2 ]
n1, n 2
Syntax
Description
out = czt(Ex,t,w)
Returns the chirped z-transform of Ex, function of t, at

each desired angular frequency w. Note that w must be a
linearly spaced set of angular frequencies but can cover
any range.
czt(Ex,x,y,kx,ky);
The two dimensional chirped z-transform. kx and ky must

be linearly spaced sets of wavenumbers but can cover any
range.
See Also
Functions 157 , fft 178
7.4.55 polyarea
Returns the area of a polygon. The area is positive if the vertices are defined in a counterclockwise direction, and negative if the vertices are defined in a clockwise direction.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N
>= 3. The second dimension represents the x,y positions. For example, a valid polygon is
V = [ 0,0; 1,0; 1,1; 0,1];
Syntax
Description
184
Reference Guide
out = polyarea(V);
Returns the area of V. The sign of the area indicates if V is

defined in a counter-clockwise (positive) or clockwise
(negative) direction.
See Also
Functions 157 , centroid 184 , polyintersect 184 , inpoly 185 , polygrow 185 , polyand 186 , polyor
186 , polydiff 186 , polyxor 187
7.4.56 centroid
Returns the center of mass of a polygon.
V = [ 0,0; 1,0; 1,1; 0,1];
Syntax
Description
out = centroid(V);
Returns the center of mass of V, assuming uniform

density. The output is a 2x1 matrix representing the x and
y positions.
See Also
Functions 157 , polyarea 183 , polyintersect 184 , inpoly 185 , polygrow 185 , polyand 186 , polyor
7.4.57 polyintersect
Determines if two polygons intersect.
V = [ 0,0; 1,0; 1,1; 0,1];
Syntax
Description
out = polyintersect(V1,V2);
Returns
0 if the polygons do not overlap
0.5 if the polygons touch
1 if they overlap
2 if one polygon completely encloses the other
See Also
Functions 157 , polyarea 183 , centroid 184 , inpoly 185 , polygrow 185 , polyand 186 , polyor 186 ,
Scripting Language
185
polydiff 186 , polyxor 187
7.4.58 inpoly
Determines if a point is inside our outside a polygon. The function is vectorized so it can be
used to create a mesh of a polygon.
V = [ 0,0; 1,0; 1,1; 0,1];
Syntax
Description
out = inpoly(V,x,y);
Returns a matrix of the same dimension of x with 1 if the

corresponding point is inside the polygon and 0 otherwise.
The matrices x and y must have the same length, or one of
them can be a singleton.
See Also
Functions 157 , polyarea 183 , centroid 184 , polyintersect 184 , polygrow 185 , polyand 186 , polyor
7.4.59 polygrow
Returns a polygon that has grown or shrunk by the specified amount. The polygon is grown
in a direction normal to every line segment.
V = [ 0,0; 1,0; 1,1; 0,1];
Syntax
Description
out = plygrow(V,dx);
Returns a new polygon that has grown by dx. To shrink a

polygon, use dx < 0.
See Also
Functions 157 , polyarea 183 , centroid 184 , polyintersect 184 , inpoly 185 , polyand 186 , polyor
186
Reference Guide
7.4.60 polyand
Combines two polygons into one using a boolean and operation.
V = [ 0,0; 1,0; 1,1; 0,1];
Syntax
Description
V3 = polyand(V1,V2);
Returns a new polygon, V3, that is the and of V1 and V2.
See Also
Functions 157 , polyor 186 , polydiff 186 , polyxor 187 , polyarea 183 , centroid 184 , polyintersect
184 , inpoly 185 , polygrow 185
7.4.61 polyor
Combines two polygons into one using a boolean or operation.
V = [ 0,0; 1,0; 1,1; 0,1];
Syntax
Description
V3 = polyor(V1,V2);
Returns a new polygon, V3, that is the or of V1 and V2.
See Also
Functions 157 , polyand 186 , polydiff 186 , polyxor 187 , polyarea 183 , centroid 184 , polyintersect
7.4.62 polydiff
Combines two polygons into one by taking the difference.
V = [ 0,0; 1,0; 1,1; 0,1];
Syntax
Description
V3 = polydiff(V1,V2);
Returns a new polygon, V3, that is V1-V2.
See Also
Functions 157 , polyand 186 , polyor 186 , polyxor 187 , polyarea 183 , centroid 184 , polyintersect
Scripting Language
184 ,
187
inpoly 185 , polygrow 185
7.4.63 polyxor
Combines two polygons into one using a boolean xor operation.
V = [ 0,0; 1,0; 1,1; 0,1];
Syntax
Description
V3 = polyxor(V1,V2);
Returns a new polygon, V3, that is the xor of V1 and V2.
See Also
Functions 157 , polyand 186 , polyor 186 , polydiff 186 , polyarea 183 , centroid 184 , polyintersect
7.4.64 lineintersect
Returns the intersection points of lines in the x-y plane. Note that the intersection point
does not have to lie on the line segments themselves that define the lines. To see if the line
segments actually cross the command linecross should be used.
Line segments are contained in a single matrix of dimension 2*Nx2, where there are N line
segments. For example, the matrix L = [ 0,0; 1,1; 0,0, 0,1]; represents 2 lines segments,
one from (0,0) to (1,1) and another from (0,0) to (0,1).
Syntax
Description
out = lineintersect(L1,L2);
Returns the intersection of the lines represented by the

segments in L1 and L2. L1 and L2 must have the same
size (2*N,2 for N line segments). The result is a sequence
of x,y points in the form Nx2 representing the intersections
of the N lines. There are special cases when
The lines are parallel. In this case, the position returned
is (1.#INF,b). The value of 1.#INF can be tested for using
the script commands finite. The value of b is 0 if the lines
are not coincident and 1 if they are coincident.
The points in a segment are degenerate, ie the same. In
this case, the position returned is (1.#INF,b), where b is
0, 1, 2 if the both line segments are degenerate, the first
is degenerate, or the second is degenerate respectively.
188
Reference Guide
See Also
Functions 157 , linecross 188 , finite 191
7.4.65 linecross
Determines if line segments cross each other.
Line segments are contained in a single matrix of dimension 2*Nx2, where there are N line
segments. For example, the matrix L = [ 0,0; 1,1; 0,0, 0,1]; represents 2 lines segments,
one from (0,0) to (1,1) and another from (0,0) to (0,1).
Syntax
Description
out = linecross(L1,L2);
Returns a matrix of dimension N which determines if the N

line segments in L1 and the N line segments in L2 cross.
L1 and L2 must have the same size (2*Nx2 for N line
segments). The result is a matrix of length N that is 0 if
the segments do not cross, 1 if they cross and 0.5 if the
endpoint of one line touches another. Line segments that
are coincident and touch also return a value of 0.5
See Also
Functions 157 , lineintersect 187 , finite 191
7.4.66 ceil
The ceil command rounds the input to the nearest integer greater than or equal to itself.
Syntax
Description
out = ceil(X);
Returns the nearest integer greater than or equal to X.
See Also
Functions 157 , floor 188 , mod 189
7.4.67 floor
The floor command rounds the input to the nearest integer less than or equal to itself.
Syntax
Description
out = floor(X);
Returns the nearest integer less than or equal to X.
See Also
Functions 157 , ceil 188 , mod 189
Scripting Language
189
7.4.68 mod
Modulus after division.
Syntax
Description
out = mod(X,Y);
Returns X - n.*Y where n = floor(X./Y) if Y is not equal to 0.

The input X must be a real array or a real scalar. Y must
be a real scalar.
The following are true by convention:
mod(X,0) = X
mod(X,X) = 0
See Also
Functions 157 , floor 188 , ceil 188
7.4.69 sign
Get the sign of a number.
Syntax
Description
out = sign(data);
Real values
sign = 0 for data=0
sign = 1 for data>0
sign =-1 for data<0
Complex values
sign = 0 for data=0+0i
sign = data/abs(data) for data!=0
See Also
Functions 157 , floor 188 , ceil 188
7.4.70 round
Rounds a number to the nearest integer.
Syntax
Description
out = round(x);
Rounds x to the nearest integer.
See Also
Functions 157
190
Reference Guide
7.4.71 rand
Generate a uniform random number between 0 and 1.
Syntax
Description
out = rand;
Generates a uniform random number between 0 and 1.
out = rand(min,max);
Generates a random number between min and max. By

default, min and max are 0 and 1 respectively.
out = rand(min,max,option);
option = 1: output is a double precision number between

min and max (default)
option = 2: output is an integer between min and max.
See Also
Functions 157 , randreset 191 , randmatrix 133
7.4.72 lognrnd
Generate a lognormal distributed random number. This command is available in
INTERCONNECT only.
Syntax
Description
out = lognrnd (mean,stddev); Generates a lognormal distributed random number with

user defined mean value and standard deviation.
See Also
Functions 157 , randreset 191 , randn 190
7.4.73 randn
Generate a normally distributed random number. This command is available in
INTERCONNECT only.
Syntax
Description
out = randn;
Generates a normally distributed random number with

mean 0 and standard deviation 1.
out = randn(mean,stddev);
Generates a normally distributed random number with user

defined mean value and standard deviation.
See Also
Functions 157 , randreset 191 , lognrnd 190 , randnmatrix 134
Scripting Language
191
7.4.74 randreset
Resets the random number generator seed.
Syntax
Description
out = randreset;
Resets the random number seed based on the clock time.

This function returns the random number seed that was
used.
out = randreset(seed);
Set the seed to a specific value
See Also
Functions 157 , rand 190 , randmatrix 133
7.4.75 finite
The finite command returns 1 (true) if a value is finite. Numbers such as NaN or #1.INF
return 0 (false).
Syntax
Description
out = finite(x);
Returns a matrix of the same size as x. The values are 1

for values of x that are finite and 0 for values that are NaN.
For example, finite(1/0) returns 0.
See Also
Functions 157
7.4.76 solar
Returns the solar power spectrum, in Watts/meter^2/meter. This command is available in
FDTD and DEVICE.
The values are based on the global tilt values from the following link:
http://rredc.nrel.gov/solar/spectra/am1.5/ASTMG173/ASTMG173.html
Syntax
Description
out = solar(1);
Returns the power of the solar spectrum as a function of

wavelength, in W/m^2/m
out = solar(0);
Returns the corresponding wavelength vector, in m
See Also
plot 198 , integrate 173
192
Reference Guide
7.4.77 stackrt
Analytically calculates the reflection and transmission of a plane wave through a multi-layer
stack. This function returns the fraction of transmitted and reflected power (Ts, Tp, Rs,
Rp), and the complex reflection and transmission coefficients (ts, tp, rs, rp), for both S and
P polarizations. All results are returned in a single dataset as a function of frequency and
incidence angle (optional).
Note: Thickness of first and last layer
It is necessary to specify the thickness of each layer, including the first and last layers.
Often, a thickness of zero can be used for these layers, meaning the results will be
calculated just beyond the first and last interface. If a larger value is used, the results will
be calculated further from the interface. For non-lossy materials, this will not effect the
reflected and transmitted power, but it will change phase of the complex coefficients.
Syntax
Description
RT = stackrt(n,d,f);
Arguments for a stack with Nlayers:

n: Refractive index of each layer. Size is either Nlayers, or
Nlayers x length(f) if dispersive materials are involved.
d: Thickness of each layer. Size is Nlayers.
f: Frequency vector.
RT = stackrt(n,d,f,theta);
theta: Angle vector, in degrees. Optional.
See Also
Functions 157
7.4.78 mean
The mean value in a matrix is returned.
Syntax
Description
out = max(a);
The mean value of the matrix a is returned.
See Also
max 168 , min 168 , abs 164 , sum 167
7.4.79 all
The script command returns 1 if all of the specified matrix entries are nonzero and returns 0
otherwise.
Syntax
Description
Scripting Language
out = all(A);
193
Will return 1 if all of the A matrix entries are nonzero and

will return 0 otherwise.
See Also
any 193 , almostequal 151
7.4.80 any
The script command returns 1 if any of the specified matrix entries are nonzero and returns
0 otherwise.
Syntax
Description
out = any(A);
Will return 1 if any of the A matrix entries are nonzero and

will return 0 otherwise.
See Also
all 192 , almostequal 151
7.4.81 var
The script command returns the variance of all entries of the matrix specified, where
variance is defined as,
var
1
N
N
i 1
( xi
Syntax
Description
out = var(A);
Will return variance of all of matrix A, over all dimensions.
See Also
std 194 , mean 192
194
Reference Guide
7.4.82 std
The script command returns the standard deviation of the all entries of the matrix specified,
where standard deviation is defined as,
1
N
N
i 1
( xi
Syntax
Description
out = std(A);
Will return standard deviation of matrix A, over all

dimensions.
See Also
var 193 , mean 192
7.4.83 mapfind
The script command returns the nearest value from a file containing a map of values to a
string. It returns the string value located at the specified nearest point.
Syntax
Description
out = mapfind (filename,x,y); Find the nearest value from a file containing a map of
values to a string. It l returns the string value located at the
nearest point (x,y).
out = mapfind (filename,x,y,
z);
Find the nearest value from a file containing a map of

values to a string. It returns the string value located at the
nearest point (x,y,z).
out = mapfind (filename,x,y,

z,w);
Find the nearest value from a file containing a map of

values to a string. It returns the string value located at the
nearest point (x,y,z,w).
See Also
readdata 122 , readdata 122
Scripting Language
195
7.4.84 quadtri
The script command approximates integration (first order quadrature) of data on a 2D finite
element mesh.
Syntax
Description
out = quadtri(tri,vtx,u);
outputs a scalar, the integral of u on the finite element

mesh, where
tri: the connectivity array, Mx3, containing row entries
that index the three vertices of M triangles
vtx: the vertex array, Nx2, containing row entries of (x,y)
pairs
u: the data on the finite element mesh (Nx1)
See Also
interptri 172
7.4.85 expand
The script command returns the expansion coefficients between two arbitrary DFT
monitors. Typically, the reference monitor contains the modal fields for the expansion.
0.25 *
0.25 *
dS E1 H 2*
dS E2* H1
N2
N2
dS E1 H 2*
dS E2* H1
N2
N2
0.5 * dS E2 H 2*
0.5 * dS E1 H1*
For more detail on how to use this command, and how to interpret the results, please see
Using Mode Expansion Monitors.
Syntax
Description
expand('a','a_ref',x,y,z);
outputs the expansion coefficients between the fields of

two monitors
196
Reference Guide
a: the monitor name, of which expansion is performed
a_ref: the reference monitor
x/y/z: the displacement from the monitor a from the
reference monitor a_ref
See Also
Adding Objects 205 , Using Mode Expansion Monitors, setexpansion 262 , removeexpansion
263 , expand2
7.4.86 norm
The script command returns the natural norm induced by the L2-norm (Spectral Norm).
Syntax
Description
out = norm(y);
Returns y to the L2-norm, y is a matrix.
See Also
Functions 157
7.5
Loop and conditional statements

The scripting language currently supports FOR loops and IF statements. Other control
structures such as while loops or case statements must be constructed from these.
Command
Description
for 196
For loop.
if 197
If statement.
while 196
A for loop must be used. See the for loop section.
7.5.1 for
for loops allow some operations to be repeated a number of times. A while loop can be
implemented when using the three argument version of for.
Syntax
Description
for(x=1:100) { ?x; }
Single argument for loop.

The loop will be sequentially executed for each value
of x.
for(x=1; x<= 100; x=x+1) {

?x;
Three argument for loop.

x=1 at the start of the loop. The loop continues while
Scripting Language
}
x <=100 and sets x=x+1 at each pass.
x=1;
for(0; x<10; 0) {
?x;
x=x+1;
}
This is equivalent to a while loop that will execute

while x<10.
See Also
Loops 196 , if 197
7.5.2 if
The scripting language supports if statements in the following forms:
Syntax
Description
if(x < 5) { y = x^2; }
Simple if statement on one line.
if(x < 5) {
y = x^2;
}
Multi-line if statement
if(x < 5) {
y = x^2;
} else {
y = x^3;
}
If else statement.
if(x < 5) {
if(x > 0) {y = x^2; }
} else {
y = x^3;
}
Nested if statement with else.
See Also
Loops 196 , for 196
7.6
Plotting commands
Line and image plots are supported. These figures can be exported to jpeg images.
Plotting functions
Command
Description
197
198
Reference Guide
plot 198
Makes line plots.
plotxy 199
Makes line plots, when data sets are sampled at

different position vectors.
polar 200
Makes polar plots.
polar2 200
Makes polar plots, when data sets are sampled at

polarimage 201
Makes a 2D polar image plot.
histc 202
Makes a histogram plot.
legend 202
Makes a legend on a figure with line plots.
image 202
Makes 2D image plots.
setplot 204
Sets figure properties.
visualize 203
Pass in simulation data to the visualizer.
vectorplot 205
Makes vector plots.
Miscellaneous plotting functions

Command
Description
selectfigure 204
Selects a figure.
exportfigure 204
Exports a figure.
closeall 205
Closes all figure windows.
7.6.1 plot
Create line plots. All data sets must be sampled on the same position vector.
See plotxy for data sets that are sampled on different position vectors.
Syntax
Description
out = plot(x,y);
Creates a plot of y vs x, y and x are both 1D vectors with

the same length.
The figure number is returned.
plot(x,y);
x is a nx1 matrix.
y is a nxm matrix.
This will generate a graph with m lines. (y(1:n,1) vs x, y(1:
n,2) vs x, etc)
Scripting Language
199
plot(x,y1,y2,y3);
Creates a plot with 3 curves, x,y1, y2, y3 must be the

same length, returns the figure number.
plot(x,y, "x label", "y label",

"title");
Creates a plot of y vs x with axis labels and a title, returns

the figure number.
plot(x,y, "x label", "y label",

"title", "options");
Creates a plot with desired options. Options can be be

log10x, log10y, loglog
plot points
greyscale
polar (same as the polar script command)
any comma separated list of the above, for example
"log10x,greyscale"
Returns the figure number.
See Also
Plotting commands 197 , plotxy 199 , legend 202 , image 202 , closeall 205 , setplot 204 ,
exportfigure 204 , visualize 203 , vectorplot 205 , polar 200
7.6.2 plotxy
Create line plots. In particular, this function is used when the data sets are sampled on
Syntax
Description
out = plotxy(x,y);
Creates a plot of y vs x, y and x are both 1D vectors with

the same length.
plotxy(x1,y1,x2,y2,xn,yn);
Creates a plot with multiple curves. The xn-yn pairs must

have the same length, but x1, x2, and xn can have different
start-end values and resolutions. It returns the figure
number.
plotxy(x1,y1,x2,y2, "x label", Creates line plots with axis labels and a title, returns the
"y label", "title");
figure number.
See Also
Plotting commands 197 , plot 198 , legend 202 , image 202 , closeall 205 , setplot 204 , exportfigure
204 , visualize 203 , vectorplot 205
200
Reference Guide
7.6.3 polar
Create polar plots. All data sets must be sampled on the same position vector.
See polar2 for data sets that are sampled on different position vectors.
Syntax
Description
out = polar(theta,rho)
Creates a polar coordinate plot of the angle theta versus

the radius rho. theta is the angle from the x-axis to the
radius vector specified in radians; rho is the length of the
radius vector.
Theta and rho can be vectors of the same length, or if the
length of theta is n, then y can be a nxm matrix.
polar(theta,rho1,rho2,rho3)
Creates a plot with 3 curves, theta, rho1, rho2, rho3 must

be the same length, returns the figure number.
polar(theta,rho,"x label", "y

label", "title")

the figure number.
polar(theta,rho,"x label", "y

label", "title", "options");

plot points
greyscale
"log10x,greyscale"
See Also
Plotting commands 197 , polar2 200 , legend 202 , image 202 , closeall 205 , setplot 204 ,
exportfigure 204 , polarimage 201 , plot 198
7.6.4 polar2
Create polar plots. In particular, this function is used when the data sets are sampled on
Syntax
Description
out = polar2(theta,rho)
Creates a polar coordinate plot of the angle theta versus

the radius rho. theta is the angle from the x-axis to the
Scripting Language
201
radius vector specified in radians; rho is the length of the

radius vector.
Theta and rho can be vectors of the same length, or if the
length of theta is n, then y can be a nxm matrix.
polar2(theta1,rho1,theta2,
rho2)
Creates a plot with 2 curves. The two data sets can be

sampled on different theta vectors.
polar2(theta,rho,"x label", "y

label", "title")

the figure number.
polar2(theta,rho,"x label", "y


plot points
greyscale
"log10x,greyscale"
See Also
Plotting commands 197 , polar 200 , legend 202 , image 202 , closeall 205 , setplot 204 ,
exportfigure 204 , polarimage 201
7.6.5 polarimage
Create 2D polar image plots. This is typically used to plot far field data.
Syntax
Description
polarimage(ux,uy,data);
Creates a 2D image plot. If

ux is of dimension N x 1, where ux goes from -1 to 1
uy is of dimension M x 1, where uy goes from -1 to 1
data must be of dimension N x M
out = image(ux,uy,data, "x

label", "y label", "title");
Creates a 2D image plot with axis labels

Optionally returns the figure number.
image(ux,uy,data, "x label",

"y label", "title", "options");
Creates a 2D image plot with axis labels and options,

options can be
logplot
See Also
Plotting commands 197 , plot 198 , polar 200 , image 202 , closeall 205 , setplot 204 , exportfigure
202
Reference Guide
204 ,
visualize 203 , Near to far field projections
7.6.6 histc
The script command create a histogram plot.
Syntax
Description
out = histc(y);
Creates a histogram plot of y.

histc(y,n);
Creates a histogram plot of y, using n bins.

histc (y,n, "x label", "y

label", "title");
Creates a histogram plot of y, using n bins, with axis

labels and a title.
See Also
Plotting commands 197 , histogram 134 , legend 202 , plot 198 , closeall 205 , visualize 203
7.6.7 legend
Add a legend to a line plot.
Syntax
Description
legend
("legend1","legend2",...,
"legendn");
Adds a legend to the selected figure.

See Also
Plotting commands 197 , legend 202 , plot 198 , closeall 205 , visualize 203
7.6.8 image
Create 2D image plots.
Syntax
Description
out = image(x,y,z);
Creates a 2D image plot. If

x is of dimension N x 1
y is of dimension M x 1
z must be of dimension N x M
Scripting Language
203
image(x,y,z, "x label", "y

label", "title");
Creates a 2D image plot with axis labels, returns the figure

number.
image(x,y,z, "x label", "y

Creates a 2D image plot with axis labels and options,

options can be
logplot
polar
any comma separated list of the above
See Also
Plotting commands 197 , plot 198 , closeall 205 , setplot 204 , exportfigure 204 , visualize 203 ,
polarimage 201 , vectorplot 205
7.6.9 visualize
Send data to the visualizer.
Syntax
Description
visualize(R);
Plots the dataset R in the Visualizer.
visualize("name",
x,y,z,
Plots data on a spatial grid.

name - Visualizer name
x,y,z - spatial grid vectors
p1,"p1" - additional parameter vectors (vector, then
parameter name).
"a1",a1 - data attributes (data name, then data matrix)
p1,"p1", p2,"p2",
"a1",a1,"a2",a2);
visualize("name",
x,y,z,
Plot vector data

"a1",a1x,a1y,a1z - data attributes (data name, then data
matrix X,Y,Z components)
p1,"p1", p2,"p2",
"a1",a1x,a1y,a1z);
visualize("name",
p1,"p1", p2,"p2",
"a1",a1x,a1y,a1z);
Plot data not attached to a spatial grid.
See Also
Plotting commands 197 , Datasets 141 , exportfigure 204 , image 202 , plot 198 , setplot 204 ,
closeall 205
204
Reference Guide
7.6.10 selectfigure
Selecting a figure will show the figure on screen (give it focus). A warning will be generated
if the figure does not exist.
Syntax
Description
selectfigure;
Selects the last figure that was created.

selectfigure(1);
Selects figure 1.
See Also
Plotting commands 197 , exportfigure 204 , image 202 , plot 198 , setplot 204 , closeall 205
7.6.11 setplot
Set figure properties.
Syntax
Description
?setplot;
Creates a string which lists all figure properties for the

figure that is currently selected. Unless the setfigure()
command was called, the most recently created plot will
be selected.
setplot("property", "property
value");
Set the desired property of the currently selected figure to

property value.
See Also
Plotting commands 197 , image 202 , plot 198 , visualize 203
7.6.12 exportfigure
Exports the current figure to a JPG image. If the file extension is not specified, ".jpg" will be
used. The image size will be the same as the figure window size.
If a file is overwritten, a warning will be generated. If an export fails, a warning will be
generated.
Syntax
Description
exportfigure("filename");
Exports the current figure to a JPG image with the name

"filename".
The exported image will have the same size as the current
Scripting Language
205
figure.
exportfigure("filename",xres,
yres);
Exports the current figure to a JPG image with the name

"filename".
The exported image will have the specified resolution, xres,
yres, in the x,y directions respectively.
See Also
Plotting commands 197 , selectfigure 204 , image 202 , plot 198 , setplot 204 , closeall 205 ,
visualize 203
7.6.13 closeall
Close all open figure windows.
Syntax
Description
closeall;
Close all open figure windows.

See Also
Plotting commands 197 , plot 198 , image 202
7.6.14 vectorplot
The script command vectorplot creates a vector plot from a rectilinear dataset. The
rectilinear dataset must be a vector, like the E field, and it must have no additional
parameters (i.e. if you have E vs. x,y.z.f and f has 2 or more values, then the command
fails). Generally, it is easier to use visualize(E) and then select the vector plot option.
Syntax
Description
vectorplot(E);
Creates a vector plot of the dataset
See Also
Plotting commands 197 , plotxy 199 , legend 202 , image 202 , closeall 205 , setplot 204 ,
exportfigure 204 , plot 198
7.7
Adding Objects
The following commands can be used to add objects. Objects are always added to the
location specified by the groupscope variable. Please note that not all the commands are
available for all products. Please refer to the table at the bottom of the page for each
command to see which products it applies to.
206
Reference Guide
Simulation environment
Command
Description
switchtolayout 208
Closes the analysis window, deletes current

simulation data and allows you to manipulate
simulation objects for a new simulation.
layoutmode 209
Used to determine if the simulation file is open in

layout or in analysis mode.
groupscope 226
Changes the group scope.
addgroup 209
Adds a container group to the simulation

environment.
addanalysisgroup 210
Add an analysis group.
addobject 210
Add an object from the object library.
addgridattribute 220
Add a grid attribute object.
Structures
Command
Description
addcircle 211
Add a circle primitive.
addcustom 211
Add a custom primitive.
addimport 211
Add an import primitive.
addpyramid 212
Add a pyramid primitive.
addpoly 212
Add a polygon primitive
addrect 212
Add a rectangle primitive.
addring 213
Add a ring primitive.
addsphere 213
Add a sphere primitive.
addsurface 214
Add a surface primitive.
addstructuregroup 209
Add a structure group.
Simulation region
Command
Description
addfdtd 214
Add an FDTD simulation area.
addeigenmode 214
Adds a MODE simulation area.
Scripting Language
addpropagator 214
Adds a propagator simulation object to the MODE

Solutions simulation environment.
addmesh 215
Add a mesh override region.
adddevice 219
Adds a DEVICE simulation area.
Sources
Command
Description
adddipole 215
Add a dipole source.
addgaussian 216
Add a Gaussian source.
addplane 216
Add a plane source.
addmode 215 ; addmodesource 215
Add a mode source.
addtfsf 216
Add a TFSF source.
addimportedsource 217
Add an imported source.
Monitors
Command
Description
addindex 217
Add an index monitor.
addeffectiveindex 222
Add an effective index monitor.
addtime 217
Add a time monitor.
addmovie 218
Add a movie monitor.
addprofile 218
Add a profile monitor.
addpower
Add a power monitor.
addmodeexpansion 222
Add a mode expansion monitor.
Create objects in Deck

Command
Description
createbeam 218
Creates a new Gaussian beam that is accessible

from the deck.
Simulation environment
Command
Description
207
208
Reference Guide
switchtolayout 208
Closes the analysis window, deletes current

simulation data and allows you to manipulate
simulation objects for a new simulation.
switchtodesign
Switches INTERCONNECT to design mode.
layoutmode 209

design (layout) or in analysis mode.
designmode
Returns true if the simulation is currently in design

mode.
groupscope 226
Adding Elements
Command
Description
addelement 221
Adds an element from the INTERCONNECT element

library.
Adding simulation objects

Command
Description
adddope 219
Add a constant doping region.
addcustomdoping
Add a doping region with custom data.
adddiffusion 219
Add a diffusion region.
addbulkgen 220
Add a bulk generation region.
addimportdope 219
Add an import primitive for a doping region.
addimportgen 220
Add an import primitive for a generation region.
addcontact 210
Add a contact to the electrical contacts table.
7.7.1 switchtolayout
Closes the analysis window and allows you to manipulate simulation objects for a new
simulation. If a simulation file is open in ANALYSIS mode, any commands to modify
objects will return errors. You must switch to LAYOUT mode before modifying any objects.
Syntax
Description
switchtolayout;
Switches to LAYOUT mode.

Scripting Language
209
See Also
Adding Objects 205 , layoutmode 209
7.7.2 layoutmode
Used to determine if the simulation file is open in layout or in analysis mode.
Syntax
Description
?layoutmode;
Returns 1 if in layout mode, and 0 if in analysis mode.
See Also
Adding Objects 205 , switchtolayout 208 , designmode
7.7.3 addgroup
Adds a container group to the simulation environment. This command is not available in
INTERCONNECT.
Syntax
Description
addgroup;
Adds a container group to the simulation environment.

See Also
Adding Objects 205 , addtogroup 230 , addstructuregroup 209 , addanalysisgroup 210
7.7.4 addstructuregroup
Adds a structure group to the simulation environment. This command is not available in
INTERCONNECT.
Syntax
Description
addstructuregroup;
Adds a structure group to the simulation environment.

See Also
Adding Objects 205 , addtogroup 230 , adduserprop 231 , addgroup 209 , addanalysisgroup 210
210
Reference Guide
7.7.5 addanalysisgroup
Adds an analysis group to the simulation environment. This command is not available in
INTERCONNECT.
Note: It is not currently possible to add user defined Analysis Parameters or Results from a
script.
Syntax
Description
addanalysisgroup;
Adds an analysis group to the simulation environment.

See Also
Adding Objects 205 , addtogroup 230 , adduserprop 231 , addgroup 209 , addstructuregroup 209
7.7.6 addobject
Adds a object from the object library.
This command is available in FDTD and MODE Solutions.
Syntax
Description
addobject("script_ID");
Adds an object from the object library.

?addobject;
Returns names of objects in the library.
See Also
Adding Objects 205 , addtogroup 230 , adduserprop 231
7.7.7 addcontact
Adds a new contact to the electrical contact table. This command is available in DEVICE
only.
Syntax
Description
addcontact;
Adds a new contact to the electrical contact table.

See Also
Adding Objects 205
Scripting Language
211
7.7.8 addcircle
Adds a circle primitive to the simulation environment. This command is not available in
INTERCONNECT.
Syntax
Description
addcircle;
Adds primitive to the simulation environment.

See Also
Adding Objects 205
7.7.9 addcustom
Adds a custom primitive to the simulation environment. This command is available in FDTD
and MODE.
Syntax
Description
addcustom;

See Also
Adding Objects 205
7.7.10 addimport
Adds an import primitive to the simulation environment. This command is available in FDTD
and MODE.
Syntax
Description
addimport;

See Also
Adding Objects 205
212
Reference Guide
7.7.11 addpyramid
Adds a pyramid primitive to the simulation environment. This command is not available in
INTERCONNECT.
Syntax
Description
addpyramid;

See Also
Adding Objects 205
7.7.12 addpoly
Adds a polygon primitive to the simulation environment. This command is not available in
INTERCONNECT.
Syntax
Description
addpoly;

See Also
Adding Objects 205
7.7.13 addrect
Adds a rectangle primitive to the simulation environment.This command is not available in
INTERCONNECT.
Syntax
Description
addrect;

See Also
Adding Objects 205
Scripting Language
7.7.14 addtriangle
Adds a 3 vertex, triangle shaped polygon primitive to the simulation environment. This
command is not available in INTERCONNECT.
Syntax
Description
addtriangle;

See Also
Adding Objects 205 , addpoly 212
7.7.15 addring
Adds a ring primitive to the simulation environment. This command is not available in
INTERCONNECT.
Syntax
Description
addring;

See Also
Adding Objects 205
7.7.16 addsphere
Adds a sphere primitive to the simulation environment. This command is not available in
INTERCONNECT.
Syntax
Description
addsphere;

See Also
Adding Objects 205
213
214
Reference Guide
7.7.17 addsurface
Adds a surface primitive to the simulation environment. This command is available in FDTD
and MODE.
Syntax
Description
addsurface;

See Also
Adding Objects 205
7.7.18 addfdtd
Adds a FDTD simulation area to the simulation environment. This command is available in
FDTD and MODE.
Syntax
Description
addfdtd;
Adds a simulation area to the simulation environment.

See Also
Adding Objects 205
7.7.19 addeigenmode
Adds an eigenmode simulation object to the MODE Solutions simulation environment. This
command is available in MODE only.
Syntax
Description
addeigenmode;
Add an eigenmode mode simulation region.
See Also
Adding Objects 205
7.7.20 addpropagator
Adds a propagator simulation object to the MODE Solutions simulation environment. This
command is available in MODE only.
Syntax
Description
Scripting Language
addpropagator;
215
Add a propagator mode simulation region.
See Also
Adding Objects 205
7.7.21 addmesh
Adds a mesh override region to the simulation environment. This command is available in
FDTD and MODE.
Syntax
Description
addmesh;
Adds a mesh override region to the simulation environment.

See Also
Adding Objects 205
7.7.22 addmode
7.7.23 addmodesource
Adds a mode source to the simulation environment. This command is available in MODE
only.
Syntax
Description
addmodesource;
Adds source to the simulation environment.

See Also
Adding Objects 205 , addmode 215 , updatesourcemode 251
7.7.24 adddipole
Adds a dipole source to the simulation environment. This command is available in FDTD
and MODE.
Syntax
Description
adddipole;

216
Reference Guide
See Also
Adding Objects 205
7.7.25 addgaussian
Adds a gaussian source to the simulation environment. This command is available in FDTD
and MODE.
Syntax
Description
addgaussian;

See Also
Adding Objects 205
7.7.26 addplane
Adds a plane wave source to the simulation environment. This command is available in
FDTD and MODE.
Syntax
Description
addplane;

See Also
Adding Objects 205
7.7.27 addtfsf
Adds a Total Field Scattered Field (tfsf) source to the simulation environment. This
command is available in FDTD and MODE.
Syntax
Description
addtfsf;

See Also
Adding Objects 205
Scripting Language
217
7.7.28 addimportedsource
Adds an imported source to the simulation environment. This command is available in
FDTD only.
Syntax
Description
addimportedsource;

See Also
Adding Objects 205 , asapimport 124 , asapload 124 , asapexport 123
7.7.29 addindex
Adds an index monitor to the simulation environment. This command is available in FDTD
and MODE.
Syntax
Description
addindex;
Adds monitor to the simulation environment.

See Also
Adding Objects 205
7.7.30 addtime
Adds a time monitor to the simulation environment. This command is available in FDTD and
MODE.
Syntax
Description
addtime;

See Also
Adding Objects 205
218
Reference Guide
7.7.31 addmovie
Adds a movie monitor to the simulation environment. This command is available in FDTD
and MODE.
Syntax
Description
addmovie;

See Also
Adding Objects 205
7.7.32 addprofile
Adds a profile monitor to the simulation environment. This command is available in FDTD
and MODE.
Syntax
Description
addprofile;

See Also
Adding Objects 205
7.7.33 createbeam
Creates a new Gaussian beam that is accessible from the deck. This command is available
in MODE only.
Syntax
Description
createbeam;
Creates a Gaussian beam in the deck/global workspace.

The Gaussian beam has the properties specified in the
Overlap analysis->Beam tab of the analysis window
Returns the name of the Gaussian beam created, which is
by default "gaussian#" (# being the total number of
Gaussian beams existing in the current deck).
See Also
Adding Objects 205
Scripting Language
219
7.7.34 adddevice
Adds a Device simulation region to the simulation environment. This command is only
available in DEVICE.
Syntax
Description
adddevice;
Add a device simulation region.
See Also
Adding Objects 205
7.7.35 adddope
Adds a region with constant doping to the simulation environment. This command is only
Syntax
Description
adddope;
Add a constant doping region.
See Also
Adding Objects 205
7.7.36 adddiffusion
Adds a diffusion region to the simulation environment. This command is only available in
DEVICE.
Syntax
Description
adddiffusion;
Add a diffusion region.
See Also
Adding Objects 205
7.7.37 addimportdope
Adds a doping region to the simulation environment where the doping profile has been or
will be imported into DEVICE. This command is only available in DEVICE.
Syntax
Description
addimportdope;
Add an import primitive to define a doping region.
220
Reference Guide
See Also
Adding Objects 205
7.7.38 addbulkgen
Adds a bulk generation region to the simulation environment. This command is only
Syntax
Description
addbulkgen;
Add a bulk generation region.
See Also
Adding Objects 205
7.7.39 addimportgen
Adds a generation region to the simulation environment where the generation profile has
been imported into DEVICE. This command is only available in DEVICE.
Syntax
Description
addimportgen;
Add an import primitive to define a generation region.
See Also
Adding Objects 205
7.7.40 addgridattribute
Adds a grid attribute object to the simulation environment. See the Reference Guide
Attributes page for more information. This command is only available in FDTD.
Syntax
Description
addgridattribute(type);
Adds a grid attribute object to the simulation.

type: Type of attribute to add. Options are "lc
orientation", "permittivity rotation", or "matrix transform".
addgridattribute(type,value,x, Adds a grid attribute with spatially varying data.

y,z);
type: Type of attribute to add. Options are "lc
orientation", "permittivity rotation", or "matrix transform".
value: the attribute value. Depending on the attribute
type, the value may be a scalar number (i.e.
concentration), a 3 element vector (i.e. orientation), 9
element tensor, etc. The size of the value matrix should
Scripting Language
221
be Nx X Ny X Nz X M , where Nx, Ny, Nz are the sizes

of the position vectors, and M is the size of the attribute
value (scalar, vector, tensors, etc).
x,y,z: Vectors that specify the position where the
attribute values are specified.
Example
The following script is an excerpt from LCD_twist.lsf in the Twisted Nematic LCD
application example which defines a spatially varying liquid crystal.
# define x/y/z
x = 0;
y = 0;
z = linspace(0e-6,5e-6,100);
X
Y
Z
n
=
=
=
=
meshgrid3dx(x,y,z);
meshgrid3dy(x,y,z);
meshgrid3dz(x,y,z);
matrix(length(x),length(y),length(z),3);
# define the orientation function

n(1:length(x),1:length(y),1:length(z),1) = cos(Z*pi*1e5);
n(1:length(x),1:length(y),1:length(z),2) = sin(Z*pi*1e5);
n(1:length(x),1:length(y),1:length(z),3) = Z;
# add LC import grid attribute
addgridattribute("lc orientation",n,x,y,z-2.5e-6); # center at
z=0
setnamed("LC attribute","nz",50); # set resolution
See Also
Adding Objects 205
7.7.41 addelement
Adds an element from the INTERCONNECT element library to the simulation environment.
This command is only available in INTERCONNECT.
Syntax
Description
addelement("element");
Adds an element from the element library.

If no element name is given, this command will add a
compound element by default.
222
Reference Guide
7.7.42 addmodeexpansion
Adds a mode expansion monitor to the simulation environment. This command is available
in FDTD and MODE.
Syntax
Description
addmodeexpansion;
Adds a mode expansion monitor to the simulation

environment.
See Also
Adding Objects 205 , Using Mode Expansion Monitors, setexpansion 262 , removeexpansion
263
7.7.43 addeffectiveindex
Adds an effective index monitor to the simulation environment. This command is only
available in MODE Solutions.
Syntax
Description
addindex;
Adds an effective index monitor to the simulation

environment.
See Also
Adding Objects 205
7.7.44 addchargemonitor
Adds a charge monitor to the simulation environment. This command is ONLY available in
DEVICE.
Syntax
Description
addchargemonitor;
Adds a charge monitor to the simulation environment.
See Also
Adding Objects 205 , addpower, addfieldmonitor 223
Scripting Language
223
7.7.45 addfieldmonitor
Adds a charge monitor to the simulation environment. This command is ONLY available in
DEVICE.
Syntax
Description
addfieldmonitor;
Adds a field monitor to the simulation environment.
See Also
Adding Objects 205 , addpower, addchargemonitor 222
7.8
Manipulating objects
Physical structures, sources, monitors, and the simulation volume itself are considered
objects. Objects generally have properties that can be modified.
Selecting and deleting objects
Command
Description
groupscope 226
deleteall 226
Deletes all objects in the current group scope.
delete 227
Deletes the selected objects.
selectall 227
Selects all objects in the current group scope.
unselectall 227
Unselect all objects.
select 227
Selects objects with a given name in the current

group scope.
selectpartial 228
Selects any objects where partialname can be found

in the name, in the current TAB.
shiftselect 228
The same as select("name"); but does not unselect

currently selected objects. Can be used to select
multiple objects.
shiftselectpartial 229
The same as selectpartial("partialname"); but does

not unselect currently selected objects. Can be used
to select multiple objects.
Moving and copying objects

Command
Description
224
Reference Guide
flipelement 229
Flips an element in the schematic editor.
rotateelement 229
Rotates and element in the schematic editor.
move 229
Move an object.
copy 230
Copy an object.
addtogroup 230
Add an object/objects into a group.
Object properties
Command
Description
adduserprop 231
Add a user property to a structure group.
set 231
Set a property of selected objects.
setnamed 232
Set a property of any objects with a given name.
setcontact
Set a property of an electrical contact.
setglobalmonitor 232
Set global monitor properties.
setglobalsource 233
Set global source properties.
setmodes 233
Set mode labels.
setposition 233
Set an element's vertical and horizontal positions.
setrectangle 234
Set width and height of an element rectangle.
setactivesolver 263
Set the specified solver as the active solver
runsetup 235
Force group setup scripts to run.
get 235
Get a property of selected objects.
getcontact
Get a property of an electrical contact.
getnumber 236
Get the number of selected objects.
getnamed 236
Get a property of any objects with a given name.
getnamednumber 237
Get the number of objects with a given name.
getglobalmonitor 237
Get global monitor properties.
getglobalsource 237
Get global source properties.
getposition 234
Get current horizontal or vertical position of an

element.
getrectangle 234
Get the width or height of an element rectangle.
Scripting Language
225
haveproperty 238
Returns the number of selected objects with a

particular property.
importsurface 238
Import surface data from a file. Only applies to import

primitives.
importsurface2 240
Import surface data from script variables. Only

applies to import primitives.
importnk 241
Import n and k data from a file. Only applies to import

primitives.
importdoping
Import data from Tecplot formatted file (text)
importnk2 243
Import n and k data from script variables. Only

applies to import primitives.
setsourcesignal 252
Set a custom source time signal.
updatesourcemode 251
Updates the mode for a mode source.
clearsourcedata 254
Clears source data for an imported source, or the

selected mode for a mode source.
setexpansion 262
Associates a DFT monitor with a mode expansion

monitor.
removeexpansion 263
Removes a DFT monitor from a mode expansion

monitor.
getname 263
Returns the dataset name of the variable selected.
setname 263
Sets the dataset name of the variable selected.
importdataset 264
Imports an unstructured dataset named 'charge' to an

'eh Density' grid attribute.
cleardataset 264
Clear the dataset from any current grid attribute.
Controlling the view

Command
Description
redraw 256
Redraw graphics.
redrawoff 257
Turn automatic redraw off.
redrawon 257
Turn automatic redraw on.
redrawmode 257
Get the current status of automatic redrawing; turn it

off or on
226
Reference Guide
setview 258
Control how the graphics are drawn in the Layout

Editor
getview 259
Get the current view control properties from the

Layout Editor.
orbit 259
A built in function to do an orbit of the perspective

view with option of creating a movie.
framerate 260
Measure graphics performance of your computer.
Undo and redo commands

Command
Description
undo 260
Undo last modify object command.
redo 260
Redo command after an undo.
7.8.1 groupscope
Changes the group scope. Script commands that add or modify simulation object use the
groupscope property to know where to act within the object tree. For example, if you want
to delete everything within a particular group, set the groupscope to that group (i.e. ::
model::my_group). If you want to delete all objects in the simulation, set the group scope
the root level (i.e. ::model).
Syntax
Description
?groupscope;
returns the current group scope
groupscope("group_name");
changes the group scope
See Also
Manipulating objects 223 , delete 227 , selectall 227 , select 227
7.8.2 deleteall
Syntax
Description
deleteall;

See Also
Manipulating objects 223 , groupscope 226
Scripting Language
227
7.8.3 delete
Deletes selected objects.
Syntax
Description
delete;
Deletes selected objects.

See Also
7.8.4 selectall
Syntax
Description
selectall;

See Also
7.8.5 unselectall
Unselect all objects and groups.
Syntax
Description
unselectall;
Unselects all objects and groups.

See Also
7.8.6 select
Selects objects with a given name in the current group scope. A failed select command will
have the same result as the unselectall command.
Syntax
Description
select("name");
Selects objects with the name "name" in the current group

scope.
228
Reference Guide
select("group name::name"); Selects all objects with the name "name" located in the
group named "group name". The group named "group
name" must be in the current group scope.
See Also
Manipulating objects 223 , groupscope 226 , unselectall 227
7.8.7 selectpartial
Selects any objects with a given partial name, in the current TAB.
Syntax
Description
selectpartial("partialname");
Selects any objects where "partialname" can be found in

the object name provided the object is not in a group. To
select objects located in groups see the command below.
selectpartial
("partialgroupname::
partialname");
Selects any objects where "partialgroupname" can be

found in the group name and "partialname" can be found in
the object name.
See Also
7.8.8 shiftselect
Same as select, but does not unselect other currently selected objects. Note that only
objects from the same "group" can be selected simultaneously.
Syntax
Description
shiftselect("name");
The same as select("name"), but does not unselect

currently selected objects. Can be used to select multiple
objects.
shiftselect("group name::
name");
The same as select("groupname::name"), but does not

unselect currently selected objects.
See Also
Scripting Language
229
7.8.9 shiftselectpartial
Same as selectpartial, but does not unselect other currently selected objects.
Syntax
Description
shiftselectpartial
("partialname");
The same as selectpartial("partialname"), but does not

unselect currently selected objects. Can be used to select
multiple objects.
shiftselectpartial
("partialgroupname::
partialname");
The same as selectpartial("partialgroupname::partialname")

, but does not unselect currently selected objects. Can be
used to select multiple objects.
See Also
7.8.10 flipelement
Flip element in the schematic editor. This command is only available in INTERCONNECT.
Syntax
Description
flipelement("element");
Flips element in the schematic editor.
See Also
Manipulating objects 223 , rotateelement 229
7.8.11 rotateelement
Flip element in the schematic editor. This command is only available in INTERCONNECT.
Syntax
Description
rotateelement("element");
Rotates element in the schematic editor.
See Also
Manipulating objects 223 , flipelement 229
7.8.12 move
Move selected objects.
Syntax
Description
230
Reference Guide
move(dx);
In 2D or 3D, move by dx
move(dx,dy);
In 2D or 3D, move by dx and dy.

move(dx,dy,dz);
In 3D, move by dx, dy, and dz.

In 2D, dz will be ignored.
See Also
Manipulating objects 223 , copy 230 , select 227
7.8.13 copy
Create a copy of the selected objects. The copied objects will typically be identical (same
name, position, etc). For some objects that must have a unique name, '_1' will be
appended to the name.
Syntax
Description
copy;
Copy the selected objects.
copy(dx);
Same as copy; but with a specified move of dx.
copy(dx,dy);
Same as copy; but with a specified move of dx, dy.
copy(dx,dy,dz);
Same as copy; but with a specified move of dx, dy, dz.
See Also
Manipulating objects 223 , move 229 , select 227 , cp (copy files) 115 , copytoclipboard 127
7.8.14 addtogroup
Add selected objects to a group. This command is not available in INTERCONNECT.
Syntax
Description
addtogroup("group name");
Adds selected object(s) to a group. If a group with name

"group name" already exists, then the objects are added to
the existing group. Otherwise, a group named "group
name" is created.
See Also
Manipulating objects 223 , addgroup 209 , addstructuregroup 209 , addanalysisgroup 210 ,
adduserprop 231 , runsetup 235
Scripting Language
231
7.8.15 adduserprop
Adds a user defined custom property to the Setup user defined Structure and Analysis
groups. This command is not available in INTERCONNECT.
Syntax
Description
adduserprop("property
name", type, value);
Adds a user property to a selected structure group. The

name is set to "property name". The type is an integer
from 0 to 5. The corresponding variable types are
0 number
1 text
2 length
3 time
4 frequency
5 material
The value of the user property is set to value.
See Also
Manipulating objects 223 , addstructuregroup 209 , runsetup 235
7.8.16 set
Set a property of currently selected objects. This command will return an error in analysis
mode.
Syntax
Description
?set;
Returns a list of the properties of the selected object(s).
set("property",value);
This will set the properties of a currently selected object,

including pull-downs and check boxes. It cannot be used
to set the value of a selected object in a group.
Value can be a number or string. This function does not
return any data.
set("property",value,i);
This form can be used to set the property of the ith

selected object when multiple objects are selected. It
cannot be used to set the value of a selected object in a
group.
The objects are ordered by their location in the object tree.
The uppermost selected object is given the index 1, and
the index numbers increase as you go down the tree.
See Also
232
Reference Guide
Manipulating objects 223 , get 235 , setnamed 232 , setmaterial 277 , addmaterial 276 ,
haveproperty 238 , runsetup 235 , runanalysis 270
7.8.17 setnamed
Like the set command, except that the object name must be specified. This command will
return an error in analysis mode.
Syntax
Description
?setnamed("name");
Returns a list of the properties of the objects called name.
setnamed("name",
"property", value);
The same as set, but acts on objects with a specific

name, instead of selected objects.
setnamed("name",
"property", value,i);
This form can be used to set the property of the ith named
object when multiple objects have the same name.
setnamed("groupname::
name", "property", value);
The same as set, but acts on objects within the group

named "groupname" that are named "name", instead of
selected objects.
setnamed("groupname::
name", "property", value,i);
This form can be used to set the property of the ith object
with the name "name" in the group "groupname" when
multiple objects have the same name.
See Also
Manipulating objects 223 , set 231 , get 235 , getnamed 236 , getnamednumber 237
7.8.18 setglobalmonitor
Set global monitor properties. This command will return an error in analysis mode. This
Syntax
Description
?setglobalmonitor;
Returns a list of the global monitor properties
setglobalmonitor("property",
value);
Set the global monitor property named "property" to a

value.
Scripting Language
233
See Also
Manipulating objects 223 , set 231 , getglobalmonitor 237 , setglobalsource 233 , getglobalsource
237
7.8.19 setglobalsource
Set global source properties. This command will return an error in analysis mode. This
Syntax
Description
?setglobalsource;
Returns a list of the global source properties
setglobalsource("property",
value);
Set the global source property named "property" to a value.

See Also
Manipulating objects 223 , set 231 , setglobalmonitor 232 , getglobalmonitor 237 ,
getglobalsource 237
7.8.20 setmodes
Set mode labels. This command is only available in INTERCONNECT.
Syntax
Description
setmodes (TE,TM);
Set a list of comma separated mode labels that will share

the same s-parameters. Orthogonal identifies are
associated to each mode from 1 to number of modes.
See Also
7.8.21 setposition
Set horizontal and vertical positions of an element. This command is only available in
INTERCONNECT.
Syntax
Description
setposition("element",x,y);
Set an element vertical and horizontal positions.
See Also
Manipulating objects 223 , getposition 234 , setrectangle 234
234
Reference Guide
7.8.22 setrectangle
Set the width or height of an element rectangle. This command is only available in
INTERCONNECT.
Syntax
Description
setrectangle ("element",w,h); Sets the width (w) and height (h) of an element rectangle.
See Also
Manipulating objects 223 , getrectangle 234 , setposition 233
7.8.23 getposition
Get the current horizontal or vertical position of an element. This command is only available
in INTERCONNECT.
Syntax
Description
out=getposition
("element",x);
Returns the current horizontal position of an element.
out=getposition
("element",y);
Returns the current vertical position of an element.
See Also
Manipulating objects 223 , setposition 233 , getrectangle 234
7.8.24 getrectangle
Get the width or height of an element rectangle. This command is only available in
INTERCONNECT.
Syntax
Description
out=getrectangle
("element",w);
Returns the width of an element rectangle.
out=getrectangle
("element",h);
Returns the height of an element rectangle.
See Also
Manipulating objects 223 , setrectangle 234 , getposition 234
Scripting Language
235
7.8.25 get
Get a property from selected objects. The property names for the get command are the
same as the property names in the Edit dialogue box. For example, if you see a property
called "mesh accuracy", then you can use the command get("mesh accuracy"); to get that
property. It is possible to get numeric, string, drop down and checkbox properties.
Syntax
Description
?get;
Returns a list of the properties of the selected object(s).
out = get("property");
Gets the requested property value from the currently

selected object. It cannot be used to get the property value
of a selected object in a group.
If multiple objects are selected get("property") is the same
as get("property",i), where i is the number of the first
selected objects with the requested property.
Out can be a matrix or a string, depending on the property
requested.
get("property",i);
Gets the property of the ith selected object. Use this to act
on a series of objects. It cannot be used to get the value of
a selected object in a group.
See Also
Manipulating objects 223 , getnumber 236 , getnamed 236 , getnamednumber 237 , set 231 ,
haveproperty 238 , runsetup 235
7.8.26 runsetup
Runsetup forces the setup scripts of structure and analysis groups to run.
In most cases, it is not necessary to use this function, as group setup scripts
automatically re-run at the end of script, if the object has been modified. It is only
necessary to use this function when you need to force the setup script to run before the
end of your script file.
Syntax
Description
runsetup;
Forces setup scripts of groups to run.
See Also
236
Reference Guide
Manipulating objects 223 , get 235 , set 231 , runanalysis 270
7.8.27 getnumber
Get the number of objects that are selected.
Syntax
Description
out = getnumber;
Returns the number of objects that are selected;
See Also
Manipulating objects 223 , get 235 , getnamed 236 , getnamednumber 237 , set 231
7.8.28 getnamed
Get a property from objects with a given name.
If multiple objects are selected, and the values are different, the smallest value is returned.
To be certain of the results, be sure that only one object is selected, or use the form of
getnamed that allows a specific object to be selected.
Syntax
Description
?getnamed("name");
Returns a list of the properties of the objects called name.
out = getnamed("name",
"property");
The same as get, but acts on objects with a specific

name, instead of selected objects.
out=getnamed("name",
"property", i);
Gets the property of the ith named object. Use this to act
on a series of objects.
out = getnamed
("groupname::name",
"property");
The same as get, but acts on objects named "name"

located in the group "groupname", instead of selected
objects.
out = getnamed
("groupname::name",
"property");
Gets the property of the ith object named "name" located

in the group "groupname". Use this to act on a series of
objects.
See Also
Scripting Language
237
Manipulating objects 223 , get 235 , getnumber 236 , getnamednumber 237 , set 231 , setnamed
232
7.8.29 getnamednumber
Get the number of objects with a given name.
Syntax
Description
out = getnamednumber
( "name");
The same as getnumber, but acts on objects with a

specific name, instead of selected objects.
out = getnamednumber
( "groupname::name");
The same as getnumber, but acts on all objects named

"name" in the group "groupname", instead of selected
objects.
See Also
Manipulating objects 223 , get 235 , getnamed 236 , getnumber 236 , set 231 , setnamed 232
7.8.30 getglobalmonitor
Syntax
Description
?getglobalmonitor;
Returns a list of the global monitor properties
?getglobalmonitor
("property");
Returns the value of the requested property.
See Also
Manipulating objects 223 , get 235 , setglobalmonitor 232 , setglobalsource 233 , getglobalsource
237
7.8.31 getglobalsource
Syntax
Description
?getglobalsource;
Returns a list of the global source properties
?getglobalsource("property"); Returns the value of the requested property.
238
Reference Guide
See Also
Manipulating objects 223 , get 235 , setglobalmonitor 232 , getglobalmonitor 237 ,
setglobalsource 233
7.8.32 getsolver
Returns the solver that is currently active. This command is only available in MODE.
Syntax
Description
?getsolver;
Returns the solver that is currently active.
7.8.33 haveproperty
Returns the number of selected objects with a particular property. This command is not
available in INTERCONNECT.
Syntax
Description
out = haveproperty
("property");
Returns the number of selected objects with the specified

property.
See Also
Manipulating objects 223 , get 235 , set 231
7.8.34 importsurface
Import surface data. This command only applies to import primitives. The function returns 1
if the data is successfully imported. Example script files showing how to use these
functions can be found in the Online Help. See the User Guide, Structures section. This
Note: Non-uniform sampling of imported data
The import object is primarily intended to load data that is sampled on a uniform mesh. It
is also capable of importing non-uniformly sampled data, but with some limitations. The
main limitation is that within the simulation file (.fsp or .lms) the import surface object
always stores the data on a uniform mesh. When non-uniform data is imported, that data
is interpolated onto a uniform mesh during at import time. The size of the new
interpolated uniform grid will be the greater of: a) the smallest grid size in the original
data or, b) a grid size that results in 4 times the original number of sample points. The
second condition is intended to prevent the size of the interpolated surface data matrix
from becoming extremely large in cases where the mesh is highly graded. If you are
concerned about the possibility of interpolation errors, the best option is to interpolate the
data onto a uniform mesh yourself, then import the uniformly sampled data into the
Scripting Language
239
simulation.
It is worth remembering that the data stored within the import object will undergo a
second round of interpolation when it is interpolated onto the actual simulation mesh
coordinates used by the actual simulation engine.
Clearly, the behavior of this object with respect to non-uniformly sampled data could be
improved. Rather than forcing all data to be stored on a uniform mesh, it could simply
store the original non-uniform data, then apply more sophisticated interpolation when the
simulation engine is generating the final simulation mesh. If such an improvement is
important to you, please contact us at support@lumerical.com.
Syntax
Description
out = importsurface(filename,
upper_surface,file_units,x0,y0,z0,
invertXY);
Import a surface from the file in the string filename in

a three dimensional simulation. All arguments after
filename are optional.
out = importsurface(filename,
upper_surface,file_units,x0,y0,
invertXY);
Import a surface from the file in the string filename in

a two dimensional simulation. All arguments after
Parameter
filename
upper_surface
file_units
x0
Default value
Type
Description
required
string
name of the file with surface data

to import. May contain complete
path to file, or path relative to
current working directory
"m"
number This optional argument should be

1 to import the upper surface and
0 to import the lower surface.
string
The optional string argument

file_units can be "m", "cm, "mm",
"microns" or "nm" to specify the
units in the file.
number The optional arguments x0, y0 and

z0 specify the data origin in the
global coordinates of the Graphical
Layout Editor. For example, if you
are importing a surface defined by
an AFM that is on a slab of Si that
ranges from 0 to 2 microns, you
240
Reference Guide
should set z0 to 2 microns.
y0
number
z0
number
invertXY
number The optional argument invertXY

can be used to reverse how the x
and y axes are read from the file.
See Also
Manipulating objects 223 , importsurface2 240
7.8.35 importsurface2
Import surface data from script variables. This command only applies to import primitives.
The function returns 1 if the data is successfully imported. Example script files showing
how to use these functions can be found in the Online Help. See the User Guide,
Structures section. This command is available in FDTD and MODE.
simulation.
Scripting Language
241
Syntax
Description
out = importsurface2(Z,x,y,
upper_surface);
Import a surface from the variables Z, x and y in three

dimensional simulations. The upper_surface
argument is optional.
Parameter
Default value
Type
Description
required
matrix
The two dimensional matrix that

defines the surface.
required
matrix
If Z is an NxM matrix, then x

should have dimension Nx1. For
two dimensional simulation, if Y is
an Nx1 matrix then x should have
dimension Nx1.
required
matrix
If Z is an NxM matrix, then y

should have dimension Mx1.
upper_surface
required
number This optional argument should be

1 to import the upper surface and
0 to import the lower surface.
matrix
This argument should be an Nx1

matrix that defines the surface for
two dimensional simulations.
See Also
Manipulating objects 223 , importsurface 238
7.8.36 importnk
Import the refractive index (n and k) over an entire volume or surface from a file. This
command only applies to import primitives. The function returns 1 if the data is successfully
imported. Example script files showing how to use these functions can be found in the
Online Help. See the User Guide, Structures section. This command is available in FDTD
and MODE.
242
Reference Guide
simulation.
Syntax
Description
out = importnk(filename,file_units,
x0,y0,z0,reverse_index_order);
Import n (and k) data from filename in three

dimensional simulations. All arguments after the
out = importnk(filename,file_units,
x0,y0,reverse_index_order);
Import n and k data from filename in two dimensional

simulations. All arguments after the filename are
optional.
Parameter
Default value
Type
Description
filename
required
string
name of the file with n (and k) data

file_units
"m"
string

units in the file.
x0

defined your volume with respect
Scripting Language
243
to a particular point in space, for

example (0,0,-5) microns, then
you should set z0 to -5 microns.
y0
number
z0
number
reverse_index_order
number The optional argument

reverse_index_order can be set to
1 to reverse how the indices are
interpreted in the file. It is best to
verify the correct setting with a
graphical import before using the
script command.
See Also
Manipulating objects 223 , importnk2 243
7.8.37 importnk2
Import the refractive index (n and k) over an entire volume or surface from script variables.
This command only applies to import primitives. The function returns 1 if the data is
successfully imported. Example script files showing how to use these functions can be
found in the Online Help. See the User Guide, Structures section. This command is
available in FDTD and MODE.
simulation.
244
Reference Guide
Syntax
Description
out = importnk2(n,x,y,z);
Import n (and k) data from script variables in three

dimensional simulations. All arguments are required.
out = importnk2(n,x,y);
Import n (and k) data from script variables in two

Parameter
Default value
Type
Description
required
matrix
The refractive index. This should

be an NxMxP matrix in three
dimensions and an NxM matrix in
two dimensions. If it is complexvalued, then the imaginary part is
interpreted as k.
required
matrix
If n is an NxMxP matrix, then x

two dimensional simulation, if n is
an NxM matrix then x should have
dimension Nx1. Values of x must
be uniformly spaced.
required
matrix
If n is an NxMxP matrix, then y

should have dimension Mx1. For
an NxM matrix then y should have
dimension Mx1. Values of y must
number If n is an NxMxP matrix, then z

should have dimension Px1.
Values of z must be uniformly
spaced.
See Also
Manipulating objects 223 , importnk 241
Scripting Language
245
7.8.38 importnkobfuscated
This command is identical to importnk but makes it possible to import data from a file that
has been obfuscated. For details on how to obfuscate the data files, please see the Online
Help in the User Guide, Structures section. This command is available in FDTD Solutions
only, for versions 8.6.3 and higher.
simulation.
Syntax
Description
out =
Import n (and k) data from filename in three dimensional
importnkobfuscated simulations. All arguments after the filename are optional.
(key,filename,
file_units,x0,y0,z0,
reverse_index_order)
;
Parameter
key
Default value
Type
Description
required
string
The key that is used to decrypt

the obfuscated file.
246
Reference Guide
filename
required
string
name of the file with n (and k) data

file_units
"m"
string

units in the file.
x0

y0
number
z0
number
reverse_index_order

script command.
See Also
Manipulating objects 223 , importnk 241
7.8.39 importbinary
Import binary data (1s and 0s) over an entire volume from a file. The object will be present
wherever the binary data is 1 and not when it is 0. This command only applies to import
primitives. The function returns 1 if the data is successfully imported. Example script files
showing how to use these functions can be found in the Online Help. See the User Guide,
Structures section. This command is available in FDTD and MODE.
Scripting Language
247
simulation.
Syntax
Description
out = importbinary(filename,
reverse_index_order);
Import binary data from filename in three dimensional

simulations. All arguments after the filename are
optional.
Parameter
Default value
Type
Description
filename
required
string
name of the file with binary data to

import. May contain complete
file_units
"m"
string

units in the file.
x0

248
Reference Guide
y0
number
z0
number
reverse_index_order

script command.
See Also
Manipulating objects 223 , importbinary2 248
7.8.40 importbinary2
Import binary data (1s and 0s) over an entire volume from script variables. The object will be
present wherever the binary data is 1 and not when it is 0. This command only applies to
import primitives. The function returns 1 if the data is successfully imported. Example script
files showing how to use these functions can be found in the Online Help. See the User
Guide, Structures section. This command is available in FDTD and MODE.
simulation.
Scripting Language
249
Syntax
Description
out = importbinary2(binary,x,y,z);
Import binary data from script variables in three

Parameter
Default value
Type
Description
binary
required
matrix
The binary data This should be an

NxMxP matrix in three dimensions
and an NxM matrix in two
dimensions. It should have only
values of 0 or 1. If other values are
present, all non-zero values will be
interpreted as 1.
required
matrix
If n is an NxMxP matrix, then x

an NxM matrix then x should have
dimension Nx1. Values of x must
required
matrix
If n is an NxMxP matrix, then y

should have dimension Mx1. For
an NxM matrix then y should have
dimension Mx1. Values of y must
See Also
Manipulating objects 223 , importbinary 246
number If n is an NxMxP matrix, then z

should have dimension Px1.
Values of z must be uniformly
spaced.
250
Reference Guide
7.8.41 importbinaryobfuscated
This command is identical to importbinary but makes it possible to import data from a file
that has been obfuscated. For details on how to obfuscate the data files, please see the
Online Help in the User Guide, Structures section. This command is available in FDTD
Solutions only, for versions 8.6.3 and higher.
simulation.
Syntax
Description
out =
Import binary data from filename in three dimensional simulations.
importbinaryobfusca All arguments after the filename are optional.
ted(key,filename,
reverse_index_order
);
Parameter
key
Default value
Type
Description
required
string
The key that is used to decrypt

the obfuscated file.
Scripting Language
251
filename
required
string
name of the file with binary data to

import. May contain complete
file_units
"m"
string

units in the file.
x0

y0
number
z0
number
reverse_index_order

script command.
See Also
Manipulating objects 223 , importbinary 246
7.8.42 updatesourcemode
Updates the mode profile of selected mode source. If there is no mode profile stored in the
source, then the mode with the highest effective index will be selected. If a mode is
already stored in the source, then the mode with the best overlap with the old mode will be
selected. Note that the mode source must be selected before running this command. This
Syntax
Description
?updatesourcemode;
Updates mode profile of the selected Mode source.
252
Reference Guide
Returns the fraction of electromagnetic fields that
overlap between the old and the new mode
?updatesourcemode
(mode_number);
Updates the mode source and selects the desired

mode number. For example, updatesourcemode(1);
will calculate the fundamental mode. Please note that
making this call will force a recalculation of a mode,
even if the same mode has previously been calculated.
In addition, making this call will force the mode
selection method to become "user select". This
optional argument was introduced in FDTD Solutions
8.6.3 and MODE Solutions 6.5.3.
NOTE: Saving simulation files before using updatesourcemode

If you have a script file which updates the simulation mesh, then you should use the save
script command 113 before updating the source mode. This will ensure that the mesh has
been updated before the new mode is calculated.
NOTE: overlap
The fraction of electromagnetic fields that overlap between the two modes is given by the
expression below. It is also the fraction of power from mode2 that can propagate in
mode1. For more information, please see overlap script command.
overlap
Re
E1 H 2* dS
E1 H
E2
*
1
dS
H 1* dS
1
Re E 2
H 2* dS
See Also
Manipulating objects 223 , addmode 215 , clearsourcedata 254 , clearmodedata 254 , getresult
270 , overlap, expand 195 , seteigensolver 255 , geteigensolver 256
7.8.43 setsourcesignal
Sets a custom source time signal.
This is an advanced source setting for users wanting a custom source time signal. For the
vast majority of simulations, a custom time signal is not required. If this function is not
used, the time signal will be automatically generated. This command is available in FDTD
and MODE.
For an example script file which uses this script command, see Online User Guide>Sources->Custom time signal.
Scripting Language
253
Syntax
Description
setsourcesignal("name", t,
amplitude, phase);
Sets the time domain signal of source named "name". t,

amplitude, and phase are 1D vectors with the same length.
setsourcesignal("name", t,
amplitude, phase, fcentre,
bandwidth);
Allows you to specify the precise center frequency and

bandwidth that will be used for all simulations. These values
are used for materials fits, calculating the mesh, and source
limits.
If fcentre and bandwidth are not specified, they will be
automatically estimated from the time signal.
See Also
sourcepower
7.8.44 updatemodes
Updates the mode profile(s) of selected mode expansion monitor If there are no mode
profiles stored in the mode expansion monitor, then the mode with the highest effective
index will be selected. If mode profiles are already stored in the mode expansion monitor,
then the modes with the best overlap with the old modes will be selected. Note that the
mode expansion monitor must be selected before running this command. This command is
available in FDTD and MODE.
Syntax
Description
updatemodes;
Updates mode profile of the selected mode expansion

monitor.
Returns 1 if the update was successful and -1 if not.
updatemodes(mode_number);
Updates the mode expansion monitor and selects the

desired mode numbers. For example,
updatesourcemode(1:10); will calculate the 10 modes
with the highest refractive index. Please note that
making this call will force a recalculation of a modes,
even if the same modes have previously been
calculated. In addition, making this call will force the
mode selection method to become "user select". This
optional argument was introduced in FDTD Solutions
8.6.3 and MODE Solutions 6.5.3.
NOTE: Saving simulation files before using updatesourcemode

If you have a script file which updates the simulation mesh, then you should use the save
254
Reference Guide
script command 113 before updating the source mode. This will ensure that the mesh has
been updated before the new mode is calculated.
NOTE: overlap
The fraction of electromagnetic fields that overlap between the two modes is given by the
expression below. It is also the fraction of power from mode2 that can propagate in
mode1. For more information, please see overlap script command.
overlap
Re
E1 H 2* dS
E2
H 1* dS
E1 H 1* dS
1
Re E 2
H 2* dS
See Also
270 , overlap, expand 195 , seteigensolver 255 , geteigensolver 256
7.8.45 clearsourcedata
Clears source data for an imported source, or the selected mode for a mode source. This
Syntax
Description
clearsourcedata;
Clears source data for the selected source.
Example
Clear source data from an imported source. This will make the file much smaller, which
can be convenient when emailing simulation files.
select("source3");
clearsourcedata;
See Also
updatesourcemode 251 , asapimport 124 , asapload 124 , asapexport 123 , clearmodedata 254 ,
getresult 270 , overlap, expand 195 , seteigensolver 255 , geteigensolver 256
7.8.46 clearmodedata
Clears mode data for a mode expansion monitor This command is available in FDTD and
MODE, as of versions 8.6.3 and 6.5.3 respectively. This is mainly useful to reduce file
sizes when saving.
Scripting Language
255
Syntax
Description
clearmodedata;
Clears mode data for the selected mode expansion mnoitor.
See Also
updatesourcemode 251 , asapimport 124 , asapload 124 , asapexport 123 , clearsourcedata 254 ,
getresult 270 , overlap, expand 195 , seteigensolver 255 , geteigensolver 256
7.8.47 seteigensolver
Mode sources and mode expansion monitors in FDTD and MODE have embedded
eigensolvers. This script command makes it possible to set the properties of that
eigensolver without using the GUI.
Changing any values of the embedded eigensolver with this command will automatically
invalidate any existing mode data. This means that new updates based on overlap
calculations with previous modes will fail after using this command. Therefore please call
this command before making any calls to updatesourcemode or updatemodes.
Syntax
Description
?seteigensolver;
Returns a list of the properties of the embedded

eigensolver
seteigensolver("property",
value);
This will set the eigensolver properties of the currently

selected objects.
Value can be a number or string. This function does not
return any data.
Example
Change the radius of curvature for a mode expansion calculation, and calculate the first 10
modes which can be subsequently used for mode expansion.
select("mode_expansion");
seteigensolver("bent waveguide",true);
seteigensolver("bend radius",10e-6);
updatemodes(1:10);
See Also
270 , overlap, expand 195 , seteigensolver 255 , geteigensolver 256 , updatemodes 253 ,
256
Reference Guide
7.8.48 geteigensolver
Mode sources and mode expansion monitors in FDTD and MODE have embedded
eigensolvers. This script command makes it possible to get the properties of that
eigensolver without using the GUI.
Syntax
Description
?geteigensolver;
Returns a list of the properties of the embedded

eigensolver
geteigensolver("property");
This will get the eigensolver properties of the currently

selected objects. The returned value may be a number or a
string, depending on the property.
Example
Change the radius of curvature for a mode expansion calculation, and calculate the first 10
modes which can be subsequently used for mode expansion.
select("mode_expansion");
?geteigensolver("bent waveguide");
See Also
270 , overlap, expand 195 , seteigensolver 255 , geteigensolver 256 , updatemodes 253 ,
7.8.49 redraw
Force the graphical viewports of the CAD to update. The viewports update automatically by
default, so this command is only required after using the redrawoff command. This
Syntax
Description
redraw;
Redraws graphics.
Scripting Language
257
See Also
Manipulating objects 223 , redrawon 257 , redrawoff 257 , redrawmode 257
7.8.50 redrawoff
Disable automatic updating of the graphical viewports in the CAD. This can greatly
increase the speed of scripts that add large numbers of objects. This command is not
available in INTERCONNECT.
Syntax
Description
redrawoff;
Prevents redrawing of graphics.

Cannot use this command in group setup scripts since
redrawing is automatically turned off.
See Also
Manipulating objects 223 , redrawon 257 , redraw 256 , redrawmode 257
7.8.51 redrawon
Enable automatic updating of the graphical viewports in the CAD. Automatic updating is
the default behavior, so this command is only required after using the redrawoff command.
This command is not available in INTERCONNECT.
Syntax
Description
redrawon;
Turns redrawing back on.

See Also
Manipulating objects 223 , redraw 256 , redrawoff 257 , redrawmode 257
7.8.52 redrawmode
This command can be used to determine the current status of automatic redrawing. It can
also be used to set the current status of automatic redrawing. The graphics will be redrawn
after any script command that may change the properties of a graphical object. This
Syntax
Description
out = redrawmode;
The value of out indicates if automatic redrawing is off or on

out=1: automatic redrawing is on
out=0: automatic redrawing is off
258
Reference Guide
out = redrawmode(in);
Set the automatic redrawing off or on. To turn it on, use

in=1. To turn it off, use in=0. The value of out is set after
executing the command so that out=in once this command
has been executed.
See Also
Manipulating objects 223 , redraw 256 , redrawoff 257
7.8.53 setview
This command allows the viewing properties of the Layout Editor to be modified. This
Syntax
Description
outstring = setview;
Returns a list of the view properties that can be set. The

command
?setview;
will return
extent, zoom, theta, phi
setview("property");
Sets the default value for any of the view properties. For
example,
setview("extent");
is the same as pressing the graphical extent button.
setview("property",value);
Sets the values to of any property for viewing.
The following table describes the properties that can be set

Property
Description
extent
Control the view extent. In this case, value should be a

2x1, 4x1 or 6x1 matrix representing the view range min x,
max x, min y, max y, min z and max z respectively.
zoom
Controls the relative zoom of the perspective view

compared to the default level. To zoom in by a factor of 2 in
the perspective view, use
setview("zoom",2);
theta
Controls the polar angle of the perspective view, in

degrees.
phi
Controls the azimuthal angle of the perspective view, in

degrees.
Scripting Language
259
See Also
Manipulating objects 223 , getview 259 , orbit 259 , redraw 256
7.8.54 getview
This command allows the viewing properties of the Layout Editor to be retrieved. This
Syntax
Description
outstring = getview;
Returns a list of the view properties that can be set. The

command
?getview;
will return
extent, zoom, theta, phi
out = getview("property");
Returns the current value of any of the view properties. For

example,
zoom_level = getview("zoom");
will return the current zoom setting of the perspective view
relative to the default level.
The properties that can be obtained with getview are described in setview 258 .
See Also
Manipulating objects 223 , setview 258 , orbit 259 , redraw 256
7.8.55 orbit
This command performs an elliptical viewing orbit of the structure in the perspective view.
Note that the commands setview 258 , getview 259 and redraw 256 make it possible to create
any type of orbit you would like in your own script file. This command is not available in
INTERCONNECT.
Syntax
Description
orbit;
Performs an orbit of the current perspective view.
orbit(zoom_factor);
Performs an orbit with the specified minimum zoom

factor. By default the zoom factor is 1.5.
orbit(zoom_factor, frame_rate);
Performs an orbit with the specified frame rate

specified in frames per second. The default frame rate
is 15.
260
Reference Guide
orbit(zoom_factor, frame_rate,
"filename");
The orbit will be streamed to the mpeg file filename for

later viewing.
See Also
Manipulating objects 223 , setview 258 , getview 259 , framerate 260
7.8.56 framerate
Orbits the perspective view and returns the framerate. This can be useful for estimating your
graphics performance. If comparing the performance of two computers, be sure to use
exactly the same simulation file. This command is available in FDTD only.
Syntax
Description
fr = framerate(num_frames,
zoom);
num_frames - Number of frames to draw

zoom - Zoom factor used in perspective view
fr - number of frames / wall time required to complete
orbit.
See Also
Manipulating objects 223 , setview 258 , getview 259 , orbit 259
7.8.57 undo
Undo the last command that modified any objects, you can undo the last 5 commands.
Syntax
Description
undo;
Undo last modify object command.

See Also
Manipulating objects 223 , redo 260
7.8.58 redo
Redo a command after a previous undo.
Syntax
Description
redo;
Redo command after previous undo.

See Also
Scripting Language
261
Manipulating objects 223 , undo 260
7.8.59 addport
Add a port to a compound/script element. (Note that this command does not apply for
primitive elements.) This command is only available in INTERCONNECT.
Syntax
Description
addport("element", "port",
"type", "data");
Adds a new port to the element with the specified

properties.
Returns the name of the port that is created.
Property
Default
value
Type
Description
element
required
string
Name of the element to add a

port to.
port
required
string
Name of the port to add. The

named will be modified if there
is already a port of the same
name.
type
required
string
The type of port to add. The

options are: Bidirectional,
Input, Output, Analyzer Input
data
required
string
The type of data for the port.

The options are: Variant,
Optical Signal, Electrical
Signal, Digital Signal
Manipulating objects 223 , removeport 261
7.8.60 removeport
Remove a port from a compound/script element. (Note that this command does not apply
for primitive elements.) This command is only available in INTERCONNECT.
Syntax
Description
removeport("element",
"port");
Removes "port" from "element".

Returns 1 if the port is successfully removed, 0 otherwise.
262
Reference Guide
Manipulating objects 223 , addport 261
7.8.61 connect
Connects one element to another via the specified ports. This command is only available in
INTERCONNECT.
Syntax
Description
connect("element1", "port1", Connects "port1" of "element1" to "element2" or "port2".

"element2", "port2");
Manipulating objects 223 , disconnect 262
7.8.62 disconnect
Disconnect one element to another via the specified ports. This command is only available
in INTERCONNECT.
Syntax
Description
connect("element1", "port1", Deletes the connection between "port1" of "element1" and

"element2", "port2");
"port2" of "element2".
Manipulating objects 223 , connect 262
7.8.63 setexpansion
Associates a DFT monitor with a mode expansion monitor. This command is available in
FDTD and MODE.
Syntax
Description
?setexpansion;
List all monitors under the "Monitors for expansion" list for
the selected mode expansion monitor.
setexpansion("name",
"dft_monitor");
Adds the "dft_monitor" to the "Monitors for expansion" list

of the selected mode expansion monitor, with the specified
name.
addmodeexpansion 222 , removeexpansion 263 , Using Mode Expansion Monitors
Scripting Language
263
7.8.64 removeexpansion
Removes a DFT monitor from a mode expansion monitor. This command is available in
FDTD and MODE.
Syntax
Description
removeexpansion("name");
Removes the DFT monitor with the specified name from the
"Monitors for expansion" list of the selected mode
expansion monitor.
addmodeexpansion 222 , setexpansion 262 , Using Mode Expansion Monitors
7.8.65 setactivesolver
Set the specified solver as the active solver. For example, this can be used to toggle
between the Eigenmode solver and Propagator simulations in MODE Solutions. This
command is available only in MODE.
Syntax
Description
?setactivesolver;
Lists all the possible solver choices
setactivesolver
('solver_name');
Set the solver with the specified name as the active solver.
7.8.66 getname
The script command getname is used to get the name of a datset.
Syntax
Description
?getname(a);
Returns the name of the dataset of the variable a.
?a.getname;
See Also
setname 263
7.8.67 setname
The script command setname is used to set the name of a datset.
Syntax
Description
a.setname("test");
264
Reference Guide
See Also
getname 263
7.8.68 importdataset
This command can import charge density to a selected 'eh density' grid attribute. A file
contains an unstructured dataset called 'charge' with scaler attributes 'n' and 'p' can be
exported from DEVICE, for example Mach_Zehnder. The unstructured dataset 'charge' in
this file can be imported to the 'eh Density' grid attribute in FDTD, MODE or DEVICE, by
GUI or this command. This command is NOT available in INTERCONNECT.
Syntax
Description
importdataset("device_data.
mat")
Imports the unstructured dataset 'charge' in the file from

the current working directory.
importdataset(charge)
Implements 'charge' from the file that is already imported

by matlabload 125
Property
Description
device_data.mat
A Matlab formatted file, that contains data exported from

DEVICE
charge
Name of an unstructured data set
See Also
Manipulating objects 223 , cleardataset 264
7.8.69 cleardataset
This command clears the dataset from any current eh Density grid attribute. This is only
useful for keeping file size small.This command is ONLY available in MODE and DEVICE.
Syntax
Description
cleardataset;
clears the dataset from any current eh Density grid

attribute.
See Also
Manipulating objects 223 , importdataset 264
Scripting Language
7.9
265
Running simulations
Moving between tabs
Command
Description
switchtolayout 208
Closes the analysis window and allows you to

manipulate simulation objects for a new simulation.
layoutmode 209

layout or in analysis mode.
Running Simulations
Command
Description
run
Launch the simulation. (Options available)
runparallel 265
Launch the simulation in parallel mode.
addjob 266
Add a simulation to the job queue.
runjobs 266
Run all simulations in the job queue.
clearjobs 266
Remove all simulations from the job queue.
runsweep 267
Runs a parameter sweep or optimization task
Command
Description
run
Launch the simulation. (Options available)
runsweep 267
Runs a parameter sweep or optimization task
7.9.1 runparallel
Launch the simulation in parallel mode. Equivalent to run and run(3). When the simulation
finishes, all simulation data will be saved to the current file. This command has been
deprecated. Use run.
Syntax
Description
runparallel;
Launch the simulation in parallel mode as defined in the

resource manager. This function does not return any data.
See Also
run, runanalysis 270
266
Reference Guide
7.9.2 addjob
Adds a simulation file to the job manager queue. This command is not available in
INTERCONNECT.
Syntax
Description
addjob(filename);
Add the simulation file "filename" to the job manager

queue.
See Also
run, runsweep 267 , runjobs 266 , clearjobs 266 , currentfilename 117
7.9.3 runjobs
Run all simulations in the job manager queue. The script execution will be paused while
the jobs run, then resume when all of the simulations have complete successfully. If errors
occur, the script will not proceed. This command is not available in INTERCONNECT.
Syntax
Description
runjobs;
Run jobs in the Job queue. Use the computer resources

and parallel settings that are specified in the Resource
Manager.
runjobs(option);
option=0: run jobs in single process mode using only the

local computer.
option=1: run jobs using the computer resources and
parallel settings that are specified in the Resource
Manager. (default)
See Also
run, runsweep 267 , addjob 266 , clearjobs 266 , save 113 , load 113
7.9.4 clearjobs
Remove all jobs from the job manager queue. This command is not available in
INTERCONNECT.
Syntax
Description
clearjobs;
Remove all jobs from the Job queue.
See Also
run, addjob 266 , runjobs 266
Scripting Language
267
7.9.5 runsweep
Runs a parameter sweep or optimization task.
Syntax
Description
runsweep;
Runs all sweeps and optimization tasks.
runsweep("taskname");
Runs only the sweep or optimization named taskname.
See Also
run, getsweepdata 268 , addjob 266 , runjobs 266
7.10 Measurement and optimization data

The following commands are used to access data from simulation objects.
Most raw data is recorded in multi-dimensional form. For example, monitors in FDTD and
MODE Solutions typically return data in 4D matrices. The first three dimensions of the
matrix correspond to the spatial dimensions X, Y, Z. The 4th dimension corresponds to the
frequency or time dimension, depending on the type of monitor. For example, suppose you
have a FDTD Solutions simulation with a frequency monitor in the XY plane that records 20
frequency points. Assuming the monitor spans 100 mesh points in the x direction and 55
mesh points in the y direction, the size of the Ex field component data matrix will be
100x55x1x20. Notice that the 3rd dimension (corresponding to Z) has a size of 1, since
the monitor only recorded data at one Z position.
Command
Description
getresult 270
Get results from simulation objects.
getdata 269
Get raw data from simulation objects.
getelectric 274
Get raw |E|2 data matrix from monitor
getmagnetic 274
Get raw |H|2 data matrix from monitor
runanalysis 270
Runs the analysis script in analysis objects
clearanalysis 273
Clears d-card data obtained by running analysis

scripts.
havedata 271
Used to see if there is any available data stored

within an object.
haveresult 271
Used to see if there are any available results within

an object.
268
Reference Guide
read and write data to file 275
Read and write data to a file.
copydcard 273
Creates a copy of a d-card.
cleardcard 274
Clears a d-card.
Parameter sweep,optimization, and yield analysis data is saved with the simulation file and
is not cleared when switching the current simulation to layout mode. These results can be
accessed with the following commands:
Command
Description
getsweepdata 268
Gets raw data from parameter sweeps,

optimizations, and yield analysis.
getsweepresult 269
Gets results from parameter sweeps and

optimizations.
havesweepdata 272
Used to check if parameter sweep and optimizations

have data.
havesweepresult 272
Used to check if parameter sweep and optimizations

have results.
loadsweep 275
Loads previously generated sweep result
savesweep 275
Saves the generated sweep result
issweep
Checks if the simulation is in sweep mode.
7.10.1 getsweepdata
Gets raw data from a parameter sweep, optimization, or yield analysis. In most cases, it is
more convenient to a complete dataset with getsweepresult, rather than getting individual
data elements with getsweepdata.
Syntax
Description
?getsweepdata;
Returns names of all sweep, optimization, and yield

analysis objects.
?getsweepdata
("sweep_name");
Returns all the names of the available data which is stored

in the sweep, optimization, or yield analysis object.
out = getsweepdata
("sweep_name", "data");
Returns parameter sweep, optimization, or yield analysis

data.
The following data can be obtained from an optimization:
Scripting Language
269
fomTrend - Figure of merit as a function of generation

fomHistory - Figure of merit history (for each generation
there will be generation size number)
bestFom - Best figure of merit obtained during sweep
bestParameter - Parameter which corresponds to
bestFom
paramHistory - Parameter history
For a parameter sweep and yield analysis, this command
returns both parameters and results.
See Also
getdata 269 , runsweep 267 , havesweepdata 272 , savedata 121 , getsweepresult 269 , savesweep
275 , loadsweep 275
7.10.2 getsweepresult
Get parameter sweep or optimization results in the form of a dataset.
Syntax
Description
?getsweepresult;
Returns names of all sweep or optimization objects with

available results.
?getsweepresult
("sweep_name");
Returns names of the available results from the sweep or

optimization task.
out = getsweepresult
("sweep_name", "result");
Returns parameter sweep or optimization dataset.
See Also
Dataset introduction 141 , runsweep 267 , havesweepresult 272 , getresult 270 , savedata 121 ,
getsweepdata 268 , savesweep 275 , loadsweep 275
7.10.3 getdata
Get data from the simulation. Remember to run the simulation before using getdata.
Syntax
Description
?getdata;
Returns names of all objects with data.
?getdata("monitor")
Returns list of of results within the simulation object.
?getdata( "monitor",
"result");
Returns list of of data within the simulation object result.
270
Reference Guide
out = getdata( "monitor",
"result", "dataname");
Gets the simulation data.
See Also
Measurements 267 , havedata 271 , getsweepdata 268
7.10.4 getresult
Get results from simulation objects. Results will be returned as datasets.
Syntax
Description
?getresult("monitor_name");
Returns the names of all the results for the monitor. All the
dataset and scalar matrix results will be returned in this
case.
R = getresult("monitor_name Returns the result T from the monitor. T is a dataset.

","T");
See Also
Measurements 267 , haveresult 271 , Dataset introduction 141 , "." operator 168 , visualize 203 ,
getdata 269 , rectilineardataset 139 , matrixdataset 139 , getattribute 141 , addattribute 140 ,
splitstring 178
7.10.5 runanalysis
Runs the analysis script in analysis objects.
Note: Scripts that already have data are not re-run; to re-run a script, first clear data using
clearanalysis.
Syntax
Description
runanalysis;
Runs the analysis scripts in all analysis objects in the

simulation file.
runanalysis("group name");
Runs the analysis script in the analysis object named

"group name".
See Also
Scripting Language
271
run, getdata 269 , getresult 270 , havedata 271 , clearanalysis 273 , runsetup 235
7.10.6 havedata
Used to see a simulation object (such as a monitor) has any data. This command is very
similar to haveresult, but is intended to be used with the getdata command, rather than
getresult. This command is not available in INTERCONNECT.
Syntax
Description
havedata;
Returns 1 if any simulation objects have raw data, and 0 if

none have any raw data.
havedata("name");
Returns 1 if "name" has raw data, and 0 if it does not have

any raw data.
havedata("name","data");
Returns 1 if "name" has the raw data named "data", and 0

if it does not have that data.
See Also
Measurements 267 , getdata 269 , haveresult 271 , getresult 270 , copydcard 273 , cleardcard 274 ,
workspace 136 , havesweepdata 272
Available in
FDTD Solutions
MODE Solutions
INTERCONNECT
DEVICE
Yes
Yes
No
Yes
7.10.7 haveresult
Used to see a simulation object (such as a monitor) has any results.
Note: This command is very similar to havedata, but is intended to be used with the
getresult command, rather than getdata.
Syntax
Description
haveresult;
Returns 1 if any simulation objects currently have any

results.
haveresult("name");
Returns 1 if "name" has any results, and 0 if it does not.
haveresult("name","data");
Returns 1 if the "name" has a result named "data", and 0 if

it does not.
272
Reference Guide
See Also
Measurements 267 , getresult 270 , havedata 271 , getdata 269 , copydcard 273 , cleardcard 274 ,
workspace 136 , havesweepdata 272
7.10.8 havesweepdata
Used to check if parameter sweep and optimizations have data. Similar to havedata, but for
sweeps and optimization tasks.
Syntax
Description
havesweepdata;
Returns 1 if any sweeps or optimizations have data.

Returns 0 if data is not available.
havesweepdata("name");
Returns 1 if the specified sweep or optimization has data.
havesweepdata
("name","data");
Returns 1 if the sweep or optimization "name" has the

specified data.
See Also
Measurements 267 , runsweep 267 , getsweepdata 268 , getdata 269 , havedata 271
7.10.9 havesweepresult
Used to check if parameter sweep and optimizations have results. Similar to haveresult, but
used for checking if sweeps and optimization tasks have available results.
Syntax
Description
havesweepresult;
Returns 1 if any sweeps or optimizations have results.

Returns 0 if data is not available.
havesweepresult("name");
Returns 1 if the specified sweep or optimization has

results.
havesweepresult
("name","data");
Returns 1 if the sweep or optimization "name" has the

specified result.
See Also
Measurements 267 , runsweep 267 , getsweepresult 269 , getresult 270 , haveresult 271
Scripting Language
273
7.10.10 copydcard
Will create a global copy of any d-card currently in memory. This command is available in
FDTD and MODE.
Syntax
Description
copydcard( "name");
Will create a global copy of any d-card currently in memory

called "name". By default, the new name will be "::
global_name".
copydcard( "name",
"newname");
Will create a global copy of any d-card currently in memory

called "name". The new name will be "::newname".
See Also
Measurements 267 , havedata 271 , cleardcard 274
Available in
FDTD Solutions
MODE Solutions
INTERCONNECT
DEVICE
Yes
Yes
No
No
7.10.11 clearanalysis
Clears analysis object results. This data is also cleared by switching from Analysis Mode
to Layout Mode. This command is not available in INTERCONNECT.
Note: The analysis object results are calculated with the runanalysis command.
Syntax
Description
clearanalysis;
Clears analysis object results.

clearanalysis( "name1",
"name2", ...);
Clears data from specific analysis objects.
See Also
Measurements 267 , switchtolayout 208 , getdata 269 , runanalysis 270 , havedata 271
274
Reference Guide
7.10.12 cleardcard
Clears global d-cards. Only global d-cards are cleared. Local d-cards are associated with
the current simulation and can only be cleared by switching from Analysis Mode to Layout
Mode. This command is available in FDTD and MODE.
Syntax
Description
cleardcard;
Clears all the global d-cards.

cleardcard( "name1",
"name2", ...);
Clears any number of specified d-cards.
See Also
Measurements 267 , havedata 271 , copydcard 273
7.10.13 getelectric
Returns the sum of the amplitude squares for all electric field components, i.e. it returns |
Ex|2+|Ey|2+|Ez|2. This command is available in FDTD and MODE.
Syntax
Description
out = getelectric
( "monitorname");
Returns |Ex|2+|Ey|2+|Ez|2 from the monitor.
getelectric( "monitorname",
option);
The optional argument, option, can have a value of 1 or 2. If

it is 2, the data is unfolded where possible according to the
symmetry or anti-symmetric boundaries if it comes from a
monitor that intersect such a boundary at x min, y min or z
min. The default value of option is 2.
See Also
Measurements 267 , getdata 269 , getmagnetic 274 , cwnorm, nonorm
7.10.14 getmagnetic
Returns the sum of the amplitude squares for all magnetic field components, i.e. it returns |
Hx|2+|Hy|2+|Hz|2. This command is available in FDTD and MODE.
Syntax
Description
out = getmagnetic
( "monitorname");
Returns |Hx|2+|Hy|2+|Hz|2 from the monitor.
Scripting Language
getmagnetic
( "monitorname", option);
275
The optional argument, option, can have a value of 1 or 2. If

it is 2, the data is unfolded where possible according to the
symmetry or anti-symmetric boundaries if it comes from a
monitor that intersect such a boundary at x min, y min or z
min. The default value of option is 2.
See Also
Measurements 267 , getdata 269 , getelectric 274 , cwnorm, nonorm
7.10.15 Read and write data to files

Please see the following section for file I/O commands.
System level commands: File input and output 109
7.10.16 loadsweep
The script command loads the sweep object with the previously generated sweep result.
Syntax
Description
loadsweep;
Loads previously generated sweep result to all the sweep

objects in simulation.
loadsweep("name");
Loads previously generated sweep result to the specified

sweep objects in simulation.
See Also
Measurements 267 , getdata 269 , runsweep 267 , havesweepdata 272 , savedata 121 ,
getsweepresult 269 , savesweep 275
7.10.17 savesweep
The script command saves the sweep object results.
Syntax
Description
savesweep;
Saves the sweep result of all sweep objects in simulation.
savesweep("name");
Saves the sweep result of the specified sweep object.
See Also
Measurements 267 , getdata 269 , runsweep 267 , havesweepdata 272 , savedata 121 ,
getsweepresult 269 , loadsweep 275
276
Reference Guide
7.11 Material database

The following commands are used to add or copy materials in the material database, as
well as to set any material property and verify the resulting complex index of a given
material at any frequency. (The permittivity can be easily obtained by squaring the index.)
Please see the chapter on the material database to understand the usage of these
commands.
This section is not relevant for INTERCONNECT.
Command
Description
addmaterial 276
Adds a new material into the material database.
copymaterial 277
Copies an existing material in the material database
setmaterial 277
Sets any property of an existing material in the

material database.
getmaterial 277
Returns properties of a material in the material

database.
getindex 278
Returns the complex index of a material.
getfdtdindex 278
Returns the material index as it will be in an actual

FDTD simulation.
getmodeindex 279
Returns the material index as it will be in an actual

MODE simulation.
getnumericalpermittivity 280
An advanced function that returns permittivity, taking

into account the effect of finite size of dt in an FDTD
simulation.
7.11.1 addmaterial
Adds a new material to the material database. This command is not available in
INTERCONNECT.
Syntax
Description
?addmaterial;
Displays all types of materials that can be added into the

material database.
out = addmaterial
("materialtype");
Adds a new material and returns the name of the new

material. The argument "materialtype" is has to match
correct string exactly.
See Also
Scripting Language
277
Material database 276 , setmaterial 277 , getindex 278 , getfdtdindex 278
7.11.2 copymaterial
Makes a copy of a material in the material database. This command is not available in
INTERCONNECT.
Syntax
Description
out = copymaterial
("materialname");
Creates a copy of the material "materialname". The new

name is returned.
See Also
Material database 276 , setmaterial 277 , getindex 278 , getfdtdindex 278
7.11.3 setmaterial
Modifies properties of a material in the material database. This command is not available in
INTERCONNECT.
Syntax
Description
?setmaterial
("materialname");
Displays the property names of the specified material that

can be modified.
setmaterial( "materialname", Sets the property named "propertyname" of the material

"propertyname", newvalue); with the name "materialname" to newvalue. The argument
newvalue can be a number or a string. The arguments
"propertyname" and "materialname" have to match correct
string exactly. For example,
setmaterial("Si","Mesh order",4);
will set the property "mesh order" of the materials "Si" to
4.
See Also
Material database 276 , addmaterial 276 , getmaterial 277 , getindex 278 , getfdtdindex 278
7.11.4 getmaterial
Returns properties of a material in the material database. This command is not available in
INTERCONNECT.
Syntax
Description
278
Reference Guide
?getmaterial
( "materialname");
Displays the property names of the specified material that

can be modified.
out = getmaterial
( "materialname",
"propertyname");
Returns the property named "propertyname" of the material

with the name "materialname". The returned variable is
either a matrix or a string, depending on the property in the
query.
See Also
Material database 276 , addmaterial 276 , setmaterial 277 , getindex 278 , getfdtdindex 278
7.11.5 getindex
Returns the complex index of any material that is in the material database. The index at
the specified frequency is interpolated from the neighboring frequencies where the index
data is available. This command is available in FDTD and MODE.
Syntax
Description
out = getindex
( "materialname", f);
Returns the complex index of the material with the given

name. The index is returned for the specified frequency f.
Frequency f is in Hz.
getindex( "materialname", f,
component);
Optional argument component can be 1, 2 or 3 to specify

the x, y or z component for anisotropic materials. The
default is 1.
See Also
Material database 276 , getfdtdindex 278 , getmodeindex 279 , addmaterial 276 , setmaterial 277
7.11.6 getfdtdindex
This function returns the material index of a material in the database as it will be used in an
actual FDTD simulation.
Many materials (such as Sampled materials) have properties that depend on frequency.
Using getfdtdindex, you can specify frequency range, and the fitting routine will find a best
fit of the material data over that range. The index evaluated at the specified f is then
returned. Note that the fit result depends on the fit parameters, Max coefficients and
Tolerance set for the material, thus getfdtdindex result depends on those parameters as
well.
Scripting Language
279
Syntax
Description
out = getfdtdindex
( "materialname", f, fmin,
fmax);

Similar to getindex, but you also specify fmin and fmax,
the span of frequency of the FDTD simulation. All
frequency units are in Hz.
getfdtdindex("materialname", Optional argument component can be 1, 2 or 3 to specify

f,fmin, fmax, component);
default is 1.
See Also
Material database 276 , getindex 278 , getmodeindex 279 , addmaterial 276 , setmaterial 277
7.11.7 getmodeindex
This function returns the material index of a material in the database as it will be used in an
actual MODE simulation.
Many materials (such as Sampled Materials) have properties that depend on frequency.
Using getmodeindex, you can obtain the refractive index as a function of the specified
frequency, f, as it will be used in MODE calculations. Note that when multi-coefficient
models are used, the fit result depends on the fit parameters, Max coefficients and
Tolerance set for the material.
Syntax
Description
out = getmodeindex
( "materialname", f);

This result is identical to getindex unless the optional
arguments fitsampled and fitanalytic are used. All
frequency units are in Hz.
getmodeindex
("materialname", f,
component);

default is 1.
getmodeindex
("materialname", f,
component, fitsampled,
fitanalytic, fmin, fmax);
Optional arguments to specify if Sampled Materials or

Analytic Materials should be fitted using Lumerical's multicoefficient model (MCM), which is commonly used in
FDTD simulations. If either of these options are set to 1
(true) then you must supply a minimum and maximum
280
Reference Guide
frequency for fitting. The MCM is typically used in MODE
Solutions for
Sampled Materials when calculating waveguide
dispersion, and for
Analytic Materials only for the purpose of using precisely
the same materials in both FDTD and MODE
simulations.
The default values are 0 (false) for fitsampled and
fitanalytic.
See Also
Material database 276 , getindex 278 , getfdtdindex 278 , addmaterial 276 , setmaterial 277
7.11.8 getnumericalpermittivity
This advanced function returns the permittivity of a material in the database as it will be
used in an actual FDTD simulation, including the effects of a finite time step, dt. In FDTD,
the relationship between the displacement field, D, and the electric field, E, is given by
0 r
, dt E
In the limit where dt tends to zero, we have

lim dt 0 r , dt n 2
where n( ) is the refractive index returned by the script function getfdtdindex, or shown in
the Materials Explorer. If you set dt to zero when calling this function, it will return exactly
the same result as the square of getfdtdindex.
The name of the function is a reminder that it returns the numerical permittivity, ie, the ratio
of D and E, which is different from the refractive index, ie the ratio of the speed of light in a
vacuum to the phase velocity of light in the medium. To understand the relationship
between the them, we must consider the full, numerical dispersion relation between and
k which is given by
r
1
, dt
sin
cdt
dt
2
k dx
1
sin x
dx
2
k y dy
1
sin
dy
2
1
k dz
sin z
dz
2
In the limit where dt, dx, dt and dz tend to zero, it is easy to show that we have the
expected result
ck
r ( , dt
0)
ck
n( )
The spatial FDTD mesh and time step are generally chosen to obtain a desired level of
simulation accuracy, essentially by ensuring that the arguments of the sine functions are
Scripting Language
281
sufficiently small that sin(x)~x and that the simulation is stable. For some materials, it may
be desired to further reduce the value of the time step, dt, without modifying the spatial
FDTD mesh, in order to obtain a higher level of accuracy for r( ,dt). This script function
makes it possible to calculate, in advance, the value of dt required to obtain the desired
accuracy for the permittivity.
Syntax
Description
out =
getnumericalpermittivity
( "materialname", f, fmin,
fmax, dt);
Returns the complex permittivity of the material with the

given name. The permittivity is returned for the specified
frequency f. This is similar to getfdtdindex except for the
additional parameter dt. All frequency units are in Hz.
("materialname", f,fmin,
fmax, dt, component);

default is 1.
See Also
Material database 276 , getindex 278 , addmaterial 276 , setmaterial 277 , getfdtdindex 278
7.12 GDSII
The following commands can be used to import and export GDSII files.
Command
Description
gdsopen 282
Opens a GDSII file for writing.
gdsclose 282
Closes a GDSII file for writing.
gdsbegincell 283
Starts a new cell in a GDSII file.
gdsendcell 283
Finishes a cell in a GDSII file.
gdsaddpoly 284
Adds a polygon element to a GDSII file stream.
gdsaddcirlce 284
Adds an approximation of a circle to a GDSII file

stream.
gdsaddrect 285
Adds a rectangle element to a GDSII file stream.
gdsaddref 286
Adds a reference to another cell to the current cell in

the GDSII file stream.
gdsimport 286
Imports a cell from a .gds file into the layout

environment.
282
Reference Guide
7.12.1 gdsopen
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 Userguide - 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.
See Also
gdsclose 282 , gdsbegincell 283 , gdsendcell 283 , gdsaddpoly 284 , gdsimport 286
7.12.2 gdsclose
This function closes a GDSII file for writing. Before calling this command, a .gds file has to
be previously opened, see gdsopen 282 .
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.
See Also
gdsopen 282 , gdsbegincell 283 , gdsendcell 283 , gdsaddpoly 284 , gdsimport 286
Scripting Language
283
7.12.3 gdsbegincell
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 286
for more details. A GDS "cell" exists as a "structure group" when imported to FDTD, see
gdsimport 286 for more details.
Syntax
Description
gdsbegincell(f, "cellname")
Creates a new cell in a GDSII file.
Parameter
Type
Description
string
a file handle that was previously opened with

gdsopen.
cellname
string
name of the cell.
Note: Just to clarify, a GDS cell is different from a Cell Array 147 in FDTD.
See Also
gdsopen 282 , gdsclose 282 , gdsendcell 283 , gdsaddpoly 284 , gdsaddref 286 , gdsimport 286 ,
cell 147
7.12.4 gdsendcell
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
string

gdsopen.
See Also
gdsopen 282 , gdsclose 282 , gdsbegincell 283 , gdsaddpoly 284 , gdsimport 286
284
Reference Guide
7.12.5 gdsaddpoly
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

gdsopen.
layer
number
layer number for this structure.
vertices
vector
vertices of the polygon, in a 1D vector. They are

grouped in XY pairs 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.
See Also
gdsopen 282 , gdsclose 282 , gdsbegincell 283 , gdsendcell 283 , gdsaddcircle 284 , gdsaddref 286
, gdsimport 286
7.12.6 gdsaddcircle
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, Adds an approximation of a circle on a layer with x-, yn)

coordinates, radius and number of polygon sides.
Parameter
Type
Description
string

gdsopen.
Scripting Language
285
layer
number
number
x-coordinate of the center position in meters.
number
y-coordinate of the center position in meters.
number
radius of the circle in meters.
number
number of sides to use in the polygon approximation.

It is 64 by default.
See Also
gdsopen 282 , gdsclose 282 , gdsbegincell 283 , gdsendcell 283 , gdsaddpoly 284 , gdsaddref 286 ,
gdsimport 286
7.12.7 gdsaddrect
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
string

gdsopen.
layer
number
number
x-coordinate of the center position in meters.
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.
See Also
gdsopen 282 , gdsclose 282 , gdsbegincell 283 , gdsendcell 283 , gdsaddpoly 284 , gdsaddref 286 ,
gdsimport 286
286
Reference Guide
7.12.8 gdsaddref
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
string

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.
See Also
gdsopen 282 , gdsclose 282 , gdsbegincell 283 , gdsendcell 283 , gdsaddpoly 284 , gdsaddcircle
284 , gdsaddrect 285 , gdsimport 286
7.12.9 gdsimport
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 Reference Guide
- Layout editor chapter 29 , Reference Guide - GDSII Import 60 and Userguide - GDSII Import and export for more information.
This command is NOT available in INTERCONNECT.
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
Scripting Language
287
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.
"cellname", layer,
"material");
Same as the above command, but the material of the

imported object will be set to the value specified.
"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 the layer number from the GDSII file to import. If only
string
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 Reference
Guide - GDSII Import 60 , and Userguide - GDSII - Import and export for associated files.
gdsimport("GDS_export.gds", "cell_1", 1, "Ag (Silver) - CRC", 0,
1e-6);
288
Reference Guide
See Also
System level 109 , setnamed 232 , fileexists 117 , gdsopen 282
7.13 User defined GUIs

Custom GUIs can be created with the following commands.
Command
Description
message 288
Creates a message window that displays some text.
newwizard 289
Used to create a new user defined wizard.
newwizardpage 289
This creates a page for the wizard.
wizardwidget 289
Adds a new widget to the current wizard window.
runwizard 291
Runs the wizard and returns a value indicating which

button was pressed.
wizardgetdata 291
Returns data entered into a specific widget.
killwizard 291
This closes the wizard window.
wizardoption 292
Sets some options for wizard widgets and labels.
fileopendialog 292
Calls the standard windows file open dialog.
filesavedialog 292
Calls the standard windows file save dialog.
Typically, a wizard will be created with the following steps

1. Open a new wizard with newwizard 289
2. Add a new wizard page with newwizardpage 289
3. Add widgets to the wizard page with wizardwidget 289
4. Call runwizard 291 to run the wizard
5. Use wizardgetdata 291 to obtain values entered into widgets by the user
6. Depending on the values returned by runwizard 291 , the wizard can be closed with
killwizard 291 , or a new wizard page is started with newwizardpage 289 .
7.13.1 message
Creates a message window that displays some text. The user must hit Enter, or click the
OK button to continue.
Syntax
Description
message("text");
Creates a window that displays text.
Scripting Language
289

See Also
User defined GUI 288 , newwizard 289
7.13.2 newwizard
Used to create a new user defined wizard. Opens a new wizard window.
Syntax
newwizard( w, h, "title");
Description
w and h (width and height) are specified in pixels. The
minimum values for w and h are 200.
title is the wizard window title.
See Also
User defined GUI 288 , message 288
7.13.3 newwizardpage
This creates a page for the wizard and should be done before adding any widgets.
Syntax
Description
newwizardpage( "label1");
Creates a button with the label "label1". Typically, this will

be "Done" or "OK".
newwizardpage( "label1",
"label2");
Creates two buttons with labels "label1" and "label2".

These will typically be "Next" and "Back" or "Done" and
"Back".
See Also
User defined GUI 288 , newwizardpage 289
7.13.4 wizardwidget
Adds a new widget to the current wizard window. This command should only be done after
creating a new wizard page with the command newwizard.
Syntax
Description
wizardwidget( "type",
"name");
type can be
"number" for a numeric input field
"string" for a alphanumeric field
"checkbox" for a checkbox
290
Reference Guide
"menu" for a pulldown menu field
"label" to add a string label (wizardgetdata does not
return information for labels)
name is a string used to give the input field, checkbox,
menu item or label a name.
wizardwidget( "type", "label", defaultValue provides a default value for numeric inputs,
defaultValue);
checkboxes, menu items or strings.
wizardwidget( "type", "label", If the "type" of widget is a "menu", then the menu choices
"choices", defaultValue);
must be provided. These choices should be separated by
the character "|". For example, to create a pulldown widget
with the name "simulation type" and 3 choices
"TE","TM","3D", with the default choice "3D", the
command is
wizardwidget("menu","simulation type","TE|TM|3D",3);
See Also
7.13.5 wizarddata
This command will cause the wizard window to wait until the user selects OK or Cancel. It
then returns value data from the matrix in a N+1 length matrix, where N is the number of
widgets (excluding labels) in the current wizard page.
This function is only available in MODE Solutions.
Syntax
Description
out = wizarddata;
The values of out are

out(1) = 0, 1 or -1. 0 means the user pressed Cancel, 1
means the user pressed the first button (typically "OK"
or "Next") and -1 means the user pressed the second
button (typically "Back")
out(2:N+1) gives the numeric values that the user
entered for each input field when out(1) is 1. Note that
check boxes return 1 if checked and 0 if unchecked.
Menu items return a number between 1 and M where M
is the number of choices in the menu. If out(1) is 0 or -1,
all the values out(2:N+1) are zero.
See Also
Scripting Language
291
7.13.6 runwizard
Runs the wizard and returns a value indicating which button was pressed.
Syntax
Description
out = runwizard;
Returns either 0, +1 or -1.

0 means the user pressed Cancel, 1 means the user
pressed the first button (created by calling newwizardpage)
and -1 means the user pressed the second button (created
by calling newwizardpage).
See Also
7.13.7 wizardgetdata
Returns data entered into a specific widget.
This function is only available in MODE Solutions.
Syntax
Description
out = wizardgetdata(N);
Returns the value that the user entered into the Nth widget.
Out will be a number or a string, depending on the type of
widget.
See Also
7.13.8 killwizard
This closes the wizard window. It should only be called after a wizard window has been
created with the newwizard command.
Syntax
Description
killwizard;
This closes the wizard window.
See Also
292
Reference Guide
7.13.9 wizardoption
Sets some options for wizard widgets and labels.
Syntax
Description
wizardoption ("optionname",
setting);
The options are

"fontsize" sets the font size to any value between 8 and
40
"fieldwidth" sets the width of each widget field to any
value between 20 and the full width of the wizard window.
"fieldheight" sets the height of each field to any value
between 8 and the full height of the wizard window.
"margin", sets size of the left margin to any value
between 0 and full width of the wizard window.
See Also
7.13.10 fileopendialog
Calls the standard windows file open dialog.
Syntax
Description
out = fileopendialog;
Brings up the open file dialog box and returns the path that
the user selects.
out = fileopendialog(".ext");
Brings up the open file dialog box, displaying only files with
the extension .ext. Returns the path of the file that the user
selects.
See Also
User defined GUIs 288 , filesavedialog 292
7.13.11 filesavedialog
Calls the standard windows file save dialog.
Syntax
Description
out = filesavedialog;
Brings up the save file dialog box and returns the path that
the user selects.
out = filesavedialog(".ext");
Brings up the save file dialog box, displaying only files with
the extension .ext. Returns the path of the file that the user
Scripting Language
293
selects.
See Also
User defined GUIs 288 , fileopendialog 292
7.14 Creating your own script commands

Running a script file from the script prompt
You can run any script file simply by typing the name of the file (without the .lsf extension).
For example, if you create the file create_array.lsf, you can run this file from the command
prompt, or another script file, with the command
create_array;
The current working directory is always in the Lumerical script path, and is the most
common location for your script files. You can add additional locations to the path with
the addpath 119 script function. The following location (within the installation directory) is
also always in the path, making it a convenient place to put script functions that may be
needed my all users of the computer. It will be necessary to have admin access to save
files in this location.
C:\Program Files\Lumerical\FDTD\scripts (Windows)
/usr/local/lumerical/scripts (Linux)
Note: Saving script files with the same name as built in script functions
It is generally not recommended to create script files that have the same name as the
standard script functions. In such cases, where there is a conflict between a script file and
standard script function, the script file will run. In other words, this allows you to override
the behavior of a standard script function. This can be helpful, but it can also lead to
confusing behavior when done unintentionally.
Calling one script file from another

Once you start creating complex scripts, it may be convenient to split them up into a
number of simpler scripts that call one another. If you have multiple scripts in the same
directory then they can call each other just as you would use any other scripting
command.
Note:
All script files use a common variable space. As a consequence, variables defined in the
scripts are global, and the script files have access to all variables defined in the simulation
project file. This can lead to problems when two script files use the same variable names.
For example, script_1.lsf (defined below) will print the value 10 to the command line
since script_2.lsf modified the variable i.
script_1.lsf
i=1;
294
Reference Guide
script_2;
?i;
script_2.lsf
for(i=1:10) {
# do something
}
Formatting tips
Multiple commands are allowed on a single line.
Blank lines, space and tabs will be ignored. Therefore you can format your script files
any way you choose.
Each command must be terminated with a semicolon.
On any line, all characters after a # symbol are ignored.
Finally, you can not define a variable or assign values to a variable that has the same name
as one of the script commands. For example, the following lines
sum = matrix(1,2);
angle = acos(pi/2);
are not valid statements since 'sum' and 'angle' are script functions.
Index
Index
'
156
150
! 154, 155
!=
152
"
155
#
157
%
133
&
153
*
150
/
150
:
132
?
157
[]
132
^ 151
|
154
~
155
+
150
<
153
<=
152
=
132
==
151
>
153
>=
152
abs
164
absolute
164
access
137
acos
163
addanalysisgroup
210
addbulkgen
220
addcircle
211
addcustom
211
adddevice
219
adddiffusion
219
adddipole
215
addeigenmode
214
addfdtd
214
addgaussian
216
addgridattribute
220
addgroup
209
addimage
211
addimportdope
219
addimportedsource
217
addimportgen
220
addindex
217
addition
150
addjob
266
addmaterial
276, 277
addmesh
215
addmode
215
addmodesource
215
addmovie
218
addobject
210
addpath
119
addplane
216
addpoly
212
addprofile
218
addpropagator
214
addpyramid
212
addrect
212
addring
213
addsphere
213
addstructuregroup
209
addsurface
214
addtfsf 216
addtime
217
addtogroup
230
addtriangle
213
adduserprop
231
almostequal
151
analysis group
70
analysis tools
81
and
153
angle
165
arccos
163
arcsin
162
295
296
Reference Guide
arctan
163
array
132, 137, 138
asap
123, 124
asapexport
123
asapimport
124
asapload
124
asin
162
assign
137
assignment
132
atan
163
atan2
163
break
120
c
138
CAD layout
29
cd
115
ceil
188
centroid
184
changing CAD layout
39
clear
136
clearanalysis
273
cleardcard
274
clearjobs
266
clearmodedata
254
clearsourcedata
254
clock
116
closeall
205
comment
157
comparison
151
conj
164
conjugate
164
copy
115, 230
copydcard
273
cos
162
cosine
162
cp
115
createbeam
218
cross
168
ctranspose
175
currentfilename
117
czt
183
data export
83
date
116
del
113, 114
delete
227
deleteall
226
detail
60
dir
114
division
150
dot
168
double quote
155
edit
31
eig
169
eigenvalue
169
eigenvector
169
else
197
endl
157
eps0
138
equal
132
equal to
151
equation interpreter
76
escape
120
eval
176
exit
116
exp
166
exponential
166
exportfigure
204
feval
176
fft
178
fftk
181
fftw
180
filebasename
117
filedirectory
118
fileexists
117
fileextension
118
fileopendialog
292
filesavedialog
292
find
174
findpeaks
174
Index
findstring
177
finite
191
flip
170
flipelement
229
floor
188
for
196
format
121
framerate
260
gaussian
190
gds
286
gdsii
60, 286
geometry
59
get
235
getcommands
118
getdata
269
geteigensolver
256
getelectric
274
getfdtdindex
278
getglobalmonitor
237
getglobalsource
237
getindex
278
getmagnetic
274
getmaterial
277
getmodeindex
279
getnamed
236
getnamednumber
237
getnumber
236
280
getpath
119
getsolver
238
getsweepdata
268
getview
259
graphics graphical rendering
60
greater than
153
greater than or equal to
152
groupscope
226
havedata
271
haveproperty
238
if 197
imag
164
image
202
imaginary
164
import
60, 286
import object
58
importbinary
246, 250
importbinary2
248
importnk
241
importnk2
243
importnkobfuscated
245
importsurface
238
importsurface2
240
inpoly
185
integrate
173
integrate2
173
interp
171
interpolate
171, 172
interptri
172
inverse
182
invfft
182
killwizard
291
layoutmode
209
legend
202
length
166
less than
153
less than or equal to
152
linecross
188
lineintersect
187
linspace
133
ln
165
load
113, 121
loaddata
121
location
59
log
165
log10
165
loop
196
ls
114
main
30
main title bar
29
297
298
Reference Guide
material
59
material database
42
matlab
83, 125
matlabget
127
matlabput
127
matlabsave
124
matrix
133, 138, 169
max
168
mesh
54
mesh refinement region
meshgrid3dx
135
meshgrid3dy
135
meshgrid3dz
136
meshgrid4d
136
meshgridx
134
meshgridy
135
message
288
min
168
mod
189
modulus
189
monitor
70
mouse mode
33
move
116, 229
moving windows
39
mu0
138
multiplication
150
multiply
169
mv 116
natural
165
negative
150
newmode
112
newproject
112
newwizard
289
newwizardpage
289
normal
190
not
152, 154, 155
num2str
175
object tree
37
Optimization
101
65
or
154
orbit
259
order
54
output
157
Particle Swarm Optimization
path
119
pause
120
permeability
138
permittivity
138
permute
170
phase
165
pi
138
pinch
167
plot
198
plotxy
199
polar
200
polar2
200
polarimage
201
polyand
186
polyarea
183
polydiff 186
polygrow
185
polyintersect
184
polyor
186
polyxor
187
power
151
priorities
54
product
168
PSO
101
pwd
115
quit
116
rand
190
randmatrix
133
random
190
randreset
191
readdata
122
real
164
redo
260
redraw
256
101
Index
redrawmode
257
redrawoff 257
redrawon
257
replace
177
replacestring
178
reshape
170
rm
114
rotations
60
round
189
run
118
runanalysis
270
runjobs
266
running a simulation
80
runparallel
265
runsetup
235
runsweep
267
runwizard
291
save
113, 121, 122
savedata
121
savedcard
122
screen
157
script
118
scripting editor prompt command line
seed
191
select
227
selectall
226, 227
selectfigure
204
selectpartial
228
set
231
seteigensolver
255
setglobalmonitor
232
setglobalsource
233
setmaterial
277
setnamed
232
setplot
204
setsourcesignal
252
setview
258
shiftselect
228
shiftselectpartial
229
38
sign
189
simulation
35
simulation region
65
sin
162
sine
162
single quote
156
size
59, 166
solar
191
speed of light
138
spline
172
sqrt
166
square root
166
str2num
176
string to number
176
strings
155, 156
structure
58
structures group
58
substring
176
subtraction
150
sum
167
switchtolayout
208
system
116
tan
162
tangent
162
time
116
time stamp
116
timestamp
116
toolbar
30
transparency
60
transpose
175
undo
260
unselectall
227
unwrap
165
updatemodes
253
updatesourcemode
251
variables with spaces
133
view
34
view ports perspective
36
visualize
203
299
300
Reference Guide
which
119
wizarddata
290
wizardgetdata
291
wizardoption
292
wizardwidget
289
workspace
136
write
123
z-transform
183

DEVICE Reference Guide

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

DEVICE Reference Guide

Hochgeladen von

Copyright:

Verfügbare Formate

DEVICE

Part II Solver physics

Part III CAD layout editor

Part IV Material database

Part V Simulation objects

Part VI Running simulations and analysis

2003 - 2013 Lumerical Solutions, Inc

Part VII Scripting Language

2003 - 2013 Lumerical Solutions, Inc

<= ................................................................................................................................................. 152

2003 - 2013 Lumerical Solutions, Inc

2003 - 2013 Lumerical Solutions, Inc

2003 - 2013 Lumerical Solutions, Inc

New features for version 1.5

Advanced contact models

2003 - 2013 Lumerical Solutions, Inc

Adaptive transient simulation

New features for version 2.0

Yield analysis tool

2003 - 2013 Lumerical Solutions, Inc

across multiple parameters to assess statistical variations of circuit elements on overall

Other new script commands

New features for version 3.1

Field and charge monitors

Continue from previous solution

2003 - 2013 Lumerical Solutions, Inc

Electron-hole density grid attribute

XML lookup table support

Export viewports to image

new script commands

2003 - 2013 Lumerical Solutions, Inc

MODE Solutions Eigenmode Solver

MODE Solutions Propagator 21

The method behind Lumerical's INTERCONNECT circuit simulator.

The method behind Lumerical's DEVICE electronic device simulator.

2003 - 2013 Lumerical Solutions, Inc

2.1.1 FDTD and Maxwell's equations

is the complex relative dielectric constant (

, where n is the refractive

2003 - 2013 Lumerical Solutions, Inc

2003 - 2013 Lumerical Solutions, Inc

2.1.2 Meshing in FDTD

2003 - 2013 Lumerical Solutions, Inc

MODE Solutions find these modes by solving Maxwell's equations on a cross-sectional

2003 - 2013 Lumerical Solutions, Inc

Z. Zhu and T. G. Brown, Full-vectorial finite-difference analysis of microstructured optical

2.2.1 Meshing in the Eigenmode solver

2003 - 2013 Lumerical Solutions, Inc

2.3.1 2.5D FDTD

2003 - 2013 Lumerical Solutions, Inc

2003 - 2013 Lumerical Solutions, Inc

"Effective index approximation of photonic crystal slabs: a 2-to-1-D assessment", Optical

2.3.2 Eigenmode expansion

2.3.3 Meshing in the propagator

2003 - 2013 Lumerical Solutions, Inc

2.4.1 Time Domain Simulator

2003 - 2013 Lumerical Solutions, Inc

2.4.2 Frequency Domain Simulator

The circuit is composed a series of elements connected by an arbitrary number of input/

2.5.1 System of Equations

2003 - 2013 Lumerical Solutions, Inc

where is the dielectric permittivity, V the electrostatic potential

2003 - 2013 Lumerical Solutions, Inc

DEVICE discretizes and solves the drift-diffusion and Poissons equations on an