Reference Guide: Solutions

FDTD Solutions
Reference Guide
Release 6.5
Contents
Table of Contents
Part I New Features
10
1 New features
............................................................................................................
for version 6.5
10
Structure
.................................................................................................................................................
groups
Analysis
.................................................................................................................................................
(monitor) groups
Object
.................................................................................................................................................
tree browser
Built
.................................................................................................................................................
in script file editor
Script
.................................................................................................................................................
syntax highlighting
Copy
.................................................................................................................................................
and Paste
Dipole
.................................................................................................................................................
radiated power calculation
New
.................................................................................................................................................
MODE source script commands
New
.................................................................................................................................................
script functions
Online
.................................................................................................................................................
Help search bar
Simplified
.................................................................................................................................................
installation
Improved
.................................................................................................................................................
material fits
10
10
10
10
11
11
11
11
11
11
12
12
2 New features
............................................................................................................
for version 6.0
12
Multi
.................................................................................................................................................
coefficient material model
Auto
.................................................................................................................................................
fitting of experimental data
Improved
.................................................................................................................................................
material database GUI
Expanded
.................................................................................................................................................
list of material data
Spectral
.................................................................................................................................................
averaging
More
.................................................................................................................................................
far field analysis
GUI.................................................................................................................................................
upgrade
User
.................................................................................................................................................
defined source signals
Shorter
.................................................................................................................................................
source pulses
Unicode
.................................................................................................................................................
characters
12
12
12
13
13
13
13
13
14
14
3 New features
............................................................................................................
for version 5.1
14
GDSII
.................................................................................................................................................
import
Improved
.................................................................................................................................................
figure windows
n and
.................................................................................................................................................
k import
Set.................................................................................................................................................
view and orbit
Surface
.................................................................................................................................................
imports
Windows
.................................................................................................................................................
Vista support
14
14
14
14
15
15
4 New features
............................................................................................................
for version 5.0
15
Graded
.................................................................................................................................................
mesh
Polygon
.................................................................................................................................................
and triangle primitives
Quadrics
.................................................................................................................................................
and Infinipath interconnects
Native
.................................................................................................................................................
support for the Windows x64 platform
Easier
.................................................................................................................................................
installation of parallel FDTD Solutions
Meshing
.................................................................................................................................................
improvements
Faster
.................................................................................................................................................
drawing modes for all primitives
Simulation
.................................................................................................................................................
auto shutoff
Improved
.................................................................................................................................................
movie monitors
Part II The physics of the FDTD algorithm
15
15
15
15
15
16
16
16
16
17
1 FDTD and Maxwell's

............................................................................................................
equations
17
2003 - 2009 Lumerical Solutions, Inc
Reference Guide
Part III Units and normalization

1
2
3
4
5
20
Source amplitudes
............................................................................................................ 21
Frequency domain
............................................................................................................
normalization
22
Spectral averaging
............................................................................................................ 24
Calculating ............................................................................................................
and normalizing power in the frequency domain
30
Integrating over
............................................................................................................
lines, surfaces and volumes
31
Part IV Simulation objects
33
1 Structures tab
............................................................................................................ 34
Geometry
.................................................................................................................................................
tab
Material
.................................................................................................................................................
tab
Rotations
.................................................................................................................................................
tab
Graphical
.................................................................................................................................................
Rendering tab
Custom
.................................................................................................................................................
tab
Import
.................................................................................................................................................
Data tab
Surface
.................................................................................................................................................
tab
Properties
.................................................................................................................................................
tab
Script
.................................................................................................................................................
tab
36
36
37
37
37
38
41
42
43
2 Simulation tab
............................................................................................................ 43
General
.................................................................................................................................................
tab
Geometry
.................................................................................................................................................
tab
Mesh
.................................................................................................................................................
settings tab
Boundary
.................................................................................................................................................
conditions tab
Advanced
.................................................................................................................................................
options tab
44
44
44
45
48
3 Sources tab............................................................................................................ 49
General
.................................................................................................................................................
tab
Geometry
.................................................................................................................................................
tab
Frequency/Wavelength
.................................................................................................................................................
tab
Beam
.................................................................................................................................................
options tab
Advanced
.................................................................................................................................................
tab
52
53
54
55
57
4 Monitors tab............................................................................................................ 58
Frequency
.................................................................................................................................................
Power/Profile tab
Frequency
.................................................................................................................................................
Power/Profile Advanced tab
General
.................................................................................................................................................
tab
Data
.................................................................................................................................................
to record tab
Geometry
.................................................................................................................................................
tab
Spectral
.................................................................................................................................................
averaging and apodization tab
Advanced
.................................................................................................................................................
tab
Setup
.................................................................................................................................................
tab
Analysis
.................................................................................................................................................
tab
60
60
61
62
62
62
63
64
64
5 Equation interpreter
............................................................................................................ 65
Part V Integrated mode solver
67
1 Mode analysis
............................................................................................................ 67
Plot
.................................................................................................................................................
and analysis options
68
Contents
Plot
.................................................................................................................................................
area
70
2 Advanced options
............................................................................................................ 71
Part VI Material database
72
1 Material database
............................................................................................................ 72
Models
.................................................................................................................................................
Mesh
.................................................................................................................................................
order
Anisotropic
.................................................................................................................................................
materials
74
77
77
2 Material Explorer
............................................................................................................ 78
Part VII CAD layout editor
81
1 Layout editor
............................................................................................................
tabs and Objects tree
82
2 Main title bar
............................................................................................................ 83
GDSII
.................................................................................................................................................
Import
Modifying
.................................................................................................................................................
your default settings
3 Toolbars
84
86
............................................................................................................ 87
Edit
.................................................................................................................................................
Mouse
.................................................................................................................................................
mode
View
.................................................................................................................................................
Simulation
.................................................................................................................................................
88
89
90
91
4 View ports ............................................................................................................ 92

5 Script Prompt
............................................................................................................
and Script Editor
93
6 Changing CAD
............................................................................................................
layout
93
Part VIII Running a simulation
96
1 Running a simulation
............................................................................................................
from the command line
97
Part IX Analysis tools
98
1 Analysis tools
............................................................................................................
and the simulation environment
98
2 The analysis............................................................................................................
window
99
Monitor
.................................................................................................................................................
properties tab
Far
.................................................................................................................................................
field settings tab
100
100
3 Analysis groups
............................................................................................................ 101
4 Figure windows
............................................................................................................
for plots and images
103
5 Data export
............................................................................................................ 104
Part X Scripting Language
106
1 System level
............................................................................................................ 107
del
.................................................................................................................................................
rm.................................................................................................................................................
dir.................................................................................................................................................
ls.................................................................................................................................................
cd.................................................................................................................................................
pwd
.................................................................................................................................................
cp.................................................................................................................................................
109
109
109
110
110
110
110
Reference Guide
mv
.................................................................................................................................................
exit
.................................................................................................................................................
system
.................................................................................................................................................
fileexists
.................................................................................................................................................
currentfilename
.................................................................................................................................................
filebasename
.................................................................................................................................................
fileextension
.................................................................................................................................................
filedirectory
.................................................................................................................................................
Run
.................................................................................................................................................
script
getpath
.................................................................................................................................................
addpath
.................................................................................................................................................
which
.................................................................................................................................................
pause
.................................................................................................................................................
break
.................................................................................................................................................
Excape
.................................................................................................................................................
key
File
.................................................................................................................................................
IO background
format
.................................................................................................................................................
loaddata
.................................................................................................................................................
savedata
.................................................................................................................................................
savedcard
.................................................................................................................................................
readdata
.................................................................................................................................................
write
.................................................................................................................................................
asapexport
.................................................................................................................................................
asapload
.................................................................................................................................................
asapimport
.................................................................................................................................................
gdsimport
.................................................................................................................................................
matlabsave
.................................................................................................................................................
lum2mat
.................................................................................................................................................
lum2mat
.................................................................................................................................................
command line
matlab
.................................................................................................................................................
matlabget
.................................................................................................................................................
matlabput
.................................................................................................................................................
111
111
111
112
112
112
113
113
113
113
114
114
114
115
115
115
116
116
116
117
117
117
118
118
119
119
120
121
122
122
123
124
2 Manipulating
............................................................................................................
variables
124
= .................................................................................................................................................
: .................................................................................................................................................
[] .................................................................................................................................................
%.................................................................................................................................................
linspace
.................................................................................................................................................
matrix
.................................................................................................................................................
randmatrix
.................................................................................................................................................
meshgridx
.................................................................................................................................................
meshgridy
.................................................................................................................................................
meshgrid3dx
.................................................................................................................................................
meshgrid3dy
.................................................................................................................................................
meshgrid3dz
.................................................................................................................................................
clear
.................................................................................................................................................
workspace
.................................................................................................................................................
Accessing
.................................................................................................................................................
and assigning matrix elements
Matrix
.................................................................................................................................................
operators
Pre-defined
.................................................................................................................................................
constants
125
125
125
126
126
126
127
127
127
127
128
128
128
129
129
130
130
Contents
3 Operators ............................................................................................................ 130

* .................................................................................................................................................
/ .................................................................................................................................................
+ .................................................................................................................................................
- .................................................................................................................................................
^ .................................................................................................................................................
==.................................................................................................................................................
almostequal
.................................................................................................................................................
!=.................................................................................................................................................
<=.................................................................................................................................................
>=.................................................................................................................................................
< .................................................................................................................................................
> .................................................................................................................................................
& .................................................................................................................................................
and
.................................................................................................................................................
| .................................................................................................................................................
or.................................................................................................................................................
! .................................................................................................................................................
~ .................................................................................................................................................
num2str
.................................................................................................................................................
" .................................................................................................................................................
' .................................................................................................................................................
endl
.................................................................................................................................................
? .................................................................................................................................................
comments
.................................................................................................................................................
132
132
132
132
133
133
133
134
134
134
135
135
135
135
136
136
136
137
137
137
138
139
139
139
4 Functions ............................................................................................................ 139

sin
.................................................................................................................................................
cos
.................................................................................................................................................
tan
.................................................................................................................................................
asin
.................................................................................................................................................
acos
.................................................................................................................................................
atan
.................................................................................................................................................
atan2
.................................................................................................................................................
real
.................................................................................................................................................
imag
.................................................................................................................................................
conj
.................................................................................................................................................
abs
.................................................................................................................................................
angle
.................................................................................................................................................
unwrap
.................................................................................................................................................
log
.................................................................................................................................................
log10
.................................................................................................................................................
sqrt
.................................................................................................................................................
exp
.................................................................................................................................................
size
.................................................................................................................................................
length
.................................................................................................................................................
pinch
.................................................................................................................................................
sum
.................................................................................................................................................
max
.................................................................................................................................................
min
.................................................................................................................................................
interp
.................................................................................................................................................
141
142
142
142
143
143
143
143
144
144
144
144
145
145
145
145
146
146
146
146
147
147
147
148
Reference Guide
spline
.................................................................................................................................................
integrate
.................................................................................................................................................
find
.................................................................................................................................................
findpeaks
.................................................................................................................................................
transpose
.................................................................................................................................................
ctranspose
.................................................................................................................................................
fft.................................................................................................................................................
fftw
.................................................................................................................................................
fftk
.................................................................................................................................................
invfft
.................................................................................................................................................
czt
.................................................................................................................................................
round
.................................................................................................................................................
rand
.................................................................................................................................................
randreset
.................................................................................................................................................
148
148
149
149
150
150
150
152
153
154
155
155
156
156
5 Loop and conditional

............................................................................................................
statements
156
for
.................................................................................................................................................
if .................................................................................................................................................
157
157
6 Plotting commands
............................................................................................................ 158
plot
.................................................................................................................................................
legend
.................................................................................................................................................
image
.................................................................................................................................................
setplot
.................................................................................................................................................
selectfigure
.................................................................................................................................................
exportfigure
.................................................................................................................................................
closeall
.................................................................................................................................................
158
159
159
160
160
160
161
7 Manipulating
............................................................................................................
objects
161
deleteall
.................................................................................................................................................
delete
.................................................................................................................................................
selectall
.................................................................................................................................................
unselectall
.................................................................................................................................................
select
.................................................................................................................................................
selectpartial
.................................................................................................................................................
shiftselect
.................................................................................................................................................
shiftselectpartial
.................................................................................................................................................
move
.................................................................................................................................................
copy
.................................................................................................................................................
addtogroup
.................................................................................................................................................
adduserprop
.................................................................................................................................................
set
.................................................................................................................................................
setnamed
.................................................................................................................................................
setglobal
.................................................................................................................................................
get
.................................................................................................................................................
getnumber
.................................................................................................................................................
getnamed
.................................................................................................................................................
getnamednumber
.................................................................................................................................................
getglobal
.................................................................................................................................................
haveproperty
.................................................................................................................................................
importsurface
.................................................................................................................................................
importsurface2
.................................................................................................................................................
importnk
.................................................................................................................................................
163
163
164
164
164
164
165
165
166
166
166
167
167
168
168
169
170
170
171
171
171
172
173
174
Contents
importnk2
.................................................................................................................................................
redraw
.................................................................................................................................................
redrawoff
.................................................................................................................................................
redrawon
.................................................................................................................................................
redrawmode
.................................................................................................................................................
setview
.................................................................................................................................................
getview
.................................................................................................................................................
orbit
.................................................................................................................................................
undo
.................................................................................................................................................
redo
.................................................................................................................................................
7
175
176
176
176
176
177
178
178
179
179
8 Measurement
............................................................................................................
data
179
showdata
.................................................................................................................................................
havedata
.................................................................................................................................................
copydcard
.................................................................................................................................................
cleardcard
.................................................................................................................................................
getdata
.................................................................................................................................................
getelectric
.................................................................................................................................................
getmagnetic
.................................................................................................................................................
Read
.................................................................................................................................................
and write data to files
180
180
181
181
181
182
182
182
9 Material database
............................................................................................................ 183
addmaterial
.................................................................................................................................................
copymaterial
.................................................................................................................................................
setmaterial
.................................................................................................................................................
getmaterial
.................................................................................................................................................
getindex
.................................................................................................................................................
getfdtdindex
.................................................................................................................................................
183
183
184
184
185
185
10 User defined
............................................................................................................
GUIs
186
message
.................................................................................................................................................
newwizard
.................................................................................................................................................
newwizardpage
.................................................................................................................................................
wizardwidget
.................................................................................................................................................
runwizard
.................................................................................................................................................
wizardgetdata
.................................................................................................................................................
killwizard
.................................................................................................................................................
wizardoption
.................................................................................................................................................
fileopendialog
.................................................................................................................................................
filesavedialog
.................................................................................................................................................
186
187
187
187
188
188
188
189
189
190
11 FDTD Solutions
............................................................................................................
toolbox
190
new2d
.................................................................................................................................................
new3d
.................................................................................................................................................
load
.................................................................................................................................................
save
.................................................................................................................................................
run
.................................................................................................................................................
runparallel
.................................................................................................................................................
setparallel
.................................................................................................................................................
runanalysis
.................................................................................................................................................
structures
.................................................................................................................................................
simulation
.................................................................................................................................................
sources
.................................................................................................................................................
194
195
195
196
196
197
197
198
198
198
199
Reference Guide
monitors
.................................................................................................................................................
switchtolayout
.................................................................................................................................................
layoutmode
.................................................................................................................................................
addcircle
.................................................................................................................................................
addcustom
.................................................................................................................................................
addimport
.................................................................................................................................................
addpyramid
.................................................................................................................................................
addpoly
.................................................................................................................................................
addrect
.................................................................................................................................................
addring
.................................................................................................................................................
addsphere
.................................................................................................................................................
addsurface
.................................................................................................................................................
addstructuregroup
.................................................................................................................................................
addfdtd
.................................................................................................................................................
addmesh
.................................................................................................................................................
adddipole
.................................................................................................................................................
addgaussian
.................................................................................................................................................
addplane
.................................................................................................................................................
addmode
.................................................................................................................................................
addtfsf
.................................................................................................................................................
addimportedsource
.................................................................................................................................................
addindex
.................................................................................................................................................
addtime
.................................................................................................................................................
addmovie
.................................................................................................................................................
addprofile
.................................................................................................................................................
addpower
.................................................................................................................................................
addanalysisgroup
.................................................................................................................................................
setsourcesignal
.................................................................................................................................................
updatesourcemode
.................................................................................................................................................
clearsourcedata
.................................................................................................................................................
getsourceangle
.................................................................................................................................................
nonorm
.................................................................................................................................................
cwnorm
.................................................................................................................................................
sourcenorm
.................................................................................................................................................
sourcenorm2_avg
.................................................................................................................................................
sourcenorm2_pavg
.................................................................................................................................................
dipolepower
.................................................................................................................................................
sourcepower
.................................................................................................................................................
sourcepower_avg
.................................................................................................................................................
sourcepower_pavg
.................................................................................................................................................
sourceintensity
.................................................................................................................................................
sourceintensity_avg
.................................................................................................................................................
sourceintensity_pavg
.................................................................................................................................................
transmission
.................................................................................................................................................
transmission_avg
.................................................................................................................................................
transmission_pavg
.................................................................................................................................................
Near
.................................................................................................................................................
to far field projections
farfieldfilter
.................................................................................................................................................
farfield2d
.................................................................................................................................................
farfieldvector2d
.................................................................................................................................................
farfieldpolar2d
.................................................................................................................................................
199
199
199
200
200
200
201
201
201
201
202
202
202
203
203
203
203
204
204
204
205
205
205
205
206
206
206
207
207
207
208
208
208
209
209
210
211
211
212
213
214
215
215
216
217
217
218
221
222
223
223
Contents
farfieldangle
.................................................................................................................................................
farfield2dintegrate
.................................................................................................................................................
farfield3d
.................................................................................................................................................
farfieldvector3d
.................................................................................................................................................
farfieldpolar3d
.................................................................................................................................................
farfieldux
.................................................................................................................................................
farfielduy
.................................................................................................................................................
farfieldspherical
.................................................................................................................................................
farfield3dintegrate
.................................................................................................................................................
farfieldexact2d
.................................................................................................................................................
farfieldexact3d
.................................................................................................................................................
farfieldexact
.................................................................................................................................................
Grating
.................................................................................................................................................
calculations
grating
.................................................................................................................................................
gratingn
.................................................................................................................................................
gratingm
.................................................................................................................................................
gratingpolar
.................................................................................................................................................
gratingvector
.................................................................................................................................................
gratingperiod1
.................................................................................................................................................
gratingperiod2
.................................................................................................................................................
gratingbloch1
.................................................................................................................................................
gratingu1
.................................................................................................................................................
gratingu2
.................................................................................................................................................
gratingangle
.................................................................................................................................................
gratingbloch2
.................................................................................................................................................
224
224
225
226
226
227
227
227
228
229
230
231
232
233
233
234
234
235
236
236
236
236
237
237
237
12 Creating your
............................................................................................................
own script commands
238
Part XI Appendix
240
1 Software acknowledgement
............................................................................................................ 240
Index
241
10
Reference Guide
New Features
FDTD Solutions is constantly being upgraded. See the following sections for a list of the
latest new features.
1.1
New features for version 6.5
1.1.1 Structure groups

The ability to group structures is one of the main new features in FDTD 6.5. Groups can
be moved, rotated and copied as a single object. In addition to simple grouping, it is
possible to create parameterized group-objects by adding script code to the group.
For example, it is possible to create a Photonic Crystal Array group with a Pitch input
parameter. When the Pitch parameter is changed, all objects in the group will
automatically move to the appropriate position. For an example of how to create and use
a group see the pc micro cavity tutorial in the getting started section.
1.1.2 Analysis (monitor) groups

The ability to group monitors into Analysis groups is one of the main new features in
FDTD 6.5. Groups can be moved and copied as a single object. In addition to simple
grouping, it is possible to create parameterized group-objects by adding script code to the
group.
For example, it is possible to create a Scattering Cross-section Analysis group. The group
is composed of 4 monitors that form a box around the structure. One associated script
adjusts the monitor positions as defined by the input parameters. A second script
calculates the scattering cross-section from the monitor data. This analysis group is set
up in the monitors section of the Getting Started nanowire resonance tutorial. A second
analysis group example can be found in the pc micro cavity tutorial.
1.1.3 Object tree browser

The object tree browser provides an alternate view of objects within a simulation. It is
especially useful for complicated simulations with many overlapping objects. In such
cases, it is much easier to select objects from the tree view than directly in the graphical
view ports. It also makes selecting objects within groups possible. For more information,
see the layout editor tabs and object tree 81 section of the Layout editor chapter.
1.1.4 Built in script file editor

The Script file editor allows you to create, edit, and run script files directly from within
FDTD Solutions, rather than using another text editor like Notepad. Syntax highlighting
makes it easier to read, write and debug script files. The Run Script button makes running
the script quick and easy. For more information, see the script prompt and script file
editor 93 page in the Layout editor section.
New Features
11
1.1.5 Script syntax highlighting

The Script File Editor and Script Prompt have syntax highlighting to make the commands
easier to read, write and debug. Comments are green, strings are red, and loop/control
statements are blue.
1.1.6 Copy and Paste

FDTD Solutions now supports Copy and Paste operations. This allows you to copy (CtrlC) a group of objects from one simulation and paste (Ctrl-V) a copy of those objects into
a different simulation. This is especially useful with the new structure and analysis
groups.
1.1.7 Dipole radiated power calculation

The dipolepower 211 script command returns the actual power radiated by a dipole
source. This greatly simplifies calculations that require knowledge of the radiated power,
such as enhancement and efficiency measurements.
1.1.8 New MODE source script commands

The updatesourcemode 207 script command automatically updates the mode profile of
the MODE source. This makes it much easier to automate some types of parameter
sweeps.
The get 169 script command now returns the mode profile stored in the MODE source, in
addition to the other object properties.
The clearsourcedata 207 script command clears the mode profile from the MODE
Source.
1.1.9 New script functions

The following script functions were added in FDTD Solutions 6.5. For more information,
see the function description in the scripting section of the Reference Guide.
system 111 , almostequal 133 , not 136 , square brackets 125 , single
quotes 138 , format 116 , updatesourcemode 207 , clearsourcedata 207 ,
setglobal 168 , getglobal 171 , addstructuregroup 202 , addanalysisgroup
206 , adduserprop 167 , addtogroup 166 , getmaterial 184 , havedata 180 ,
layoutmode 199 , sourceintensity 214 , sourceintensity_avg 215 ,
sourceintensity_pavg 215 , dipolepower 211 , runanalysis 198 , runwizard
188 , wizardgetdata 188 , setplot 160 .
1.1.10 Online Help search bar

The Online Help search toolbar provides easy access to the FDTD Solutions Online Help
website. The toolbar will open your default web browser and search the Online Help for
the requested term. This is particularly useful when searching for script function syntax.
For more information, see the toolbars 87 page in the layout editor section.
12
Reference Guide
1.1.11 Simplified installation

Simplified licensing: The USB hardware keys now contain much of the licensing
information (expiry dates, quotas). In many cases, license files are no longer required.
Matlab script integration: FDTD Solutions automatically detects MATLAB. The MATLAB
script integration step of the FDTD installation has been removed.
MATLAB is a registered trademark of The Mathworks, Inc.
1.1.12 Improved material fits

The fitting functions used to generate material models from Sampled data materials have
been improved to give more control over the fits that can be generated. For example, you
can specify a custom wavelength range or force the fit to give priority to the real or
imaginary part of the permittivity.
1.2
1.2.1 Multi coefficient material model

In the past, FDTD Solutions supported single Plasma, Lorentz, Debye or combinations of
these dispersive models. FDTD Solutions 6 has a new generalized multi-coefficient
model that allows more complicated data to be fit. The accuracy of the model can be
controlled with the number of coefficients. More coefficients will give a better fit to
experimental data, but at the expense of more memory and longer simulation times.
This model is only available when using the Sampled data material definition. The
coefficients are automatically calculated from the sampled material data over the source
bandwidth. See the chapter on the Material Database 72 for details.
1.2.2 Auto fitting of experimental data

The Sampled data material definition (for importing experimental data) uses an automatic
fitting routine to calculate broadband model parameters from experimental data. This
makes importing experimental data much easier, since manually calculating model
parameters can be very difficult. See Material Database 72 for more information.
1.2.3 Improved material database GUI

The Material Database interface has been completely redesigned and simplified. The
Database provides an interface to modify the properties of existing materials and to add
new materials. The Material Explorer is used to view the index/permittivity profile of
material in the database. See the Material Database 72 chapter for more information.
New Features
13
1.2.4 Expanded list of material data

The number of materials included in the Material Database has been increased. Co, Cr,
Cu, Ge, In, Ni, Pt, Ti, W, AlN, GaAs, H20 are some of the new materials. The frequency
range of the data has also been expanded. Most materials have data at least from deep
UV to far infrared.
1.2.5 Spectral averaging

The Spectral averaging feature of Power and Profile monitors calculates the incoherent
spectral average of the electromagnetic fields or the Poynting vector as the simulation
runs. The technique is much more efficient than measuring many frequencies and
averaging after the simulation.
Two types of averaging are available. Total spectral averaging uses the source input
spectrum as the weighting function. This is most useful when the source spectrum of the
simulation matches the actual illumination conditions. Partial spectral averaging uses a
Lorentzian weighting function multiplied by the source spectrum. Partial spectral
averaging is useful to extract the average response of the system to a variety of different
illumination conditions from a single simulation.
See the Spectral averaging 24 section of the Units and Normalization chapter for more
details.
1.2.6 More far field analysis

A number of new far field projection and grating script functions have been added. Three
of the new functions are described here. For more information, see the far field function
section of the Reference Guide: Near to far field projections 218 .
The farfield3dintegrate 228 function makes integrating portions of the far field
much easier.
The farfieldspherical 227 function converts direction cosine units (returned from the
far field projection functions) into more familiar spherical coordinates.
The gratingvector 235 function can be used to study the polarization of grating orders
of periodic structures.
1.2.7 GUI upgrade

The entire Graphical User Interface has been updated. It is now possible to undock
individual sub-windows from the main application. This can be very helpful when trying to
make one sub-window very large. Another new feature is the ability to show/hide and
rearrange toolbars.
1.2.8 User defined source signals

The source time signal is normally generated by FDTD Solutions based on the frequency
range specified by the user. While the automatically generated pulse is usually
appropriate, there are some simulations where a custom source time signal is desirable.
FDTD Solutions 6.0 now supports user defined source time signals. See the script
14
Reference Guide
command setsourcesignal
207
for more information.
1.2.9 Shorter source pulses

FDTD Solutions 6.0 uses a new algorithm to generate the source time pulse from the
frequency range specified by the user. The new algorithm generates a much shorter time
pulse, while still ensuring that most of the pulse energy is contained within the
frequencies of interest.
The total simulation time of many simulations is dominated by the source pulse length.
These simulations will experience a significant speedup because of the shorter pulse.
Simulations with resonant structures, where the total simulation time is not dominated by
the source pulse length, will not experience this speedup.
1.2.10 Unicode characters

FDTD Solutions now supports Unicode file names and file paths. This allows users to
work in directories and save simulation files with names that include characters from
Japanese, Chinese, or other languages that are supported by the Unicode format.
1.3
1.3.1 GDSII import

FDTD Solutions can now import GDSII files. The GDSII files use a standard data format
to store 2D geometric data. These files can be imported to create complex multi-layered
structures in your simulations. For more information, see the GDS Import 84 section.
1.3.2 Improved figure windows

Control over the figure window color map has been expanded. The color map limits can
now be adjusted. This is useful when creating several images with a consistent color
map. A grey scale color map is also available, which is useful when creating figures to be
printed in black and white. See the figure window 103 page for more details.
1.3.3 n and k import

The import structure, used to import physical structure data from a file, has been
expanded. Refractive index (n and k) data as a function of space (3D) can be imported
from a file or matrix. See the nk import 39 page in the simulation objects chapter for
more details.
1.3.4 Set view and orbit

The setview 177 command gives the user complete control over the perspective view
window. The orbit 178 command will view the current simulation objects in an elliptical
orbit. This can make viewing the simulation objects easier. Movies of the orbits can also
be created.
New Features
15
1.3.5 Surface imports

The import structure, used to import physical structure data from a file, has been
expanded. Surface data of the form y = f(x) or z = f(x,y) can be imported from a file or
matrix. This data can be generated from an analytic formula or from an experimental
source such as an AFM. See the surface import 40 page in the simulation objects
chapter for more details.
1.3.6 Windows Vista support

Windows Vista has been added to the list of supported systems. For details on installing
the correct version for your hardware and operating system (OS), please see the
Installation Manuals.
1.4
1.4.1 Graded mesh

FDTD Solutions now supports a non-uniform, or graded, mesh. This can dramatically
increase speed and accuracy for many problems, as well as reducing the memory
requirements. Please refer to the simulation tab 33 section of the simulation objects
chapter.
1.4.2 Polygon and triangle primitives

FDTD Solutions now supports extruded N-sided polygons and triangles. For details,
please see the physical structures 34 section of the simulation objects chapter.
1.4.3 Quadrics and Infinipath interconnects

FDTD Solutions now supports even more high performance computing (HPC) networking
interconnects, including Quadrics and Infinipath. Please see the Installation Manual for
details on configuring your installation for your HPC hardware.
1.4.4 Native support for the Windows x64 platform

FDTD Solutions has added a full Windows x64 application to the current Windows 32-bit
and Linux 32- and 64-bit versions. For details on installing the correct version for your
hardware and operating system (OS), please see the Installation Manuals.
1.4.5 Easier installation of parallel FDTD Solutions

Get your parallel FDTD Solutions up and running faster! The easy installation lets you
immediately take full advantage of your multi-core and multiprocessor systems, as well as
larger scale clusters.
16
Reference Guide
1.4.6 Meshing improvements

Each physical structure primitive can control its own mesh order (priority), making it
easier to draw complex, overlapping structures. Please see Mesh order 77 for details on
material meshing order.
Advanced users can now store the mesh from previous simulations and re-use it to save
meshing time. Please see Using the non-uniform mesh for details.
1.4.7 Faster drawing modes for all primitives

All physical structure primitives now support wireframe, vertex wireframe and pixel
drawing modes which can make the manipulation of large numbers of primitives more
convenient in the Layout Editor. Please see Physical Structures 34 for details.
1.4.8 Simulation auto shutoff

Simulations can detect when the electromagnetic fields have decayed and automatically
terminate the simulation early.
1.4.9 Improved movie monitors

The movie monitors now support mpeg movies of |E|2 and |H|2 and well as the usual
electromagnetic field components. The user can now choose the final movie resolution in
pixels for better viewing. Please see the monitors 58 section of the simulation objects
chapter for details.
The physics of the FDTD algorithm
17

The finite-difference time-domain (FDTD) method1,2 has recently become the
start-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, 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.
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).
2.1
FDTD and Maxwell's equations

Consider Maxwell's curl equations in non-magnetic materials:
where H, E, and D are the magnetic, electric, and displacement fields, respectively, while
is the complex relative dielectric constant (
, where n is the refractive
index).
In three dimensions, Maxwell equations have six electromagnetic field components: Ex, E
y, 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
then Maxwell's equations split into two independent sets of equations composed of three
18
Reference Guide
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:
FDTD Solutions can solve two and three dimensional Maxwell equations in linear and
non-linear dispersive 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
22 for more details.
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 72 for details.
Boundary conditions are very important in electromagnetics and simulation techniques.
FDTD Solutions supports a range of boundary conditions, such as PML, periodic, and
Bloch. See the boundary conditions 45 section here for the complete list.
Sources are another important component of a simulation. FDTD Solutions 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
19
softwares. Detailed information about each of these sources is contained in the Radiation
sources 49 section.
Unless otherwise specified, all quantities in FDTD Solutions are calculated in SI units.
Please see Units and Normalization 20 for more information.
The online User Guide at www.lumerical.com/fdtd_online_help 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.
20
Reference Guide
Units and normalization

Unless specified explicitly in a GUI window, FDTD Solutions uses SI Units at all times.
The following table summarizes the units used in FDTD.
Please note that some quantities can be returned in either the Continuous Wave
Normalization state (cwnorm) or the No Normalization state (nonorm). Please see
Frequency domain normalization 22 for details on the different normalization states. For
most applications, the default cwnorm state is the best choice.
To see the data available in a source or monitor, use the script command
?showdata 180 ("monitorname");
All data can be obtained in scripting, with commands such as getdata 181 , getelectric
getmagnetic 182 and transmission 216 .
182
Quantity
Description
Norm
state
Units
Unit description
E(t)
Electric field as function

of time
N/A
V/m
Volts per meter
|E(t)|2
Electric field intensity as

a function of time
N/A
(V/m)2
Volts squared per

meter squared
H(t)
Magnetic field as a
function
N/A
A/m
Amperes per meter
|H(t)|2
Magnetic field intensity

as a function of time
N/A
(A/m)2
Amperes squared per

meter squared
Electric dipole in 3D
N/A
Cm
Coulomb meters
Magnetic dipole in 3D
N/A
Am2
Ampere meters
squared
Electric field in 2D
N/A
Cm/m
Coulomb meters per

meter
Magnetic dipole in 2D
N/A
Am2/m
Ampere meters
squared per meter
f=w/2p
Frequency
N/A
Hz
Hertz
E(w)
Electric field as a function cwnorm V/m

of angular frequency
|E(w)|2

a function of angular
frequency
cwnorm (V/m)2
Volts per meter

Volts squared per
meter squared
3.1
21
H(w)
Magnetic field as a
function of angular
frequency
cwnorm A/m
Amperes per meter
|H(w)|2

as a function of angular
frequency
cwnorm (A/m)2
Amperes squared per

meter squared
P(w)
Poynting vector as a
function of angular
frequency
cwnorm W/m2
Watts per meter

squared
Power(w)
Power as a function of
angular frequency
cwnorm W
Watts
Power(w)
2D Power as a function
cwnorm W/m
Watts per meter
E(w)
Electric field as a function nonorm

V/m/Hz
Volts per meter per

Hertz
|E(w)|2

a function of angular
frequency
nonorm
(V/m/Hz)2
Volts squared per

meter squared per
Hertz squared
H(w)
Magnetic field as a
function of angular
frequency
nonorm
A/m/Hz
Amperes per meter

per Hertz
|H(w)|2

as a function of angular
frequency
nonorm
(A/m/Hz)2
Amperes squared per

meter squared per
Hertz squared
P(w)
Poynting vector as a
function of angular
frequency
nonorm
W/m2/Hz2
Watts per meter

squared per Hertz
squared
Power(w)
Power as a function of
angular frequency
nonorm
W/Hz2
Watts per Hertz

squared
Power(w)
2D Power as a function
nonorm
W/Hz2/m
Watts per Hertz

squared per meter
Source amplitudes
Dipole sources
Dipole source amplitudes are
Cm for 3D electric dipole sources
Am2 for 3D magnetic dipole sources
Cm/m for 2D electric dipole sources
Am2/m for 2D magnetic dipole sources
22
Reference Guide
Other sources
When specifying the amplitude for non-dipole sources, the "amplitude" refers to the peak
electric field amplitude in units of V/m. For example, if a Gaussian beam has the following
electric field distribution in time and space:
Then the "amplitude" refers to the value of E0 and has units of V/m.
3.2
Frequency domain normalization

The frequency power and frequency profile monitors record the electric and magnetic
fields at a series of user-defined frequencies. These can be returned in either the
Continuous Wave Normalization state (cwnorm), or the No Normalization state (nonorm
). For most applications, the default cwnorm state is the best choice.
In the nonorm state, the returned fields are simply the Fourier transform of the simulated
time domain fields, and we use the subscript sim to refer to these fields in the table
below. In the cwnorm state, the fields are normalized by the Fourier transform of the
source pulse, thereby yielding the impulse response of the system, and we use a
subscript imp to refer to these fields in the table below.
Quantity
Definition
Normalization
state
Esim(w)
nonorm
Hsim(w)
nonorm
Psim(w)
nonorm
Eimp(w)
cwnorm
Himp(w)
cwnorm
Pimp(w)
cwnorm

s(w)
23
N/A
, where sj(t) is the
source time signal of the jth source and N is the number
of active sources in the simulation volume
Understanding Continuous Wave Normalization (cwnorm)

Impulse response
FDTD is a time domain method. The electromagnetic fields are calculated as a function
of time. In FDTD Solutions, the system being simulated is excited by a dipole, beam,
mode or imported source. In FDTD Solutions, the time signal of the source, s(t), is a
pulse. For example, this could be
and the Fourier transform of s(t) is s(w)
Ideally, s(t) would be a dirac delta function (in which case s(w) = 1). This would allow us
to obtain the response of the system at all frequencies from a single simulation. For a
variety of reasons, it is more efficient and numerically accurate to excite the system with a
short pulse such that the spectrum, |s(w)|2, has a reasonably large value over all
frequencies of interest.
In the nonorm state, power and profile monitors in FDTD Solutions return the response
of the system to the simulated input pulse s(t):
The simulated electric field as a function of angular frequency, Esim(w), depends on both
the source pulse used, s(t), and the system under study.
In the default cwnorm state, power and profile monitors in FDTD Solutions return the
impulse response of the system.
The impulse response of the system is a much more useful quantity because it is
completely independent of the source pulse used to excite the system.
Example
Consider a beam source injected into free space at z=z0. The source signal is
24
Reference Guide
The electric field at the source injection plane has the following form:
In the cwnorm state,

In other words, the field returned in the cwnorm state is the field that would exist if a CW
source of amplitude E0 had been used at the angular frequency w. It removes any
frequency dependence due to the finite pulse length of the source, and the units of the
returned fields are the same as time domain fields.
3.3
Spectral averaging
For some simulations, it is useful to calculate the incoherent spectral average of the
electromagnetic fields or the Poynting vector. For example, we might want to calculate
where W(w) is a weighting function and Pimp(w) is the Poynting vector returned in the
cwnorm state, in other words, the impulse response of the system. (Please see
Frequency domain normalization 22 for an explanation of the impulse response.) We
could calculate the Pimp(w) at many different angular frequencies and then perform the
spectral average after the simulation. FDTD Solutions, however, allows for two methods
of more efficient spectral averaging during the simulation which can significantly reduce
the memory requirements and increase the speed of the simulation. These methods are
called "total spectral averaging" and "partial spectral averaging".
The frequency power and frequency profile monitors can record spectral averages of
various quantities during the simulation. Like the other quantities calculated by these
monitors, these can be returned in the Continuous Wave Normalization state (cwnorm),
or the No Normalization state (nonorm). For most applications, the default cwnorm state
is the best choice. In the tables below, we use the subscripts sim and imp to refer to the
quantities returned in the nonorm and cwnorm states respectively. Please refer to
Frequency domain normalization 22 for more details on the two normalization states, and
obtaining the impulse response of the system.
Total spectral averaging
FDTD Solutions supports a spectral average that uses the source input spectrum as the
weighting function. Total spectral averaging can be useful when the source spectrum of
the simulation matches the actual illumination conditions. The following table gives the
precise definitions of the quantities available using total spectral averaging.

Quantity
Definition
25
Normalization
state
<|Esim|2>total
nonorm
<|Hsim|2>total
nonorm
<Psim>total
nonorm
<|Eimp|2>total
cwnorm
<|Himp|2>total
cwnorm
<Pimp>total
cwnorm
s(w)
N/A
source time signal of the source and N is the
number of active sources in the simulation volume
jth
Total spectral averaging can be turned on by selecting total spectral average as shown in
the screenshot below.
26
Reference Guide
To see the data available in a monitor, use the script command

All data can be obtained in scripting, with commands such as getdata 181 and
transmission_avg 217 . The available components for total spectral averaging are shown in
the following table.
Quantity
Data name
Example script command
<|Exsim|2>total
E2x_avg
nonorm;
E2x = getdata("monitor1","E2x_avg");
<|Eysim|2>total
E2y_avg
nonorm;
E2y = getdata("monitor1","E2y_avg");
<|Ezsim|2>total
E2z_avg
nonorm;
E2z = getdata("monitor1","E2z_avg");
<|Hxsim|2>total
H2x_avg
nonorm;
H2x = getdata("monitor1","H2x_avg");
<|Hysim)|2>total
H2y_avg
nonorm;
H2y = getdata("monitor1","H2y_avg");
<|Hzsim)|2>total
H2z_avg
nonorm;
H2z = getdata("monitor1","H2z_avg");
<Pxsim>total
Px_avg
nonorm;
Px = getdata("monitor1","Px_avg");
<Pysim>total
Py_avg
nonorm;
Py = getdata("monitor1","Py_avg");
<Pzsim>total
Pz_avg
nonorm;
Pz = getdata("monitor1","Pz_avg");
<|Eximp|2>total
E2x_avg
cwnorm;
E2x = getdata("monitor1","E2x_avg");

<|Eyimp|2>total
E2y_avg
cwnorm;
E2y = getdata("monitor1","E2y_avg");
<|Ezimp|2>total
E2z_avg
cwnorm;
E2z = getdata("monitor1","E2z_avg");
<|Hximp|2>total
H2x_avg
cwnorm;
H2x = getdata("monitor1","H2x_avg");
<|Hyimp|2>total
H2y_avg
cwnorm;
H2y = getdata("monitor1","H2y_avg");
<|Hzimp|2>total
H2z_avg
cwnorm;
H2z = getdata("monitor1","H2z_avg");
<Pximp>total
Px_avg
cwnorm;
Px = getdata("monitor1","Px_avg");
<Pyimp>total
Py_avg
cwnorm;
Py = getdata("monitor1","Py_avg");
<Pzimp>total
Pz_avg
cwnorm;
Pz = getdata("monitor1","Pz_avg");
27
Partial spectral averaging

FDTD Solutions supports a spectral average that uses a Lorentzian weighting function
multiplied by the source spectrum. Partial spectral averaging is useful to extract the
average response of the system to a variety of different illumination conditions from a
single simulation. The following table gives the precise definitions of the quantities
available using partial spectral averaging.
Quantity
Definition
<|Esim(w)|2>
Normaliza
tion state
nonorm
partial
<|Hsim(w)|2>
nonorm
partial
<Psim(w)>partial
nonorm
28
Reference Guide
<|Eimp(w)|2>
cwnorm
partial
<|Himp(w)|2>
cwnorm
partial
<Pimp(w)>partial
cwnorm
|h(w,w')|2
N/A
s(w)
N/A
source time signal of the source and N is the number of
active sources in the simulation volume
jth
Partial spectral averaging can be turned on by selecting partial spectral average as shown
in the screenshot below.
29
The FWHM of |h(f,f')|2 is called d, and can be modified as shown below.
Please note that when considered as a function of angular frequency, the FWHM of
|h(w,w')|2 is 2pd rad/seconds.
To see the data available in a monitor, use the script command
All data can be obtained in scripting, with commands such as getdata 181 and
transmission_pavg 217 . The available components for total spectral averaging are shown
in the following table.
Quantity
Data name
Example script command
<|Exsim(w)|2>
E2x_pavg
nonorm;
E2x = getdata("monitor1","E2x_pavg");
E2y_pavg
nonorm;
E2y = getdata("monitor1","E2y_pavg");
E2z_pavg
nonorm;
E2z = getdata("monitor1","E2z_pavg");
H2x_pavg
nonorm;
H2x = getdata("monitor1","H2x_pavg");
H2y_pavg
nonorm;
H2y = getdata("monitor1","H2y_pavg");
H2z_pavg
nonorm;
H2z = getdata("monitor1","H2z_pavg");
<Pxsim(w)>partial
Px_pavg
nonorm;
Px = getdata("monitor1","Px_pavg");
<Pysim(w)>partial
Py_pavg
nonorm;
Py = getdata("monitor1","Py_pavg");
<Pzsim(w)>partial
Pz_pavg
nonorm;
Pz = getdata("monitor1","Pz_pavg");
partial
<|Eysim(w)|2>
partial
<|Ezsim(w)|2>
partial
<|Hxsim(w)|2>
partial
<|Hysim(w)|2>
partial
<|Hzsim(w)|2>
partial
30
Reference Guide
<|Eximp(w)|2>
E2x_pavg
cwnorm;
E2x = getdata("monitor1","E2x_pavg");
E2y_pavg
cwnorm;
E2y = getdata("monitor1","E2y_pavg");
E2z_pavg
cwnorm;
E2z = getdata("monitor1","E2z_pavg");
H2x_pavg
cwnorm;
H2x = getdata("monitor1","H2x_pavg");
H2y_pavg
cwnorm;
H2y = getdata("monitor1","H2y_pavg");
H2z_pavg
cwnorm;
H2z = getdata("monitor1","H2z_pavg");
<Pximp(w)>partial
Px_pavg
cwnorm;
Px = getdata("monitor1","Px_pavg");
<Pyimp(w)>partial
Py_pavg
cwnorm;
Py = getdata("monitor1","Py_pavg");
<Pzimp(w)>partial
Pz_pavg
cwnorm;
Pz = getdata("monitor1","Pz_pavg");
partial
<|Eyimp(w)|2>
partial
<|Ezimp(w)|2>
partial
<|Hximp(w)|2>
partial
<|Hyimp(w)|2>
partial
<|Hzimp(w)|2>
partial
3.4
Calculating and normalizing power in the

frequency domain
The complex Poynting vector
can be used to calculate the power flow in a particular direction; the user can also
calculate this quantity from the frequency-dependent fields of frequency monitors. The
time-averaged power flowing across a surface is given by
Note that the propagating power is proportional to the real part of the Poynting vector
only, which is related to the conservation of energy for the time-averaged quantities. The
factor of 1/2 is related to the time averaging of the CW fields. The imaginary part of the
Poynting vector relates to the non-propagating reactive or stored energy, such as one
might find in the evanescent tail of light being reflected by total internal reflection (TIR).
Please see J. D. Jackson, "Classical Electrodynamics, Second Edition", John Wiley &
Sons, 1975 for further details.
As an example, if one simulates a y-propagating source such as a Gaussian bream
31
striking a circular rod in a 2D TM simulation, then by placing a frequency power or profile

monitor on the opposite side of the rod, the normalized transmission, T, as a function of
frequency can be calculated with:
FDTD Solutions provide many GUI and scripting functions to make transmission
calculations easily at the press of a button or using a single command. The transmission
script command will perform this particular calculation.
3.5
Integrating over lines, surfaces and

volumes
The electric and magnetic fields are recorded on the FDTD mesh, as shown below for a
2D monitor, where the grey dots represent the positions where the fields are recorded.
The thick black outline shows the limits of the surface monitor as seen in the Layout
Editor. This monitor has an x-span of 12dx and a y-span of 5dy. This monitor records a
total of 13x6 data points.
A typical calculation with this monitor might be to integrate the total power flow across the
surface of the monitor, or
In order to calculate this quantity, we provide the scripting function integrate. If Pz is a

variable of dimension 13x6x1, and x and y are the corresponding position vectors, then
the desired quantity is:
power = 0.5*integrate(real(Pz),1:2,x,y);
The integrate script command can be used to integrate over spatial dimensions even
when several frequency points have been recorded. For example, if Pz is a variable of
dimension 13x6x1x10, representing 10 frequency points, then the following can be used
32
Reference Guide
to integrate over y (ie dimension 2) and then x (ie dimension 1)
power = 0.5*integrate(real(Pz),1:2,x,y);
power will be a matrix of dimension 10x1.
Simulation objects
33
Simulation objects
There are four types of simulation objects:
Physical structures
Structure objects are used to model the physical structure
of the device.
Simulation objects
The simulation region defines simulation parameters like
boundary conditions and mesh size.
Radiation sources
Radiation sources create the incident radiation
Measurement monitors
Monitors, located on the fourth tab, are used to collect data
from the simulation.
The CAD environment for FDTD solutions contains four main tabs: one for each group of
simulation objects. A simulation object can be added from by selecting the tab of the
group to which it belongs, and then clicking on the button for that simulation object. The
buttons for the simulation objects are located along the top of the tab. For example, in the
screen shot below, the monitor group tab is selected. Clicking on the
add a time monitor object.
button would
Once the object is selected (refer to the Getting Started section for more information),
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 time monitor is
shown below.
TIP: In-field equation interpreter
34
Reference Guide
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. For more information, see the Equation interpreter 65 section.
Notes:
Structure objects support Multi-object editing. If you select multiple objects then click
EDIT, you can edit all properties that are common to all selected objects.
Monitors and sources have global properties. For example, the global source frequency
range will apply to all sources. The global properties can be edited with the GLOBAL
PROPERTIES
button. See the first figure above.
Structures and monitors can be organized in groups. Groups are created using the
GROUP
icon, located to the right of the simulation object buttons.
The purpose of this section of the Reference Guide is to describe all of the available
simulation objects and groups, and their properties. This section is organized as follows.
There are five subsections. The first four subsections correspond to the four types of
object groups. Each of these sections begins with a brief overview of the simulation
objects that are available. Then, the properties of the simulation objects are described.
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.
4.1
Structures tab
The layout tab includes options to add the following physical 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 cubes of
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
Simulation objects
35
are connected with straight lines. For 3D simulations, the object is extruded in the z
dimension.
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.
Custom Primitives
Custom primitives can be used to create customized surfaces, specified via parametric
equations. The resulting surfaces can either exist on one or more faces of the object, or
can be used to define a cylindrically-symmetric surface of revolution.
Import Objects
Import primitives can be used to import material data from external data files. There are
three types of data that can be imported using links in the Import Data tab 38 :
SURFACES, for example from an atomic force microscope (AFM). In two dimensional
simulations, the data must be defined as y = f(x). In three dimensional simulations, it
must be defined as z = f(x,y). Both upper and lower surfaces can be imported.
IMAGES in JPG or PNG format, for example from an scanning electron microscope
(SEM). In three dimensions, the imported data is extruded along the z axis.
The REFRACTIVE INDEX (N AND K) as a function of space, for example, to represent
doped material where the doping concentrations and optical loss are calculated in
another software package. In two dimensions, the data is defined as n(x,y), k(x,y) and
in three dimensions as n(x,y,z), k(x,y,z). Please note that the value of k is translated
into a conductive (or plasma) model and is only valid at a the center frequency of the
simulation. It should therefore only be used with single frequency simulations.
Surface
Surface primitives can be used to define complex material volumes that exist above or
below analytically defined surfaces. In 3D simulations, a surface (S) is defined as a
function of variables u and v, i.e. S = S(u,v). The variables (u,v) can represent (x,y), (x,z)
or (y,z) depending on the surface orientation. Similarly, in 2D simulations, a surface is
defined as a function of u (S = S(u)) where u can represent x or y.
36
Reference Guide
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.
Structure Group
Structure groups are used to organize, edit and set up composite systems of objects.
Structure groups contain variables and scripts that can be utilized to edit and set up parts
of the structure. See the Properties tab 42 and Script tab 43 sections for more
information. It is possible to create groups of groups.
4.1.1 Geometry tab

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

The material options are as follows
MATERIAL: This field can be set to any material included in the material database. If
<Object defined dielectric> is selected, then the index property must be set. It is
possible to include new materials in the database, or edit the materials already
included. See the material database section for more information.
INDEX: The refractive index of the structure, when the material type is <Object defined
dielectric>. The index must be greater than one, and can be specified in terms of an
equation in terms of x, y, z, f, w, l0, and k0 (which are defined in the Equation
interpreter 65 section).
INDEX UNITS: This setting is only used when INDEX is entered as an equation. The
units of the spatial variables when the index is specified with a formula. The origin is the
center of the object. The units will affect the interpretation of l0 and k0.
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 77 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 mesh order for the currently chosen material from the material database.
Simulation objects
37
4.1.3 Rotations tab

Rotate objects by setting the following variables:
FIRST, SECOND, THIRD AXES: 3D simulation only. 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. In 2D simulation, only one angle (rotated around z axis) is
required.
4.1.4 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 and 1 for the object, depending on how transparent you
want the object to be.
4.1.5 Custom tab

The custom tab is only available for custom primitives. Custom primitives are objects that
are defined by equations describing the boundaries of the physical object. The custom
primitive defaults to a rectangular region upon creation, and is shaped via entry of one or
more equations in the edit window. Custom primitives in 3D simulations are extruded in
the z direction to a specific height, or can be rotated about the x-axis to create a surface
of revolution.
EQUATION 1: The equation, expressed as a function of x, which defines the upper y
edge of the physical object. The origin of equation is the center of the object. Suitable
syntax for the equations is shown in the Equation interpreter 65 section.
Note: Equation definition changed between release FDTD 6.0 and FDTD 6.5
The location of the origin for custom objects was changed between FDTD 6.0 and 6.5.
Equations in custom objects created with FDTD 6.0 or earlier will be automatically
converted to the new definition.
MAKE NONSYMMETRIC: Uncheck this if you want to define the lower edge with a
different equation.
EQUATION 2: The equation, expressed as a function of x, which defines the lower
38
Reference Guide
edge of the physical object.
EQUATION UNITS: The default units in which x and y are expressed in equation 1 and
2. For example, a setting of microns means that both x and y are expressed in
microns.
CREATE 3D OBJECT BY: Options include "extrusion", and "revolution". Extrusion
results in an object that is extruded along the z-axis (i.e. invariant in z). The revolution
object is created by revolving the equation around the x-axis, resulting in a surface of
revolution.
Equation 1 and 2 are bound such that they are only defined over specific regions.
Equations which result in undefined values (1/0) result in a zero height; any equation left
blank results in a custom primitive of zero height everywhere. Equations that go larger
than the span of the object will be clipped at the edge of the object. Equations that go
negative will be clipped at zero. In the following figure, notice how the equations are
clipped at the edge of the object.
4.1.6 Import Data tab

The import data tab is only available for import objects. Data is imported by the buttons
located in the Import region of this tab. All related options are described below:
Import
IMPORT TYPE: This field is inactive, but tells the user which data has been imported.
SURFACE: This button opens the surface import window, which is described in the
Surface import 40 section.
IMAGE: This button is used to launch the image import wizard which provides a simple
interface to import, threshold, crop and scale the image. The image is used to define
the objects shape in the XY plane. The object is extruded in the Z direction. Images can
be imported from JPG (*.jpg) or PNG (*.png). Other image types can be exported to
these two formats in most image viewing software. Detailed instructions for the Import
Wizard can be found on the Import object images page in the User Guide section of the
Online help.
(N,K) MATERIAL: This button is used to launch the n,k import window, which is
described in the nk material import 39 section.
CLEAR ALL DATA: Deletes any previously imported data. This returns the primitive to
the state it was in prior to importing any data.
Simulation objects
39
Fine scale adjustments

XSCALE, NOT UNIFORM SCALING, Y SCALE, Z SCALE: These parameters are used
to scale the overall imported data by either a constant value in both the x and y
directions, or in different amounts for each direction. This can be used to correction for
a tilted image, for example.
ADJUST IMAGE SCALE: This button is used to launch the fine tune image scale
wizard. This allows you to graphically retune the scale for image imports, and adjust for
image tilt. The fine tune image scale wizard is explained in detail below and can only be
used after importing image data.
Data size
DATA X POINTS, DATA Y POINTS, DATA Z POINTS: The number of pixels in each
direction contained in the original file read in.
DX, DY,DZ: The size of each pixel, scaled to the overall dimension of the simulation
region.
Image only
THRESHOLD: This is the threshold used to import the data for image imports
Surface only
LOWER REF HEIGHT: When surface data is imported, it is defined with respect to a
reference height or zero plane. This zero plane can be changed in the global
coordinates of the Layout Editor. This field is only active if surface data has been
imported.
UPPER REF HEIGHT: The same as the LOWER REF HEIGHT but for the upper
surface.
REF HEIGHT SPAN: The distance between the LOWER REF HEIGHT and the UPPER
REF HEIGHT. This is useful for conformal layers to ensure that the layer thickness is
correct. This field is only active if surface data has been imported
4.1.6.1 nk material import window
Options in the (n,k) material import window include:

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 SPAN, Y SPAN, Z SPAN: This defines the size of volume that you are importing.
These fields are inactive and help to determine that the file units have been properly
chosen.
FILE UNITS: Select units for the data in your file.
IMPORT AS Mji INSTEAD OF Mij: 2D simulation only. It is often easy to cycle through
the array indices in the wrong order when exporting the file, and this check button
allows you to reverse the order easily. Typically, it is very easy to see in the figure
window when you have the order incorrect.
IMPORT AS Mkji INSTEAD OF Mijk: 3D simulation only. It is often easy to cycle
through the array indices in the wrong order when exporting the file, and this check
40
Reference Guide
button allows you to reverse the order easily. Typically, it is very easy to see in the
figure window when you have the order incorrect.
PLOT PLANE: You can image the data in either the x-y plane, the x-z plane or the y-z
plane to be sure that it is correctly imported. Use this menu chooser to switch between
planes.
Z (or X or Y): Depending on the PLOT PLANE chosen, you can view cross sections at
any depth into the structure. Use this slider or the value input field to choose the depth
of cross section.
IMAGE N, IMAGE K: Choose to view n or k in the figure window.
For detailed information and example text import files, as well as script files that generate
the example files, see the Import object spatial (n,k) data page in the User Guide section
of the Online help.
4.1.6.2 Surface import window
Options in the surface import window include:

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 SPAN: This defines the length of surface that you are importing. If the x data was
contained in the file (file format type 1), then this field is inactive. If the x data was not in
the file, then this field is active and should be set to the desired data span.
YSPAN: 3D simulation only. This defines the size of surface area 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.
For detailed information and example text import files, as well as script files that generate
the example files, see the Import object surfaces page in the User Guide section of the
Online help.
Simulation objects
41
4.1.7 Surface tab

The diagrams below show how the surface is used to create a volume of desired
material.
The surface equation can contain up to three terms, conic, polynomial and custom which
are added together to create the total surface. Not all terms have to be included.
Conic term:
c = 1/Rc is the inverse of the radius of curvature of the surface at r = 0.

k is the conic constant. When k=-1 we have a parabolic surface. When k=0 we have
a spherical surface.
r2 = u2 + v2 in 3D simulations and r = u in 2D simulations.
Polynomial term:
There are 6 M coefficients in 2D simulations and 36 in 3D simulations

Custom term:
42
Reference Guide
You can choose any analytic function of u in 2D simulations and (u,v) in 3D
simulations.
The syntax and functions available to specify the index are found in the Equation
interpreter 65 section.
For example, you could use
The surface tab contains the options:

ORIENTATION: The surface determines if S is a function of (x,y), (x,z) or (y,z) in 3D
simulations and (x) or (y) in 2D simulations.
ZERO PLANE: This determines if surface is measured from the lower edge of the
rectangular volume or the upper edge. See diagrams above.
MATERIAL POSITION: This determines if the material fills the regions above the
surface or below the surface. See diagrams above.
SET UNDEFINED TERMS TO: It is possible that the surface equation becomes
undefined. For example, it could be sqrt(-1) for some values of (u,v). In this case, the
surface function will become either zero or the maximum value allowed by the
rectangular volume encompassing the surface object.
U0, V0: The origin of the (u,v) coordinate system, If U0, V0 are zero, then (u,v) = (0,0)
will correspond to the center of the surface object. Setting these values to non-zero will
offset the origin by a desired amount.
SURFACE UNITS: All quantities defining the surface must be measured in the same
units. You can choose these units with this menu.
CONIC: Check this option to include the conic term in the surface equation. If this is
checked, then set
RADIUS OF CURVATURE: curvature of the surface at the origin. This is equal to
the inverse of the parameter c described in the definition of Sconic.
CONIC CONSTANT: The k constant.
CUSTOM: Check this option to include the custom term in the surface equation
EQUATION: The equation as a function of u in 2D simulations or u and v in 3D
simulations.
POLYNOMIAL: Check this option to include a polynomial term in the surface equation.
If this option is checked, the M coefficients as explained above can be entered into a
table.
4.1.8 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
Simulation objects
43
page of the User Guide section of the Online Help.
4.1.9 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 106 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.
4.2
Simulation tab
Simulation objects are used to define simulation parameters like boundary conditions and
mesh size.
The simulation region defines most simulation parameters including the size,
boundary conditions, mesh size, and simulation time.
The mesh override region is used to override the default mesh size in some part of
the simulation region. Normally the meshing parameters are set based on the Mesh
accuracy slider in the Simulation region setup. However, if some specific meshing
conditions are required in part of the simulation region, a mesh override region can be
specified. For example, some simulations with metals are very sensitive to meshing, and
a mesh override region may be required at the metal surface.
Note that only one simulation region per simulation is supported, but multiple mesh
override 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
44
Reference Guide
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.
4.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 two settings:
BACKGROUND INDEX: The refractive index of the surrounding, background medium
in the simulation region.
SIMULATION TIME: The maximum duration of the simulation to be performed. The
actual simulation may be shorter if the autoshutoff criteria are satisfied before this
maximum simulation time is exceeded. For more information about how to choose the
simulation time see set the simulation region section of the introduction in the Getting
Started guide.
Mesh override region
For the mesh override region the general tab includes options to override the mesh in
different directions, and enter the desired maximum mesh spacing. Alternatively, since
the mesh spacing is usually determined by the refractive index of the materials in the
simulation, it is possible to set an EQUIVALENT INDEX that will be used to determine the
mesh spacing. A higher index will lead to a finer mesh.
4.2.2 Geometry tab

The geometry tab contains options to change the size and location of the simulation or
mesh refinement region.
4.2.3 Mesh settings tab

The mesh settings tab includes settings which control the mesh geometry and the
discretization of time. There are three different types of meshes. The options for each are
described in more detail below. Then, the time step options are discussed.
Auto non-uniform
The default setting. A non-uniform mesh is automatically generated based on the mesh
accuracy slider bar and the material properties. Areas with a high index will have a
smaller mesh step size.
The MESH ACCURACY parameter is an integer from 1-8, where 1 is low accuracy, and 8
Simulation objects
45
is high accuracy. It is strongly recommended that you start with a low accuracy setting so
your simulation is fast. Once the simulation is setup properly, you should perform some
convergence testing with different mesh sizes to ensure your result is converged.
Custom non-uniform
This setting allows the user to fully customize how the non-uniform mesh is generated. If
setting the mesh cells using wavelength, the default setting of 10 is sufficient in general,
but may be reduced to 6-8 for coarse simulations.
The grading factor determines the maximum rate at which the mesh can be modified. For
example, if dx(i+1) = a*dx(i), then 1/(GRADING FACTOR) <= a <= GRADING FACTOR.
The grading factor should be between 1 and 2. The default setting is sqrt(2).
Uniform
A uniform mesh is applied to the entire simulation volume, regardless of any material
properties.
Time Step Options
DT STABILITY FACTOR: A setting which determines the size of the time step used
during the simulation, defined as a fraction of the Courant numerical stability limit. A
larger number will result in faster simulation times, and a smaller number will result in
slower simulation times. The Courant stability condition requires that this setting must
be less than 1 for the FDTD algorithm to remain numerically stable.
DT: The time step of the FDTD simulation. This is determined by the values of the
spatial grid to ensure numerical stability and cannot be directly set by the user.
4.2.4 Boundary conditions tab

The boundary conditions that are supported by FDTD Solutions are listed below with an
image showing how that particular boundary condition is drawn in the CAD window.
PML
Many simulations employ absorbing boundary conditions that allow radiation to propagate
out of the computational area without interfering with the fields inside. Perfectly matched
layer (PML)3 boundaries absorb electromagnetic energy incident upon them. PML is most
effective when absorbing radiation at normal incidence; it can have significant reflection at
grazing incidence. Increasing the PML thickness (number of layers) will reduce
reflections, but increase the simulation time and memory requirements.
Metal
Metal boundary conditions are used to specify boundaries which are perfectly reflecting,
allowing no energy to escape the simulation volume along that boundary.
46
Reference Guide
Periodic
Periodic BC should be used when both the structures and EM fields are periodic. Periodic
boundary conditions can be used in one or more directions (i.e. only in the x direction) to
simulate a structure which is periodic in one direction but not necessarily other directions.
Bloch
Bloch BC should be used when the structures are periodic, and the EM fields periodic,
except for a phase shift between each period. Bloch boundary conditions are used
predominantly for the following two simulations:
Launching a plane wave at an angle to a periodic structure in this situation, accurate
reflection and transmission data can be measured at a single frequency point for a
given simulation.
Calculating the bandstructure of a periodic object in this situation, a broadband pulse
is injected via a dipole source into a periodic structure.
Symmetric
Symmetric boundary conditions are used when the user is interested in a problem that
exhibits one or more planes of symmetry. Both the structure and source must be
symmetric. Symmetric boundaries are mirrors for the electric field, and anti-mirrors for
the magnetic field. A visual explanation of a symmetric boundary condition is shown in the
figure below. Careful consideration must be given to whether symmetric or asymmetric
boundary conditions are required, given the vector symmetry of the desired solution. For
meaningful results, the sources used must have the same symmetry as the boundary
conditions. Further information about symmetric and asymmetric boundary conditions can
be found in the online help in the section user guide - simulation - Choosing between
symmetric and anti-symmetric BCs.
Simulation objects
47
Asymmetric
Asymmetric boundary conditions are used when the user is interested in a problem that
exhibits one or more planes of symmetry. Asymmetric boundaries are anti-mirrors for the
electric field, and mirrors for the magnetic field.
3 J. P. Berenger, J. Comput. Phys. 114, 185 (1994).
Boundary condition tab options
XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX BOUNDARIES: These fields describe the
boundary conditions to be applied along the perimeter of the simulation region.
Symmetric and asymmetric boundary conditions should be applied to the lower
boundary conditions.
ALLOW SYMMETRY ON ALL BOUNDARIES: By default, symmetric and
anti-symmetric conditions can only be used on the lower boundaries (x min, y min and z
min). This box allows you to also use symmetry and anti-symmetric conditions on the
upper boundaries in order to simulate periodic structures that exhibit symmetry.
SET BASED ON SOURCE ANGLE: Bloch boundary conditions are often used to inject
plane waves on angles into periodic structures. This option will determine the values kx,
ky and kz for you based on the source in your current simulation. Note that if more than
one source is defined, all sources must require consistent Bloch settings. By default,
this box is checked. If you uncheck the box, you should set kx, ky and kz directly.
BLOCH UNITS: Two types of units are allowed for specifying the values of kx, ky and
kz:
o bandstructure: In these units kx,y,z are defined in units of (2p/ax,y,z) where ax,y,z is the
x,y or z span of the FDTD simulation region. These units are very convenient for
bandstructure calculations.
o SI: In SI units, kx,y,z are defined in units of m-1. This is generally more convenient for
injection of plane waves on angles.
48
Reference Guide
KX, KY, KZ: The wavevector setting in the x, y and z direction for the Bloch boundary in
the units specified above.
4.2.5 Advanced options tab

WARNING: This tab includes options which should only be changed if you are quite
familiar with the FDTD technique.
USE MESH REFINEMENT: Mesh refinement can be used to average the material
properties near interfaces. Increasing the mesh parameter improves the accuracy for
dielectric structures, but also increases the time required to mesh. Default value is off.
The MESHING REFINEMENT parameter determines how accurately the physical
structures are discretized near interfaces. Each cell within the grid is subdivided into a
sub-grid over which the average permittivity is determined. The number of sub-cells
along each side of the cell is given by the meshing precision parameter. Increasing the
mesh parameter improves the accuracy for dielectric structures, but also increases the
time required to mesh. The default meshing precision value is 5 in 3D and 10 in 2D.
FORCE SYMMETRIC X, Y, Z MESH: Will force a symmetric mesh about the x, y or z
axis. When this option is enabled, the meshing algorithm ONLY considers objects in
the positive half of the simulation region. The mesh in the negative half is simply a
copy of the positive half mesh. All physical structures and mesh override regions in the
negative half will not be considered by the meshing algorithm. This option also forces a
mesh point at the center of the simulation region. Forcing a symmetric mesh ensures
that the mesh does not change when going from a simulation with symmetry to a
simulation without symmetry.
ALWAYS USE COMPLEX FIELDS: This checkbox forces the algorithm to use complex
fields during simulation. This will result in slower simulation times and increased
memory requirements and should only be used when necessary. Without this, complex
fields are only used when there are Bloch boundary conditions.
USE EARLY SHUTOFF: Will automatically end the simulation when most of the energy
has left the simulation volume.
o AUTO SHUTOFF MIN: The simulation will end when the total energy in the
simulation volume drops to this fraction of the maximum energy injected. The
simulation data will automatically save.
USE DIVERGENCE CHECKING: Will automatically end the simulation when the total
energy in the simulation volume is this many times larger than maximum energy
injected.
o AUTO SHUTOFF MAX: The simulation will end when the total energy in the
simulation volume rises to this many times the maximum energy injected. The
simulation data will automatically save.
DOWN SAMPLE TIME: Check the auto shutoff conditions every down sample time
number of dT time steps
PML KAPPA: The normalized imaginary electric and magnetic conductivity used in the
PML boundaries.
PML SIGMA: The maximum normalized electric and magnetic conductivity used in the
PML boundaries.
PML LAYERS: The number of cells which are used for PML boundary conditions.
Simulation objects
4.3
49
Increasing this number will reduce the back-reflection arising from the PML boundaries
but will also increase time and memory requirements for simulations. Defaults to a
setting of 12.
PML POLYNOMIAL: The polynomial power which determines how rapidly the electric
and magnetic conductivity increases as radiation propagates at normal incidence into
the PML. The default setting of 3 denotes a cubic increase of electric and magnetic
conductivity with increasing depth into the PML.
TYPE OF PML: The type of PML used can be STANDARD, STABILIZED or DEFAULT
CHOICE. In some cases, STABILIZED PML provides more numerical stability,
although the performance is slightly reduced.
MAX SOURCE TIME SIGNAL LENGTH: This is the maximum length of data used by
sources to store the time and time_signal properties of sources. If a large number of
sources are used and the simulation time is on the order of 100ps (which is very rare),
advanced users may want to reduce this to save memory. However, since the time
and time_signal properties of sources are important for calculating the sourcepower,
sourcenorm, and the normalization for the transmission functions, care must be taken
with source normalization. In particular, in most cases, nonorm option should be used.
SET DEFAULTS: Can be used to reset the settings back to their original default
settings.
Sources tab
The layout tab includes options to add the following sources:
Global source options

The global source options window is where the user can specify the frequency-domain
parameters. These settings can be used by any of the frequency domain sources.
Point sources
Point sources are oscillating dipoles that act as sources in Maxwell's equation to produce
electromagnetic fields. Their position and direction are specified in terms of the center
position (x, y, and z for 3D simulations) and their orientation through angles phi
(measured in the x-y plane with respect to the x-axis) and theta (measured from the
z-axis). They can be placed at one or more points anywhere in the simulation area.
For two-dimensional simulations, the behavior of point sources depends on whether you
are performing a TE or a TM simulation. For a TE simulation, a magnetic dipole is
oriented in the z-direction, while an electric dipole is oriented in the x-y plane by the
ANGLE argument, which specifies the angle measured with respect to the x-axis. For a
TM simulation, an electric dipole is oriented in the z-direction, while a magnetic dipole is
oriented in the x-y plane with the same ANGLE argument describing the direction of the
dipole vector.
50
Reference Guide
Gaussian and thin lens sources

A Gaussian source defines a beam of electromagnetic radiation propagating in a specific
direction, with the amplitude defined by a Gaussian cross-section of a given width. By
default, the Gaussian sources use a scalar beam approximation for the electric field
which is valid as long as the waist beam diameter is much larger than the diffraction limit.
The scalar approximation assumes that the the fields in the direction of propagation are
zero. For highly focused beam, FDTD Solutions provides a thin lens source which will
inject a fully vectorial beam. The cross section of this beam will be a Gaussian if the lens
is not filled, and will be a sinc function if the lens is filled. In each case, the beams are
injected along a line perpendicular to the propagation direction, and are clipped at the
edges of the source.
Note: References for the thin lens source
The field profiles generated by the thin lens source are described in the following
references. For uniform illumination (filled lens), the field distribution is precisely the
same as in the papers. For non-uniform illumination at very high NA, there are some
subtle differences. This is due to a slightly different interpretation of whether the
incident beam is a gaussian in real space or in k-space. This difference is rarely of any
practical importance because other factors such as the non-ideal lens properties
become important at these very high NA systems.
M. Mansuripur, "Distribution of light at and near the focus of high-numerical-aperture
objectives," J. Opt. Soc. Am. A 3,2086-2093 (1986).
M. Mansuripur, "Certain computational aspects of vector diffraction problems," J. Opt.
Soc. Am. A 6, 786-805 (1989).
M. Mansuripur, "Distribution of light at and near the focus of high-numerical-aperture
objectives: erratum, Certain computational aspects of vector diffraction problems:
erratum" J. Opt. Soc. Am. A 10, 382-383 (1993).
Plane wave sources

Plane wave sources are used to inject laterally-uniform electromagnetic energy along one
side of the source region. In two-dimensional simulations, the plane wave source injects
along a line, while in three-dimensional simulations the plane wave source injects along a
plane. It is possible to inject a plane wave at an angle. The plane wave source is actually
the same object as the gaussian source. The only difference is the SOURCE SHAPE
setting.
Total-field scattered-field sources

Total-field scattered-field sources are used to separate the computation region into two
distinct regions one contains the total field (i.e. the sum of the incident field and the
scattered field) while the second region contains only the scattered field. The incident field
is a plane wave with a wavevector normal to injection surface. This source type is
Simulation objects
51
particularly useful to study the scattering behavior of objects, as the scattered field can be
isolated from the incident field.
In 2D, the TFSF source injects along one edge of a rectangle as specified by the user.
The other three boundaries subtract the incident field (allowing for the wave propagation).
Everything inside the TFSF boundary is total field (i.e. incident + scattered field), while
everything outside is only scattered field. In the absence of any objects, the wave
propagates within the TFSF region and is subtracted out at the other end; this of course
results in no scattered field. However, if one places an object in the path of the TFSF
wave, this introduces scattered fields that then propagate outside the total field area.
Consequently, one can then measure the total or scattered transmission, by placing
monitors inside or the total field region, respectively. Currently, only normal incidence
plane waves are supported as the incident field.
TIP: Using TFSF sources
TFSF sources can be used when:
the source can completely surround the scattering objects in a homogeneous
material (including materials with complex index).
the scattering object is on or in a multilayer slab that is illuminated from above.
Certain boundaries of the TFSF can be dragged outside the simulation area
boundaries, for example, when symmetric or anti-symmetric boundary conditions are
used in the simulation. For advanced use of TFSF sources, please consult an
application example or technical support at support@lumerical.com.
Note:
Some care is needed when using the TFSF source. The concept of total/scattered field
is complex and can lead to misinterpretation of results, particularly with regards to
energy conservation.
Mode sources
The mode source is used to inject a guided mode into the simulation region. The extent of
the region defining the mode source (i.e. center location, and span) is that used in the
computation of the guided modes for the structure. In three-dimensional simulations, the
mode source defines a plane across which the guided modes are computed, while in
two-dimensions the mode source defined a line across which the guided modes are
computed. From the computed guided modes, a single mode is selected for injection into
the FDTD simulation region. For additional details on the operation of the mode solver,
consult the integrated mode solver section 67 .
Imported sources
The imported source allows the user to input field profile data as a radiation source within
the three-dimensional FDTD Solutions design environment. Currently, ASAP sources
52
Reference Guide
(produced with Breault Research Organizations ASAP ray-tracing design environment)
can be used as an imported source.
Imported sources are only available in 3D simulations.
4.3.1 General tab

The information located on the general tab depends on the type of monitor chosen. The
settings in these tabs are outlined below.
Dipole sources
DIPOLE TYPE: A pull-down menu in which the point source can be configured as an
electric dipole or a magnetic dipole.
AMPLITUDE: The amplitude of the point source. The units of the source depend on the
dipole type, as explained in the Units and normalization 20 section.
BASE AMPLITUDE: This is the amplitude that will generate a radiated CW power of 10
nW/m in 2D simulations and 1 fW in 3D simulations.
TOTAL AMPLITUDE: This is the amplitude actually used in the simulations, it is the
product of the AMPLITUDE and the BASE AMPLITUDE.
PHASE: The phase of the point source, measured in units of degrees. Only useful for
setting relative phase delays between multiple radiation sources.
THETA: 3D simulations only. The angle with respect to the z axis of the dipole vector
PHI: 3D simulations only. Angle with respect to positive x axis of the dipole vector.
POLARIZATION: 2D simulations only. The polarization of the simulation to be
performed. The user has the option of either a TE simulation in which the electric field
lies within the plane of the drawing palette, or a TM simulation in which the magnetic
field lies within the plane of the simulation region.
Gaussian, plane wave and TFSF sources
(Some of the options below are not available for the TFSF source)
SOURCE SHAPE: The shape of the beam. This setting defaults to Gaussian, but for
convenience can be changed to that of a Cauchy/Lorentzian, or a plane wave.
AMPLITUDE: The amplitude of the source as explained in the Units and normalization
20 section.
PHASE: The phase of the point source, measured in units of degrees. Only useful for
setting relative phase delays between multiple radiation sources.
INJECTION AXIS: Sets the axis along which the radiation propagates.
DIRECTION: This field specifies the direction in which the radiation propagates.
FORWARD corresponds to propagation in the positive direction, while BACKWARD
corresponds to propagation in the negative direction.
ANGLE: 2D simulations only. The angle of propagation, in degrees, with respect to the
injection axis defined above. The angle must be between -89.9 and 89.9 degrees.
POLARIZATION: 2D simulations only. The polarization of the simulation to be
performed. The user has the option of either a TE simulation in which the electric field
lies within the plane of the drawing palette, or a TM simulation in which the magnetic
field lies within the plane of the simulation region.
Simulation objects
53
ANGLE THETA: 3D simulations only. The angle of propagation, measured in degrees,

with respect to the injection axis defined below.
ANGLE PHI: 3D simulations only. The angle of propagation, in degrees, rotated about
the injection axis in a right-hand context.
POLARIZATION ANGLE: 3D simulations only. The polarization angle defines the
orientation of the injected electric field, and is measured with respect to the plane
formed by the direction of propagation and the normal to the injection plane. A
polarization angle of zero degrees defines P-polarized radiation, regardless of direction
of propagation while a polarization angle of 90 degrees defines S-polarized radiation.
THETA VS WAVELENGTH PLOT: This plot shows the actual injection angle theta for
each source wavelength as used in the simulation.
Mode and imported sources
INJECTION AXIS: Sets the axis along which the mode source will propagate.
DIRECTION: This field specifies the direction in which the TFSF source propagates.
FORWARD corresponds to propagation in the positive direction, while BACKWARD
corresponds to propagation in the negative direction.
AMPLITUDE: The amplitude of the mode source as explained in the Units and
normalization 20 section.
SELECT MODE: Mode source only. Launches the mode solver and allows the user to
select the desired mode for injection. For more information on using the mode source,
consult the integrated mode solver 67 section of the reference guide.
CLEAR SOURCE DATA: Clears the selected mode for mode sources, or clears the
imported data for imported sources
PLOT: This menu allows you to choose which component of the field profile you would
like to plot.
PLOT CURRENT MODE/FIELD: This button will plot the field profile selected in the
PLOT pull down menu for the currently selected mode.
PLOT IN NEW WINDOW: This is the same as PLOT CURRENT MODE/FIELD but
opens a new window for the graphics that stays open even after property edit window is
closed.
Also for imported sources the following Imported source settings are available
X0, Y0, Z0: Displays the location in the imported source where the field was recorded.
IMPORTED INDEX: The refractive index of the background medium where the
imported field was recorded.
IMPORTED POWER: The power of the source recorded in imported.
IMPORTED WAVELENGTH: The wavelength of the imported source data.
IMPORT SOURCE: load an interface file (*.fld).
4.3.2 Geometry tab

The geometry tab contains options to change the size and location of the sources.
54
Reference Guide
4.3.3 Frequency/Wavelength tab

The Frequency/Wavelength tab is shown below. This tab can be accessed through the
individual source properties, or the global source properties. Note that the plots on the
right-hand side of the window update as the parameters are updated, so that you can
easily observe the wavelength (top figure), frequency (middle figure) and temporal
(bottom figure) content of the source settings.
At the top of the tab, it is possible to chose to either SET FREQUENCY / WAVELENGTH
or SET TIME-DOMAIN. If you choose to set the frequency or wavelength ranges to define
your sources, then FDTD Solutions tries to find the optimum time domain settings that will
cover the desired frequency/wavelength range without compromising accuracy. If you
choose to directly modify the time domain settings, please keep the following tips in
mind:
Pulse durations: Choose a pulse duration that can accurately span your frequency or
wavelength range of interest. However, keep in mind that very short pulses contain
many frequency components and therefore disperse quickly. As a result, short pulses
require more points per wavelength for accurate simulation.
Pulse offset: This parameter defines the temporal separation between the start of the
simulation and the center of the input pulse. To ensure that the input pulse is not
truncated, the pulse offset should be at least 2 times the pulse duration. This will
ensure that the frequency distribution around the center frequency of the source is
close to symmetrical, and the initial fields are close to zero at the beginning of the
simulation.
Source type: In general, you can choose between standard and broadband source
Simulation objects
55
types. Standard sources consist of a Gaussian pulse at a fixed optical carrier, while the
broadband sources consist of a Gaussian pulse with an optical carrier which varies
across the pulse envelope. Broadband sources can be used to perform simulations in
which wideband frequency data is required for instance, from 200 to 1000 THz. This
type of frequency range cannot be accurately simulated using the standard source
type.
Set frequency wavelength
If the SET FREQUENCY / WAVELENGTH option was chosen, this section makes it
possible to either set the frequency or the wavelength and choose to either set the center
and span or the minimum and maximum frequencies of the source.
Set time domain
The options in the time domain section are:
SOURCE TYPE: This setting is used to specify whether the source is a standard
source or a broadband source. The standard source consists of an optical carrier with a
fixed frequency and a Gaussian envelope. The broadband source, which contains a
much wider spectrum, consists of a chirped optical carrier with a Gaussian envelope.
When the user uses the script function setsourcesignal, this field will be set as "user
input".
FREQUENCY: The center frequency of the optical carrier.
PULSELENGTH: The full-width at half-maximum (FWHM) power temporal duration of
the pulse.
OFFSET: The time at which the source reaches its peak amplitude, measured relative
to the start of the simulation. An offset of N seconds corresponds to a source which
reaches its peak amplitude N seconds after the start of the simulation.
BANDWIDTH: The FWHM frequency width of the time-domain pulse.
Advanced
ELIMINATE DISCONTINUITY: Ensures the function has a continuous derivative
(smooth transitions from/to zero) at the start and end of a user defined source time
signal. By default, this option is enabled.
4.3.4 Beam options tab

This tab is only available for Gaussian sources. In the general tab, set the source shape
option to the desired shape (Gaussian, plane wave or Cauchy/Lorentzian) before entering
data in the beam options tab because the beam options that are available will change
depending on the source shape.
Beam options for all source shapes
CURRENT INDEX: This field shows the refractive index at the x,y (and z) position of
the beam.
BEAM PROFILE, PLOT: This menu allows you to choose which component of the field
profile you would like to plot.
SHOW/REFRESH: This button will update the current plot and the current index. The
56
Reference Guide
plot is not automatically updated because the thin lens calculations can be long.
PLOT IN NEW WINDOW: This is the same as SHOW/REFRESH but opens a new
window for the graphics that will persist after you close the property edit window.
Beam options for Gaussian and Cauchy/Lorentizian sources
USE SCALAR APPROXIMATION / USE THIN LENS: These checkboxes allow the user
to choose whether to use the scalar approximation for the electric field or the thin lens
calculation. Gaussian sources can be defined using either the scalar approximation or
thin lens calculation, whereas Cauchy/Lorentzian sources can only be defined using the
scalar approximation.
Scalar approximation
BEAM PARAMETERS: This menu is used to choose to define the scalar beam by the
WAIST SIZE AND POSITION or the BEAM SIZE AND DIVERGENCE ANGLE.
If WAIST SIZE AND POSITION is chosen, the options are:
WAIST RADIUS: 1/e field (1/e2 power) radius of the beam for a Gaussian beam, or a
half-width half-maximum (HWHM) for the Cauchy/Lorentzian beam.
DISTANCE FROM WAIST: The distance, d, as shown in the figure below. A positive
distance corresponds to a diverging beam, and a negative sign corresponds to a
converging beam.
If BEAM SIZE AND DIVERGENCE ANGLE is chosen, the options are:
BEAM RADIUS: 1/e field (1/e2 power) radius of the beam for a Gaussian beam, or a
half-width half-maximum (HWHM) for the Cauchy/Lorentzian beam.
DIVERGENCE ANGLE: Angle of the radiation spread as measured in the far field, as
shown in the figure below. A positive angle corresponds to a diverging beam and a
negative angle corresponds to a converging beam.
Thin Lens
NA: This is nsin(a) where n is the refractive index of the medium in which the source is
found and a is the half angle as shown in the figure below. Please note that the index
will not be correctly defined in dispersive media and lenses should only be used in
non-dispersive media. The refractive index for the source is determined at X, Y (and
Z).
DISTANCE FROM FOCUS: The distance d from focus as shown in the figure below. A
negative distance indicates a converging beam and a positive distance indicates a
diverging beam.
FILL LENS: Checking this box indicates that the lens is illuminated with a plane wave
which is clipped at the lens edge. If FILL LENS is checked, then it is possible to set the
diameter of the thin lens (LENS DIAMETER) and the beam diameter prior to striking
the lens (BEAM DIAMETER), as shown in the figure below. A beam diameter much
larger than the lens diameter is equivalent to a filled lens.
NUMBER OF PLANE WAVES: This is the number of plane waves used to construct
the beam. The beam profile is more accurate as this number increases but the
calculation takes longer. The default value in 2D is 1000.
Simulation objects
57
The figure below shows the beam parameter definitions for the scalar approximation
beam.
The figure below shows the beam parameter definitions for the thin lens, fully-vectorial
beam.
TIP: Setting Gaussian source parameters

Gaussian spot size: The beam spot size
can be set independently of the source
span. The source span should be chosen
to be larger than the beam spot size. If
there is significant intensity at the edges of
the source, as shown in this figure, the
beam will scatter on injection.
If the spot size is larger than the simulation
region, the beam profile will be truncated
at the simulation boundary.
4.3.5 Advanced tab

This tab only appears for the dipole source. The tab contains a RECORD LOCAL FIELD
checkbox. When checked, the fields around the dipole are saved; this box must be
checked in order to use the dipolepower script function.
58
Reference Guide
4.4
Monitors tab
The layout tab includes options to add the following monitors:
Global Monitor Properties

The global monitor options window is where the user can specify the range and resolution
with which to measure frequency-domain information. These settings can be used by any
of the frequency domain monitors.
Index Monitors
Index monitors records the n and k value as a function of frequency/wavelength in a
simulation. Index monitors are only available in two or three dimensions; there is no
option for linear or point index monitors. In the future, the index monitor will be able to
capture the time-evolution of the physical properties profile for nonlinear media.
Time-domain monitors
Time-domain monitors provide time-domain information for field components over the
course of the simulation. Time-domain monitors can consist of point, line, or area
monitors to capture this information over different spatial extents within the FDTD
simulation region. For the purposes of extracting line widths of resonant structures
through Fourier analysis, point time monitors with a down sample time of 1 are sufficient.
TIP: Using time monitors
Check the memory requirements when using 1D, 2D or 3D time monitors, since they
will generate large amounts of data. Consider using the temporal or spatial
downsampling options.
Movie monitors
Movie monitors capture a desired field component over the region spanned by the movie
monitor for the duration of the simulation. Movie monitors are only available in the two
dimensional variety. The resultant movies are saved with the same name as the monitor
in the current working directory.
TIP: CW Movies
It is possible to create a CW movie from profile or power monitor data. For more
information, see the online help at http://www.lumerical.com/fdtd_online_help/ and go to
the User Guide - Data Analysis section.
Note: Movie monitors are ignored when running parallel simulations.
When running a simulation in parallel, all movie monitors will be ignored. Constructing
Simulation objects
59
the movies from multiple processes running on different computers would add extra
communication and computation overhead, as well as be difficult to implement. There
is no workaround, except to run the simulation as a single process. This is generally not
a problem, since movie monitors are most useful for qualitative understanding only,
where a low resolution simulation is sufficient.
Frequency-domain profile monitors

Frequency-domain profile monitors provide a means to collect field profile and data in the
frequency domain from simulation data across some spatial region within the simulation.
Individual field components, poynting vector, and power flow can be collected as a
function of frequency and position.
These monitors are ideally used to collect field profile data for visualization and
customized analysis. Profile monitors will record field profiles exactly where they are
positioned. If highly accurate power measurements are required, power monitors should
be used, rather than profile monitors.
Tip: Using frequency monitors
Beware that frequency-domain field-profile monitors are computationally-intensive and
they can increase the simulation time considerably. When possible, try to use 1D or 2D
rather than than 3D monitors; if it is necessary to use the latter, try to restrict the
number of frequency points. We suggest experimenting with the spatial downsample
value(s) before doing long simulations and watch how long your simulation takes. If you
are only interested in the power flux, you can select only OUTPUT POWER in the Data
to record tab.
Frequency-domain power monitors

Frequency-domain power monitors provide a means to collect high-accuracy power flow
information in the frequency domain from simulation data across some spatial region
within the simulation. These monitors are identical to Frequency-domain profile monitors
except that they automatically snap to the nearest FDTD mesh cell boundary when the
simulation runs due to a different default setting of the SPATIAL INTERPOLATION
property in the advanced option. This is important when accurate power flow calculations
are required. Less interpolation is required in this case, which results in slightly more
accurate power measurements. Unfortunately, this means that the exact position where
the data is recorded will change whenever the mesh changes. If it is more important to
measure the field at a particular position, profile monitors should be used.
The precise location of where the monitor measures data during the simulation is
recorded with the monitor data in the x, y and z vectors.
Tip: When to use profile and power monitors
60
Reference Guide
Profile monitors: when it is most important to measure the fields at a very specific point
in space.
Power monitors: when it is most important to get the most accurate power
measurements.
TIP: Switching between power monitor and profile monitor
You can switch between frequency-domain power monitors and frequency-domain
profile monitors by changing the SPATIAL INTERPOLATION setting in the Advanced
Options tab. When the SPATIAL INTERPOLATION is set to NEAREST MESH CELL or
NONE, the monitor becomes a frequency-domain power monitor.
Analysis groups
Analysis groups are used to group, setup monitor groups and/or process monitor data.
The group object has a section that can contain code to set up the monitors, as well as a
section that can contain code to process monitor data once a simulation has been run
(this is why they are called analysis groups and not monitor groups). It is possible to
create groups of groups.
4.4.1 Frequency Power/Profile tab

This tab only appears for the global monitor settings, but includes the same options as
the general tab does for frequency domain power and profile monitors.
USE LINEAR WAVELENGTH SPACING: By default, data is recorded at linearly
spaced points with respect to frequency. Selecting this option spaces data at linearly
spaced points with respect to wavelength.
USE SOURCE LIMITS: When checked these monitors use the source limits. When
unchecked, the frequencies/wavelengths at which to record data can be set using the
pull down menus and boxes below them.
FREQUENCY POINTS: Set to choose the number of frequency points at which to
record data.
4.4.2 Frequency Power/Profile Advanced tab

This tab only appears for the global monitor settings. It contains advanced global settings
for frequency-domain monitors. Only the MIN SAMPLING PER CYCLE can be modified
by the user.
MIN SAMPLING PER CYCLE: This parameter determines the minimum amount of
sampling per optical cycle that can be used. By default, it is set at 2 (the Nyquist limit)
for optimum efficiency.
DESIRED SAMPLING: This converts the minimum points per optical cycle into an
actual sampling rate in Hz.
NYQUIST LIMIT: The Nyquist sampling limit is calculated based on the maximum
frequencies that may be present in the simulation volume.
ACTUAL SAMPLING: The actual sampling rate is the rate that will actually be used for
Simulation objects
61
the discrete fourier transforms (DFTs), taking into account the desired sampling rate,
the Nyquist limit and the time step, dt.
DOWN SAMPLE TIME: This is the time step downsampling.
4.4.3 General tab

The information located on the general tab depends on the type of monitor chosen. There
are 3 different possibilities. The settings in these tabs are outlined below.
Movie monitor
HORIZONTAL RESOLUTION: The horizontal width of the final movie, in pixels.
VERTICAL RESOLUTION: The vertical height of the final movie, in pixels.
SCALE: A dimensionless variable which defines how to scale the capture of the field
data, with the tendency that a scale factor too small will result in saturation of the
movie, while a scale factor too large will result in very faint radiation patterns. This
parameter may not be less than zero. Tip: for Gaussian pulses, this is best set to unity.
For dipole sources, it is typically on the order of 0.01 to 0.05. The monitor outputs its
maximum intensity at the end of the simulation in the variable Monitor Name_maxI.
Setting the scale factor to Monitor Name_maxI and rerunning the simulation will result
in a perfectly scaled movie.
DRAW STRUCTURE OUTLINE: A toggle which allows the user to superimpose an
outline of the refractive index profile on top of the movie. This can be used to aid in
visualization of where the radiation is located within the dielectric structure.
TM, TE FIELD COMPONENT: 2D simulations. The field component to be captured in
the movie. The choices depend on whether a TE or TM simulation is being performed,
as set out in the FDTD simulation region. If a TM simulation is being performed, the TM
field component is captured to the movie, whereas if a TE simulation is being
performed, the TE field component is captured. Can also be ELECTRIC FIELD
INTENSITY (|E|2) or MAGNETIC FIELD INTENSITY (|H|2).
FIELD COMPONENT: 3D simulations. The field component to be captured in the
movie. Can also be ELECTRIC FIELD INTENSITY (|E|2) or MAGNETIC FIELD
INTENSITY (|H|2).
Time-domain monitor
The general tab for the time domain monitor includes options to edit the amount of data,
and time period over which data is collected.
Index, frequency domain profile and frequency domain power monitors
OVERRIDE GLOBAL MONITOR SETTINGS: A toggle to override the global monitor
settings. If checked, the user can specify the frequency range and number of points at
which frequency-domain information will be recorded (using the options described
below). If unchecked the options below are set from the global monitor settings.
USE LINEAR WAVELENGTH SPACING: By default, data is recorded at linearly
spaced points with respect to frequency. Selecting this option spaces data at linearly
spaced points with respect to wavelength.
USE SOURCE LIMITS: When checked these monitors use the source limits. When
62
Reference Guide
unchecked, the frequencies/wavelengths at which to record data can be set using the
pull down menus and boxes below them.
FREQUENCY POINTS: Set to choose the number of frequency points at which to
record data.
4.4.4 Data to record tab

STANDARD FOURIER TRANSFORM: The monitor outputs data at specific
frequencies.
PARTIAL SPECTRAL AVERAGE:The monitor outputs the partial spectral average
power through a monitor surface, normalized to the partial spectral average of the
source.
TOTAL SPECTRAL AVERAGE:The monitor outputs the total spectral average power
through a monitor surface, normalized to the total spectral average of the source.
OUTPUT EX, EY, EZ, HX, HY, HZ, PX, PY, PZ: A set of fields with which the user can
select what field components (EX, EY, EZ, HX, HY, HZ) or Poynting vector (PX, PY,
PZ) to measure. In 2D simulations, only some components are non-zero (i.e. only EX,
EY, and HZ are applicable for TE simulations). All the field quantities remain active to
facilitate easy change between TE and TM simulations.
OUTPUT POWER: For surface monitors (3D) and line monitors (2D) only. You can
calculate the integrated power over the monitor surface. This requires much less
memory after the simulation is completed and is particularly suitable for large parallel
simulations where only the integrated power across a surface is required.
4.4.5 Geometry tab

The geometry tab contains options to change the size and location of the monitors.
The DOWNSAMPLE X, Y, Z option is used to set the spatial averaging performed on the
data. A down sample value of N corresponds to averaging over N grid points. Setting the
down sample value to 1 gives the most detailed spatial information (i.e. information at
each grid point).
4.4.6 Spectral averaging and apodization tab

PARTIAL SPECTRAL AVERAGING, DELTA: FWHM of the Lorentzian weighting
function.
APODIZATION: Specifies the window function of the apodization. Options include
none, start (i.e. beginning of time signature apodized), end (i.e. end of time signature
apodized, or full (i.e. both start and end). Note that apodization will, in general,
invalidate any source normalization performed and is therefore not suitable for accurate
power measurements.
APODIZATION CENTER, TIME WIDTH, FREQ WIDTH: See the diagram below for the
definition of these terms. The FREQ WIDTH corresponds to the effective bandwidth of
the full apodization window, as described under APODIZATION.
Note: Apodization functions
Simulation objects
63
Full apodization involves windowing the time-domain data on both the start and end
side. The resulting windowed data is then processed to produce frequency-domain
information.
Start apodization involves windowing the front side of the time-domain data. This can
be useful to exclude the initial source excitation from the frequency-domain data.
End apodization involves windowing the last part of the simulation. This can be useful
for ramping down the time-domain signal in devices where the radiation lives a long
time, like cavities.
4.4.7 Advanced tab

Time-domain monitors
SPATIAL INTERPOLATION: In FDTD generally, the electromagnetic field components
are not recorded at the same point in space. Instead each component of the vectorial
electric and magnetic fields are recorded at different locations in the Yee cell. In order
to properly calculate the Poynting vector and electromagnetic energy density, the fields
are interpolated to the same location in the Yee cell. This setting controls how the fields
are interpolated. Currently, the supported options for time monitors are NEAREST
MESH CELL and NONE. With NEAREST MESH CELL, the fields are interpolated to
the nearest FDTD mesh cell boundary. With NONE, no interpolation is performed and
each electromagnetic field component is recorded at a different position within the Yee
cell.
MIN SAMPLING PER CYCLE: This parameter determines the minimum amount of
sampling per optical cycle that can be used. By default, it is set at 10.
SAMPLING RATE: The actual sampling rate in Hz.
Frequency domain profile and power monitors
SPATIAL INTERPOLATION: This option is as described above for time domain
monitors
OVERRIDE ADVANCED GLOBAL MONITOR SETTINGS: When this option is selected
MIN SAMPLING PER CYCLE can be set. The other options cannot be altered, they are
there to display settings. For further details, see the descriptions in Frequency
Power/Profile Advanced tab 60 .
Movie monitors
MIN SAMPLING PER CYCLE: This parameter determines the desired amount of
64
Reference Guide
sampling per optical cycle.
SAMPLING RATE: This converts the minimum points per optical cycle into an actual
sampling rate in Hz.
FRAME RATE: The speed at which frames are displayed on the screen, in units of
frames per second. The default is 30.
Index monitors:
SPATIAL INTERPOLATION: There are three options for index monitors. The default
option, SPECIFIED POSITION returns the index that that the field sees at the location
where the monitor is placed. The next two options. NEAREST MESH CELL and NONE
are as described for time-domain monitors. In simulations with mesh refinement turned
on, the default option does not show the averaging of the indices, but the other options
do.
4.4.8 Setup tab

The setup tab is only available for analysis groups. The setup tab contains two further
tabs: the variables tab, and the script tab. The variables tab is identical to the properties
tab 42 for structure groups and the script tab is identical to the script tab 43 for structure
groups.
For more information and examples, see the Analysis groups page of the User Guide
4.4.9 Analysis tab

The analysis tab is only available for analysis groups. The analysis tab contains two
further tabs, the variables and the script tab. The variables tab is used to define the input
and output parameters of the script, and the script command contains script that can be
used to process the monitor data.
Variables tab
PARAMETERS: These are input parameters to the analysis script.
RESULTS: The output parameters are defined here. The analysis script must calculate
these quantities. Once the analysis script has been run, the results become monitor
data, that can be accessed using script commands in the same manner that monitor
data is accessed for simple monitors.
Script tab
The script has access to the input parameters defined in the variables tab, and can get
data from any of the monitors located in the group. However, it cannot get data from
monitors or sources not located inside that group. The script in the analysis groups does
not use the global variable space from the script prompt and script file editor. The results
from the script can be obtained in the script prompt by setting up output parameters in the
variables tab.
Simulation objects
65
The following buttons and regions are available in the script tab:
ANALYSIS SCRIPT: This is where the script commands are written. To find a list of
script commands, see the Scripting Language 106 section of the Reference Guide.
ANALYSIS SCRIPT OUTPUT: Press the RUN ANALYSIS button to run the script. If
there are no syntax errors in the script the SCRIPT OUTPUT will read <script
complete>. In addition, the analysis script output will contain any results from the "?"
script command.
RUN ANALYSIS: Pressing the run analysis prompt runs the analysis script and saves
the results. This button can only be pressed when the simulation is in analysis mode.
SAVE ANALYSIS: Pressing this button saves changed made to the analysis script
(even when in analysis mode).
For more information and examples, see the Analysis groups page of the User Guide
4.5
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 two tables provide a list of available operators and constants.
Operator category
Syntax
Algebraic
+, -, *, /
Trigonometric
sin(), cos(), tan()
Inverse trigonometric
asin(), acos(), atan(), atan2()
Hyperbolic trigonometric
sinh(), cosh(), tanh()
Power
^ or **
Exponential
exp()
Logarithmic (base 10, natural)
log10(), log()
Square root
sqrt()
Absolute
abs()
Mod
mod()
Variable or predefined
constant
Description
Units
66
Reference Guide
c
The speed of light in a

vacuum
m/s
pi
The variable p
none
Examples
2^10
sqrt(3)/exp(1)
sin(45*pi/180)
Index profile for <Object defined dielectric>

An additional set of variables are available when specifying the index profile of the
<Object defined dielectric> material definition. They are described in the following table.
Variable or predefined
constant
Description
Units
x, y, z
Position variables
as defined by user
The simulation center

frequency
f = (fmin+fmax)/2
Hz
The simulation center

angular frequency
w = 2*pi*f
Hz
l0
The free space wavelength

l0 = c/f
Length units as defined by

user
k0
The free space

wavenumber
k0 = 2*pi/I0
The inverse of the length

units defined by the user
Examples
sin(x)^2
exp(-x^2-y^2)
f/1e14
Integrated mode solver
67

This section describes the operation of the integrated mode solver to inject guided waves
into FDTD simulations. The mode solver itself uses the same discretization mesh as the
FDTD algorithm, so the profile of the guided modes as computed with the mode solver
naturally interface with the underlying FDTD mesh. Overall, this facilitates the injection of
guided modes with minimal back-reflection.
This section describes the operation of the mode solver once the physical structure and
the simulation region defining the structure of interest have been defined within the layout
editor. The mode source is launched by pressing the SELECT MODE button within the
mode source edit window. Following this, the mode source window appears with different
tabs. The following sections detail each tab within the mode solver window, and the
information which it contains.
Also see the MODE source
5.1
49
description in the Simulation objects chapter.
Mode analysis
The MODE ANALYSIS window is shown in the screenshot below. The upper left-hand
portion of the window contains the MODE PARAMETERS section, where the mode
number, effective index, propagation loss, and polarization (percentage of the mode
polarized TE; not valid for 3D simulations) are shown. The lower left-hand corner shows
the CALCULATION, ANALYSIS AND SELECTION OPTIONS; upon launch, the lower
left-hand portion of the window shows the default calculation parameters to be used to
simulate the structure. The right-hand portion of the window contains the PLOT AREA
where the simulation data is plotted, and the two drop-down boxes at the top of the plot
area are used to specify which data to plot in the plot window, while the region at the
bottom right can be used to modify the current mode plot options. Upon launch, the plot
area shows the refractive index profile of the structure being analyzed.
68
Reference Guide
Mode Parameters
The mode parameters portion of the window displays simulation data relevant to the
different modes calculated for the structure of interest. This portion of the window shows
the modes, arranged from top to bottom in terms of the highest effective index and
numbered sequentially. For each mode, this portion of the window shows the effective
index of the mode, the calculated loss (measured in dB per millimeter of propagation; only
valid for lossy materials), and the TE or TM fraction corresponding to the definition of TE
and TM in 2D FDTD. For 3D simulations, the TE or TM fraction is not displayed.
See the following sections for more information about the analysis and plot sections.
5.1.1 Plot and analysis options

The different plot and analysis options are shown in the partial screenshot below.
Available options include:
Set Calculation Parameters
View Current Parameters
Select Mode for Injection
69
Set Calculation Parameters

With the option pull-down box set to SET CALCULATION PARAMETERS, the lower
left-hand portion of the window displays the calculation parameters. A portion of the
screenshot which shows the calculation parameters is shown below. The parameters
are:
FREQUENCY: the frequency at which the modes are solved for.
WAVELENGTH: the wavelength at which the modes are solved for.
NUMBER OF TRIAL MODES: the number of modes to be calculated.
SEARCH NEAR N: Allows you to look for modes near a desired effective index.
o USE MAX INDEX: Search for modes near the maximum index found in the meshed
cross section.
o N: Choose the effective index to search for.
SEARCH IN RANGE: Allows you to search for modes in a desired range of indices.
o N1, N2: Define the range of indices to search over.
BENT WAVEGUIDE: Allows the user to specify a current radius of curvature for the
mode and solver for the modes of a bent waveguide.
o BEND RADIUS: the bend radius of the waveguide
o BEND ORIENTATION: the orientation of the radius of curvature. For example, for
propagation in the z direction, a bend orientation of 0 means that the waveguide is
70
Reference Guide
bent in the x-z plane. A bend orientation of 90 means that the waveguide is bent in
the y-z plane.
CALCULATE MODE: by clicking this button the mode solver will start the calculation for
the waveguide modes given the criteria above.
Note:
Any desired changes to the boundary conditions must be done by editing the simulation
region via the layout editor.
View current parameters
With the option pull-down box set to VIEW CURRENT PARAMETERS, the lower
left-hand portion of the window displays the current simulation parameters corresponding
to the modes that have been calculated. A portion of the screenshot which shows the
current parameters is shown below. The parameters are the same as for the SET
CURRENT PARAMETERS with the exception of:
CURRENT NUMBER OF MODES: the number of modes that have actually been
calculated
X, Y BOUNDARY MIN, MAX: the boundary conditions used on the x and y boundaries
Select Mode for Injection
With the option pull-down box set to SELECT MODE FOR INJECTION, the lower
left-hand portion of the window contains a button labeled SELECT MODE FOR FDTD
SOURCE. Pressing this button will initialize the mode source with the current mode
selected within the mode table in the upper left-hand portion of the window.
5.1.2 Plot area

The plot area portion of the window is where the simulation data is plotted, and where the
end user specified which simulation data to plot. The plot area consists of
Plot control pull-down boxes
Figure window
Mode plot options
Plot control boxes
The plot control portion of the plot area of the window is where the user specifies what
simulation data should be plotted within the plot area. The content to plot is specified by
two pull-down boxes:
PLOT: This pull-down allows the user to specify what general class of data to plot.
Available options include:
o MODAL FIELDS: allows the user to select various field quantities such as electric
and magnetic field amplitudes and intensities and Poynting vectors using the
COMPONENT pull-down
o MATERIAL PROPERTIES: allows the user to select various physical quantities such
as refractive index, permittivity, and conductivity using the COMPONENT pull-down
COMPONENT: This pull-down allows the user to specify which specific component is to
be plotted within the plot area. The available options depend on the setting of the PLOT
71
pull-down.
Figure window
The plot itself where the data appears is automatically labeled and scaled to fit the
simulation data. As with the layout editor, the plot can be zoomed using the standard
mouse actions. Note, however, that the mouse is automatically in the zoom state when
over the plotted data and therefore the keyboard shortcut Z is not necessary.
Mode plot options
The MODE PLOT OPTIONS can be set in the bottom right of the MODE ANALYSIS
window, the options are
LINEAR/LOG SCALE: determines whether the simulation data is plotted on a linear or
a log plot
SUPERIMPOSE STRUCTURE: toggles whether a black outline showing the physical
structure is superimposed on the simulation data
PLOT: indicates which part of complex-valued simulation data is to be plotted. Available
options include:
o AMPLITUDE
o PHASE
o REAL PART
o IMAGINARY PART
COORDINATES: currently supports only CARTESIAN coordinate system.
5.2
Advanced options
The ADVANCED OPTIONS tab has the following parameters:
MAXIMUM NUMBER OF MODES TO STORE: When searching for modes in a range
of effective indices from n1 to n2, it is possible to fill your available memory if too many
modes are found. For this reason, the maximum number of modes is limited and the
calculation will stop when this number of modes is exceeded.
USE SINGLE PRECISION: this can be used to save some memory during the
calculation of the modes but the results are less accurate.
AUTOMATICALLY REMOVE PML MODES/THRESHOLD FOR PML MODE
REMOVAL: In the future PML boundary conditions will be permitted in the integrated
mode solver. This setting can then be used, as in MODE Solutions, to remove
unphysical PML modes.
CONVERGENCE TOLERANCE: the convergence tolerance used for the calculations.
The default value corresponds to 1e-12 but can be increased by the user to speed
convergence or decreased to improve accuracy.
72
Reference Guide
Material database
This chapter details operation of the Material Database and Material Explorer.
Material Database
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.
Material Explorer
The Material Explorer is used to check the material fits that will be used in the simulation.
It is most important to check the fits when using the Sampled data material type, but the
Material Explorer can be used to check the fits for any material type. The Material
Explorer can be accessed through the Simulation menu.
6.1
Material database
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 physical object layout editor 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 Go to Material Explorer button on
the bottom left hand corner of the window to open the Material Explorer.
Material database
73
Import / Export material file

The import and export material file buttons can be used to import/export Material
Database Files (.mdf) files. mdf files can be used to transfer material data between
simulation files.
Material list
The material list shows all of the materials that are defined in the database. Many of the
material properties are editable. Double click on the table entry to change its value.
Property
No modification
No delete
Name
Mesh order
Color
Anisotropy
Description
These materials can not be modified. The default materials
included with the installation package can not be modified .
These materials can not be deleted. Materials that are
currently used in a simulation can not be edited.
The material name.
The mesh order. See the mesh order 77 section for more
information.
The color used to draw the objects in the CAD.
The type of anisotropy. See the Anisotropic materials 77
74
Reference Guide
Type
Last modified
Add
Delete
Copy
section.
The type of material model used. See the material models
section for more information.
The last modified date.
74
New materials can be added to the database. The material

model 74 must be selected.
Delete an existing material. Objects with the No delete flag
can not be deleted.
Copy an existing material. The materials included with the
installation package can not be modified. If a modification is
required, create a copy of the material. Copies of the materials
can be modified.
Material Properties
Material properties related to the model type are shown in the Model properties panel.
See the material models section for more information about these properties.
6.1.1 Models
This section describes the material models supported by the Material Database. Model
parameters can be edited in the Material property panel of the Material Database window.
Sampled data
The Sampled data model is used to import experimental material data. The experimental
data can be imported from a text file with the Import data... button.
The Sampled data material definition uses an automatic fitting routine to generate a multicoefficient material model of the experimental data over the frequency range specified by
the source.The fitting routine can use one of the models described below, or a more
generalized model. The fits can be checked and adjusted in the Material Explorer.
Tolerance - The desired RMS error between the permittivity of the experimental data and
the material fit. The fitting routine will use the least number of coefficients that produce a
fit with an RMS error less than the tolerance.
Max coefficients - The maximum number of coefficients allowed to be used in the
material fit. More coefficients can produce a more accurate fit, but will make the
simulation slower.
The following advanced options can be set in the Material Explorer:
Make Fit Passive - Set to be true to prevent the fit from having gain at any frequency. By
default this is true in order to prevent diverging simulations.
Improve Stability - If this setting is true, the fitting routine restricts the range of coefficients
Material database
75
in the fit in order to reduce numerical instabilities which cause simulations to diverge.
Imaginary Weight - Increasing the weight increases the importance of the imaginary part
of the permittivity when calculating a fit. A weight of 1 gives equal weight to the imaginary
and real parts of the permittivity.
Specify Fit Range - Set to true to decouple the bandwidth used to generate the material fit
and the source bandwidth. This option is used in parameter sweeps where the source
frequency is changed, and where it is important to keep the material parameters constant
over the whole parameter sweep. The fit range should cover the simulation bandwidth.
Bandwidth range - Bandwidth to be used for the fit when Specify Fit Range is true.
Dielectric
The Dielectric model is used to create a material with a constant real index. This material
will have the specified index at all frequencies (non-dispersive).
Refractive index - The refractive index of the material. Must be >= 1.
(n,k) material
The (n,k) material model is used to create a material with a specific value of n and k at a
single frequency.
Refractive index - Real part of the index at the center frequency of the simulation. Must
be > 0.
Imaginary refractive index - Imaginary part of the index at the center frequency of the
simulation. Positive values correspond to loss, negative values will produce gain.
NOTE: Single frequency simulations only!
This type of material model should only be used for single frequency simulations. The
implementation of the (n,k) material model is such that the material properties will only
be correct at the center frequency of the simulation.
Conductive
The Conductive model is used to create a material defined by the following formula.
Plasma
The Plasma model is used to create a material defined by the following formula.
Debye
The Debye model is used to create a material defined by the following formula.
76
Reference Guide
Lorentz
The Lorentz model is used to create a material defined by the following formula.
Sellmeier
The Sellmeier model is used to create a material defined by the following formula. The C
coefficients have dimensions of micrometers squared (mm2).
NOTE: Single frequency simulations only!

This type of material model should only be used for single frequency simulations. The
implementation of the Sellmeier model is such that the material properties will only be
correct at the center frequency of the simulation.
PEC
A Perfect Electrical Conductor (PEC). There are no parameters for this model.
Kerr nonlinear
In the Kerr nonlinear model, the electric polarization field P will depend on the electric field
E in the following manner.
Solving for the displacement field D gives
The relative permittivity and Chi3 values must be specified by the user.
PDLC (backwards compatibility mode)

The addition of combined Plasma, Debye, Lorentz and Conductivity (PDLC) models is no
longer supported in FDTD Solutions. For backwards compatibility with older versions,
these combined models will be created if an older fsp file containing a combined PDLC
material is opened. In most cases, these combined models were used to try and improve
fits to real experimental data or analytical models. Much better fits can now be obtained
automatically using the Sampled material models. The data used in these models can be
either experimental or created analytically.
To see an example of converting a PDLC model to the Sampled Data model, see the "
Material database
77
Importing arbitrary dispersive models" section of the FDTD Online Help (User Guide Structure and Materials)
6.1.2 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).
A typical example of the first
scenario is creating an "etch"
material which describes the
physical location where material
has been removed. In this case, the
user can define a material that
matches the background index.
The mesh order of this material
should have a lower numerical
value than the other materials.
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: Use an index monitor to confirm that the structures are meshed as intended.
6.1.3 Anisotropic materials

In general, anisotropic materials can be represented by a 9 element permittivity tensor eij
such that the electric and displacement fields are related by
where summation over j is implied on the right hand side. The full anisotropy tensor can
be written as
78
Reference Guide
FDTD Solutions currently allows for a diagonal permittivity tensor of the following form
To define an anisotropic material, set the Anisotropy field in the Material database to
Diagonal. The Material property editor will then have a property field for each direction.
When using the Material Explorer, you can select the component (x,y,z) of the permittivity
or index to plot.
Note:
When you rotate a geometric primitive, the permittivity tensor is not rotated.
6.2
Material Explorer
The Material Explorer is used to check the material fits that will be used in the simulation.
This is most important when using the Sampled data material type, although it can be
used to check material properties for all material types.
If the fit for a Sampled data material is not good enough, the Tolerance and Max
coefficient properties and the wavelength range of the source can be edited in the
Material Explorer.
Material database
Plot windows
The two figure windows at the top of the Material Explorer window show the real and
imaginary parts of the material index.
Fit and plot controls

Property
Material
Axis
Fit Tolerance
Max Coefficients
Show/Hide Advanced
Imaginary weight
Description
Select the material to check.
If the material is anisotropic, select the axis to check.
The Tolerance setting of the material. Only applies to
Sampled data materials.
The Max coefficients setting of the material. Only applies to
Sampled data materials.
Show or hide the advanced options.
Increasing the weight increases the importance of the
imaginary part of the permittivity when calculating a fit. A
79
80
Reference Guide
weight of 1 gives equal weight to the imaginary and real parts
of the permittivity.
Make fit passive
Check to prevent the material fit from having gain at any
frequency. By default this is checked in order to prevent
diverging simulations.
Improve stability
Check to restrict the range of coefficients in the material fit in
order to reduce numerical instabilities which cause simulations
to diverge.
Specify fit range
Decouple the bandwidth used to generate the material fit and
the source bandwidth.
Bandwidth range of fit
The frequency/wavelength range used for the fit if specify fit
range is selected. The bandwidth of the fit should cover the
simulation bandwidth.
Save fit parameters
Update the Material Database with the new Tolerance and
Max coefficients values.
Bandwidth units
Specify range in units of wavelength or frequency. Specify
range by Min/Max or Center/Span.
Bandwidth range
The frequency/wavelength range of interest. By default, this is
the source limits.
Save source bandwidth Update the source limits with these values.
Vertical axis
Plot permittivity or index
Show extended spectrum Plot the fit over a wider range.
Show material data
Show the experimental data on the plot windows
Fit and plot
Calculate the fit and plot data.
Plot in new window
Plots fit and data in a new window
Fit analysis
Property
RMS error
Number of coefficients
Description
The RMS error of the fit. The fitting algorithm will use the
minimum number of coefficients required to achieve an RMS
error less than the value specified by the Tolerance property of
that material.
The number of coefficients used in the fit.
CAD layout editor
81
CAD layout editor

The image below shows the graphical CAD Layout Editor of FDTD Solutions. CAD is the
graphical interface to FDTD Solutions. It is used to setup, and analyze simulations, and
to run all scripts.
In the screenshot below, different regions of the Layout Editor are circled. They include
Layout editor tabs and object tree
Main title bar
Toolbars
Script Prompt and Script Editor
View ports
Analysis Window
The following five section describe the first 5 regions. The Analysis window is discussed
in more detail in the analysis tools 99 section of the user guide. The final section
describes how to customize the window layout of CAD.
NOTE: Layout mode and Analysis mode

FDTD Solutions has two modes: Layout mode and Analysis mode. Layout mode is
used for setting up your simulation. Objects can be added, edited, and deleted in
Layout mode. After a simulation runs, CAD automatically switches to Analysis mode.
Once in Analysis mode, objects can not be edited, since we want the object settings to
match the values used in the simulation. In Analysis mode, data recorded by monitors
82
Reference Guide
in the simulation can be accessed and analyzed.
In order to edit an object, press the SWITCH TO LAYOUT
button. This will delete
all the simulation data, and return the simulation to layout mode. The image below
shows the CAD layout editor in analysis mode. Notice that the COPY, MOVE, DELETE,
etc, buttons are disabled.
7.1
Layout editor tabs and Objects tree

As previously discussed, a simulation requires that the user define a set of physical
structures, simulation region, radiation sources, and monitors. As a complete simulation
may contain a large number of objects, the layout tabs have been designed to facilitate
easy object manipulation by the end-user. There is one tab for each class of objects.
When one tab is selected, (eg sources), then all source objects are selectable and
editable. All other objects are inactive. This allows the user to more easily select a
particular object from the complete set of simulation objects. For example, a user wishing
to modify the location of the structure can select the Structures tab and thereby avoid
inadvertently selecting any other objects, such as radiation sources or monitors that may
be in close proximity to the dielectric structure of interest. See Simulation objects 33 for
lists of objects that can be added in each tab.
If a tab is selected, the corresponding group of objects will be visible in the objects tree. In
the same manner, if the name of the groups of objects is selected in the object tree, that
tab will be selected in the layout editor.
In the image below, the monitors tab is selected, and the monitor objects are visible in the
objects tree. Note that there are buttons located at the top of the objects tree. These
buttons can be used to hide or display objects, and move them up/down the tree or into
CAD layout editor
83
and out of groups.

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 clicking
on their name in the object tree with the mouse. In the image below, monitor2 is selected.
7.2
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 new files and save or load existing files. Note
that when creating a new file, there are three choices to determine how default settings
are chosen. More information regarding the default settings 86 is provided in the following
sections. The import option in the menu allows structures stored in GDSII files 84 to be
imported into the simulation.
Edit
The edit menu allows users to undo/redo their actions, and copy, paste and an option to
select all the objects in all of the tabs. It also contains all the options that are in the edit
toolbar. Note that in the edit bar, the copy and paste options are available, but the
duplicate option is not. Conversely in the edit toolbar the duplicate option is available,
copy and paste option is not. The duplicate tool has the same effect as copying and then
subsequently pasting.
View
84
Reference Guide
The view menu includes
the ability to choose the default layout of CAD
the ability to choose which windows, toolbars and structures are visible
the mouse mode toolbar options
the view toolbar options
Setting
This setting menu contains options to change the units used and the normalization of the
frequency domain data. More information regarding normalization is given in the
Frequency domain normalization 22 section in chapter3
Simulation
This menu is important since it contains option to change the settings used for parallel
computations. It also contains all of the options given in the simulation toolbar.
Help
The help menu contains update links and tells you which version of FDTD Solutions you
are running, including the expiry date of the license file in use. It also contains links to the
FDTD Online Help. The getting started and reference guide links will launch the .pdf copy
of these guides. Since the online version is the most current, we recommend that you use
the online version if you are connected to the internet.
7.2.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 in FDTD Solutions, 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

FDTD Solutions supports 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
CAD layout editor

Polygon
Yes
Path (see note below)
Yes
Node
No
Text
No
Symbolic cell reference
Yes
Array cell reference
Yes
85
Advanced
Cell references in external library/file
No
Magnifications in array and symbolic

references
No
Rotations and mirroring in array and

symbolic references
No
Note: Path corners

Path objects in GDSII files are piecewise linear lines plus a width and optionally some
information on how to handle the corners and ends. GDSII files support several corner
style options (rounded, squared, etc). The GDSII import function has limited support for
corner styles. All corners will be imported using the squared corner style.
Note: Flattened GDSII files
If you encounter problems importing a GDSII file, you may find better results if you
create a flattened GDSII file with the original software that you use to create the GDSII
file. Flattening a GDSII file removes features such as cell references, array references,
magnifications, and rotations.
GDSII Import
GDSII import is initiated by accessing the IMPORT->GDSII option from the FILE menu.
This will bring up a standard file browser which will allow you to select a GDSII file with
the extension .gds or .db. Selecting a GDSII file will bring up the Single layer GDSII
Import window as shown below.
86
Reference Guide
The following 3 input parameters control how the GDSII data is imported to FDTD
Solutions structures:
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 FDTD Solutions layout environment. These structures are
automatically put in 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 layer number from which they
came. 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.
7.2.2 Modifying your default settings

When creating a new simulation project using FILE -> NEW, there are three choices to
determine how default settings are chosen:
from default project: The settings for the new simulation project, including the default
materials, are loaded from the defaults settings files created when FDTD Solutions is
installed.
from current project: The settings for the new simulation project are preserved from
whatever is currently set before starting a new project. This includes any materials in
the current material database.
from existing project: A file browser allows you to select an existing *.fsp file to use as a
template for any default settings, including materials existing in that particular .fsp file.
Users may want to create a standard fsp file with all the settings and materials that are
normally used for their simulations. When starting FDTD Solutions, they can either
open this file and then select New->from current project, or
choose New->from existing project and then select this file to be used as a template.
CAD layout editor
87
Finally, it is sometimes useful to run a default script each time you start up FDTD
Solutions, for example, to change working directories to your home directory. Users can
save a script .lsf file called
C:\Program Files\Lumerical\FDTD\defaults\default.lsf (Windows)
/usr/local/Lumerical/defaults/default.lsf (Linux)
that will be automatically run each time FDTD Solutions opens.
7.3
Toolbars
There are 6 toolbars in CAD. For more information on the first four toolbars see the
following sections For information on the alignment toolbar see the User Guide in the
Online Help. The online help toolbar is self explanatory.
Edit toolbar
The edit toolbar contains tools used to edit simulation objects.
Mouse mode toolbar

The mouse mode toolbar changes what the mouse place holder looks like on the screen.
Depending on the mode of the mouse, the user can edit objects, move or zoom in on an
object in one or more view ports or measure the size of objects.
View toolbar
The view toolbar contains tools to zoom to the extents of objects, draw a grid and view
the mesh used for the simulation.
Simulation toolbar
The simulation toolbar contains tools to run the simulation and switch back to layout
mode.
Alignment toolbar
Alignment tools are only available when the structure tab is selected. The alignment
toolbar consists of six buttons that control the way in which objects can be accurately
positioned with respect to other objects. For example, these functions were used to align
the left edge of the circular objects with the left edge of the rectangle in the figure below.
88
Reference Guide
Online help toolbar

The online help toolbar can be used to quickly access the online help. Simply enter a
query in the online help toolbar and press on the magnifying glass. This will bring up the
search results in a new tab in current default browser if an instance of the browser exists,
and opens a new browser window otherwise.
7.3.1 Edit
The view tools are described below. 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
for information about the properties of each object.
33
chapter
Tip: Group edit of multiple objects

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
CAD layout editor
89
distance in each of the x,y,z dimensions. A pop-up window that appears has 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 array properties :
A1 LATTICE: the distance between the grid in the a1 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: fields which define the number of rows and columns which
comprise the array.
AZ LATTICE: the distance between 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 definition of these parameters in terms of the resulting array is shown in the diagram
below along with an example array properties edit window.
Delete (Del)
The delete command removes the currently selected object, or objects, from the
simulation.
7.3.2 Mouse mode

The four mouse modes are described below. 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.
90
Reference Guide
Select (S)
This functions 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 select tool is pressed or not).
For reference, the current location of the mouse within the view ports is shown in the
fields at the bottom left-hand corner of the CAD window (see the image below). The >
and < buttons at the right increase or decrease the number of decimal places shown in
these fields.
Zoom (Z)
This function sets the mouse to be in the zoom tool mode. The aspect ratio of the 2D
view port, and the XY view 3D, is maintained at 1:1, so there is no distortion and circles
are plotted as circles.
Pan view (P)

The pan view mode allows the user to drag the view. In the Perspective window, the pan
mode can be 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 right hand corner of the CAD window (see the image
above under the select mouse mode). 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.
7.3.3 View
The view tools are described below. When applicable, the shortcut key used to run the
function from the keyboard is given in brackets next to the name of the tool.
CAD layout editor
91
Zoom Extent (X)

Selecting this submenu item centers and scales the current view of the palette to show all
of the simulation objects that correspond to the current layout tab. For instance, selecting
zoom extent while the Structures tab is selected arranges the palette view such that all
the physical structures are shown, while other simulation objects may appear outside the
extent of the palette view. As mentioned above, this function is also accessed via
double-clicking either the left- or right-hand mouse button while in the zoom tool mode.
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
AZ LATTICED: the distance between the grid 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.
View simulation mesh

Selecting the "View simulation mesh" button will show the simulation mesh. Because
recalculating the mesh is somewhat computationally intensive, it is not continuously
updated. For example, the mesh will not update immediately if a physical structure is
moved. To have FDTD Solutions recalculate the mesh, click the "Recalculate simulation
mesh button" directly below the "View simulation mesh" button. The mesh is always
recalculated before a simulation starts.
Recalculate simulation mesh (F5)

This function will calculate and redraw the simulation mesh based on the current
simulation setup. The mesh is always recalculated before running a simulation.
7.3.4 Simulation
The simulation tools are:
Check memory requirements

This function will estimate the memory requirements for the current simulation. The total
92
Reference Guide
requirements are broken down into categories such as Simulation fields and Monitor data.
Material Explorer
The Materials Explorer can be used to check the material properties that will be used in a
simulation. For more information, please see the section on Material Explorer 78 .
Run FDTD
Run the current simulation in single process mode. If the current simulation project is not
saved, the application will prompt the user to save the project to a simulation project (.fsp)
file. For more information on running a simulation, consult the Running a simulation 96
section.
Run parallel FDTD

Run the current simulation in parallel mode. If the current simulation project is not saved,
the application will prompt the user to save the project to a simulation project (.fsp) file.
Before running a parallel simulation, the parallel options must be setup. The parallel
simulation feature is not available in the trial version of the program.
Run scripts
This function will allow the user to run a Lumerical script file (*.lsf) to perform
automated commands to, for example, run a series of simulations for parameter sweeps
or optimized device performance. 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 on button on the toolbar brings up an open file dialog, so that a file can
be chosen. Pressing the version of this button on top of the script editor runs the script
that is open in the script editor.
Switch to layout editor

This function returns the simulation environment back to the layout editor when in
analysis mode. If you switch to layout editor and then save the file, the data from the
simulation will be overwritten and lost.
7.4
View ports
The view ports show a graphical representation of all the simulation objects.
When running the mouse over the view port, it will either have the shape of an arrow, a
hand, a magnifying glass or a ruler. You can toggle between these by selecting a mouse
mode as described in detail in the toolbars section.
CAD layout editor
93
Selecting objects in the view ports

In order to select an object in a view port using the mouse, the layout editor must be in
the correct tab and the mouse must be in select mode (ie the mouse looks like an arrow).
When objects are selected, the vertices are drawn with red squares (also, the names are
highlighted in blue in the object tree).
Copying and Pasting from other simulations
It is possible to copy and paste between different CAD windows using the Ctrl+C and Ctrl
+V shortcut keys. If, the incorrect tab for the type of simulation object is selected in the
CAD window into which the object gets pasted, the correct one will automatically be set
when the paste command is carried out.
7.5
Script Prompt and Script Editor

The scripting language is useful for setting up complex structures, for data manipulation
and for parameter sweeps. Chapter 10 of the reference guide gives a list of all the script
commands, as well as examples of 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 bottom left hand corner 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 script commands 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, and then any other folders in the path, then the directory of the
script file.
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, the script prompt interpreter
automatically inserts 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.
7.6
Changing CAD layout

There are five pre-defined CAD layouts that can be accessed through main title toolbar.
Change between the default layouts by selecting the menu VIEW->SET DEFAULT
LAYOUT, and choosing one of them. In addition, users can hide or show more windows,
change the location of the the toolbars and some of the windows, and undock the
windows. The current window layout is saved when CAD closes so the next time you
open CAD, your previous window layout will be used.
Hiding/showing windows and toolbars
94
Reference Guide
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 have
check marks.
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 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
drag and drop the toolbar. If you reach a region where you can place a toolbar, the CAD
environment makes room for the toolbar, creating a blue void.
Moving and undocking windows
The object tree, script prompt, view ports and script editor may be undocked (the
perspective view port is undocked in the image below) by double clicking the name with
the left mouse button. This is particularly useful for the script file editor, since it can be
convenient to make the window quite large when writing script files. The object tree, script
editor and analysis window 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, they gain tabs on their
bottom left corner so that you can toggle between them.
Tip: Moving undocked windows in Linux
To reposition an undocked window on Linux operating systems, hold down the Alt key
before attempting to move the window.
CAD layout editor
95
96
Reference Guide
Running a simulation
When the desired physical structure, sources, monitors and simulation area have been
defined, it is possible to run the simulation. Selecting Run FDTD in the Simulation menu
or clicking on the RUN button in the toolbar will launch the simulation progress window. If
you have not already saved your simulation, you will be prompted to do so as you must
have a saved simulation project file in order to run a simulation.
The simulation progress window allows you to start, pause and exit simulations. Any
movie monitors will save to the filename you chose for the movie monitor. Closing the
simulation progress window or pressing the EXIT button will launch the data analysis
window (for further information, consult the section entitled The analysis tools 98 ).
The elements of the simulation launch window are as follows:

FDTD simulation file: This field tells you which file is currently being simulated.
GO: Use this button to launch or resume a simulation.
PAUSE: Use this button to pause a simulation that is in progress.
EXIT: Use this button to exit the current simulation. It will allow you to terminate a
simulation early, while still saving the data obtained up to that point.
Simulation status: This field updates the status of the simulation. Status values include
not started, running, paused or completed and saved.
Simulation time: This field tells you the current time of the simulation between time 0
and the maximum time set for the simulation.
Maximum time: This field reminds you of the maximum simulation time you set for the
simulation.
Maximum time remaining: This field tells the maximum REAL time, in hours, minutes
and seconds, that you have remaining. It is based on the time the simulation has taken
up to date.
Progress bar: The progress bar indicates how much of the simulation is complete, with
the length of the progress bar is determined by the maximum simulation time that you
have specified. The red line within the progress bar shows the amplitude of the radiation
pulse as a function of the simulation time. This is a useful visual guide to know when the
pulse has been injected, and how long the total simulation time is compared to the pulse
length.
Running a simulation
97
Note: More information

For more information about running FDTD simulations, including running on clusters,
using a job scheduler, preparing batch files, and using extra engine licenses, see the
Online Help. Go to the User Guide - Running Simulations section.
8.1
Running a simulation from the command

line
Sometimes it is convenient to run FDTD Solutions simulations that you have prepared in
advance without the CAD layout editor. You can run the FDTD simulation engine directly
from the command line with the command
FDTD [nw] [fullinfo] filename.fsp
The options are
-nw: run in no windows, or non-graphical interface mode. In no windows mode, the
following option is available:
-fullinfo: this will print more detailed time benchmarking information to the log file based
on walltime and cpu time measurements
Extra options for FDTD-par
The parallel executable of FDTD (FDTD-par) always runs in no windows or nongraphical mode so the nw flag does nothing.
FDTD-par also supports one additional flag:
-logall: this forces each process in the simulation to create a log file. Logfiles are
named filename_p0.log, filename_p1.log, filename_p2.log,... By default, only
filename_p0.log is created.
98
Reference Guide
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 98 . This is followed by two sections to familiarize the user
with the operation of the analysis routines. The first section entitled The analysis window
99 describes the analysis routine window and its various components. The second
entitled Analysis groups 101 describes the analysis tab of an analysis object. Finally, 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 103 section. The section entitled Data export 104 describes how 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 106 section.
9.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 FDTD simulation project (.fsp) file; even premature termination of a simulation results
in a partial dataset being written to the .fsp file. When the simulation completes and the
EXIT button is pressed, or the simulation is prematurely terminated by pressing the EXIT
button, the analysis tool is automatically launched.
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.
Analysis tools
9.2
99
The analysis window

An example analysis window is shown in the screenshot below.
As can be seen, the window itself is divided into four different sections where each is
described in turn below, together with the File item.
DATA TO ANALYZE: In this section, the user specifies which monitor data to analyze.
The top field, labeled Monitor consists of a pull-down menu in which the user selects
the simulation monitor to be analyzed. Depending on the monitor selected, various
other input fields in the analysis window will be active or inactive depending on its
relevance to the current monitor. For example, selecting a time-domain field monitor
will result in the frequency field becoming inactive as it is not relevant.
NORMALIZE MONITOR TO SOURCE POWER(DFT ONLY): Only applicable to
frequency-domain field monitors and power monitors. This option, when checked,
normalize the transmission data to the source power, rather than having the results
returned in Watts.
CONVERT FREQUENCY TO WAVELENGTH: This checkbox toggles between
displaying the data in wavelength or frequency units.
MONITOR PROPERTIES / FAR FIELD SETTINGS:
o MONITOR PROPERTIES The monitor properties contain information as to how the
particular monitor is to be analyzed. The monitor properties tab is more fully
discussed in the Monitor properties tab 100 section.
o FAR FIELD SETTINGS The far field settings tab is where the end-user sets the
properties that govern the far field transformation, including the resolution, which
100
Reference Guide
direction to project in, and so on. When plotting far field data, the data to output
setting in the monitor properties tab must be set to far field. The contents of the far
field settings tab is more fully discussed in the Far field settings tab 100 section.
PLOT DATA: The plot data section of the analysis window contains a button which,
when pressed, generates the desired plot in a new window as specified in the Data to
analyze and Monitor properties sections of the analysis window. Within the plot data
section of the analysis window, the user can specify whether to plot linear or log data.
EXPORT DATA: The export data section of the analysis window contains a filename
field in which the user specifies the filename to which the data subset is exported when
the Export button is pressed. For more information about this function, please contact
Lumerical Support.
9.2.1 Monitor properties tab

The monitor properties tab contains the following items:
DATA TO OUTPUT : This is where the user specifies what type of plot to generate.
Options include distributions as a function of
o space (line plots as a function of x, y, or z, or image plots in the x-y, x-z, or y-z
planes)
o time only available with time monitors
o frequency (via FFT of time monitors, or via frequency-domain monitors)
o far-field projection versus angle only available with frequency-domain monitors; the
settings for the far field projection are set via the far field settings tab, as discussed in
the next section
COMPONENT : This is the particular field component (|E|^2, |Ex|^2, |Ey|^2, |Ez|^2, |H|
^2, |Hx|^2, |Hy|^2, |Hz|^2, or the Poynting vectors real(Px), real(Py), real(Pz) for power
flow)
X, Y, Z : This is the spatial location at which to plot the data.
FREQUENCY : This is the frequency at which to plot the data (valid for frequencydomain monitors, only) Updated automatically with the wavelength below.
WAVELENGTH: This is the wavelength at which to plot the data (valid for frequencydomain monitors, only) Updated automatically with the frequency above.
TIME : This is the time at which to plot the data (valid for time-domain monitors only)
9.2.2 Far field settings tab

The far field settings tab is the location where the end-users specifies the parameters
which govern the projection of near field and Poynting vector data into the far field. The
far field data is plotted as a function of angle, measured from the projection direction in a
polar plot overlaid with circles which indicate the far field diffraction angle of the near field
radiation. All far field data is projected onto a hemisphere with a radius of 1 meter. The far
field data is scaled so that if it is integrated over the far field, you obtain the same integral
as if you were to perform a similar integration over the near field data.
A screenshot of the far field settings tab is shown in the figure below.
Analysis tools
101
Available settings include:

PROJECTION DIRECTION: this is the axis direction in which the fields are projected,
and is specified in terms of positive or negative directions. With the default AUTO
setting, this will be automatically set to be perpendicular to the line/plane over which the
data is measured, in the direction of positive power flow.
MATERIAL INDEX: this is the refractive index of the material in which the field is
projected. For instance, to project in air set the index to 1; to project in SiO2 set the
index to 1.44. By default it is set to auto.
FAR FIELD FILTER: reduces ripple in the far field projection caused by truncation of
the near field data.
X, Y, Z POINTS: this is the spatial resolution of the projection in the far field. These
numbers represent the number of points to spread across the 180o span of the
projection.
ASSUME PERIODIC: this checkbox is used to determine the far field projection of a
periodic structure from a simulation with periodic or Bloch boundary conditions. If
checked, the following settings apply:
o ILLUMINATION: can be either GAUSSIAN SPOT, or TOP HAT.
Gaussian spot refers to a situation where the extent of the periodic structure is
large with respect to the spot size.
Top hat refers to a situation where the illumination is large with respect to the
physical extent of the structure.
o X, Y, Z PERIODS: this governs the extent of the effective structure. The extent of the
structure is limited by either the illumination conditions (i.e. Gaussian spot) or by the
structure itself (i.e. Top hat). For a Gaussian spot, the x, y, z periods refers to the
FWHM of the Gaussian beam, measured in the number of periods. For a Top hat,
the x, y, z periods refers to the number of periods in the structure.
9.3
Analysis groups
Analysis groups are objects that contain monitors and associated script functions which
can be used to create customize data analysis. For example, an absorption monitor
group can be created with a power monitor, index monitor, and the a script function that
calculates absorption from the fields and index.
102
Reference Guide
An example of the edit window for an analysis group is shown in the screenshot below.
As can be seen above, there is a SETUP tab and an ANALYSIS tab. The SETUP tab
contains all the information needed to edit and set up monitors that are located in the
analysis group. The functionality of the SETUP tab is very similar to the Structure groups
object. See the Properties 42 and Script 43 tab section for information. It is only possible
to edit information in the SETUP tab in layout mode, but information in the SCRIPT tab
can be edited both in layout and analysis mode (see the note at the top of the window
which is highlighted in yellow).
The ANALYSIS tab contains all the information to analyze the monitor data. It is divided
into two sub-tabs. The VARIABLES tab contains all input parameters in the top half, and
the output parameters (named results) in the bottom half. Parameters can be added and
removed using the respective buttons. Any changes to the variables can be saved using
the SAVE ANALYSIS button at the bottom of the tab. The RUN ANALYSIS button runs
the analysis script located in the SCRIPT tab.
Once an analysis routine has run, the result (output parameters) become monitor data,
that can be accessed from the script prompt or a script file in the same manner that
monitor data is accessed for simple monitors.
A screenshot of the contents of the SCRIPT tab is given below. There is a section of the
window that contains the analysis script and a section that contains the results of the
analysis script once the RUN ANALYSIS button has been pressed.
Note that the script below computes the output parameter. Since the script contains the
script command to print the results to the screen, i.e. "?", the value computed for the
Analysis tools
103
output parameter is printed in the Analysis Script Output portion of the window.
More information concerning Analysis groups is available in the User Guide section of the
Online Help.
9.4
Figure windows for plots and images

Plots and images can be created from either the scripting language (Plotting commands
158 ) or from the Analysis Window (The analysis window 99 ). Once a figure window has
been created, it looks like this:
Plot
Image
All of the figure windows support the same zoom functionality as in the layout editor. The
104
Reference Guide
left button zooms in by a factor of two, the right button zooms out by a factor of two,
pressing and holding the left-hand mouse button results in a zoom window, and doubleclicking either mouse button scales the plot to show all of the data.
The figure window also has functions that are accessible from the top menu, which
contains the FILE and SETTING.
The FILE submenu contains the following items:
EXPORT TO JPEG: Opens a file browser and to select a filename for a jpeg copy of
the current view of the figure. A window will pop up asking for the figure resolution.
The SETTING submenu contains the following items:
Common for Plot and Image:
AXIS: Allows the following axes properties to be set
o SET AXIS LIMITS(Ctrl+A): Opens a GUI window that allows the min and max values
to be set for both the x and y axes. The initial values correspond to the current view
of the figure.
o INVERT AXIS(Ctrl+V): A check box that allows the axis to be inverted: the vertical
axis is drawn on the horizontal and vice versa.
COLOR MAP: Allows you to choose between a color image (Ctrl+C)or a grey-scale
figure(Ctrl+G).
SET TITLE(Ctrl+T): allows you to set the x label, y label, and the title of the plot.
Plot specific
SET LEGEND(Ctrl+L): Allows you to set the legend and its position.
Image specific
COLOR BAR:
o SET COLOR BAR LIMITS (Ctrl+B): Opens a GUI window that allows the min and
max values to be set for both the color bar. The initial values correspond to the
current view of the figure. Any data values larger than the maximum are displayed at
the color (or grey-scale) of the maximum, and similarly for the minimum. This allows
for over-saturation of the colors to emphasize certain regions of the image, or for
more accurate comparison between two images.
o RESET DEFAULT LIMITS(Ctrl+D): Resets the original limits. This corresponds to the
minimum and maximum values of the data being imaged.
9.5
Data export
In some cases, the user may wish to export the FDTD simulation data to take advantage
of the advanced plotting and data analysis tools not available in the FDTD Solutions. Data
export can be done in a number of ways, but in general the use of the scripting language
will be required. The user can use scripting commands as described in the Scripting
language 106 section to write data into text format, or alternatively use Matlab by directly
calling Matlab functions in FDTD or by exporting data to .mat files.
Export to text files
The data subset export facility in the analysis view allows the user to save to a specified
Analysis tools
105
filename, a subset of the total simulation data for quick plotting in other software
packages. For x-y plots, the data subset export facility generates a two-column ASCII
data file, with a header which specifies where the data was taken from and the column
headings with units. For image plots, the data subset consists of two columns which
specify the x and y positions in the units specified within the CAD layout editor, and a
matrix of data which consists of the field quantities being exported. The user may also
write a script file and utilize the write 117 script function to custom create a text file.
Matlab
MATLAB has a number of specialized plotting functions useful for visualizing FDTD
simulation data. For example, contour plot or vector plot, which are not available in the
FDTD Solutions but found in MATLAB, are suitable for visualizing the electric field or
power flow. FDTD Solutions provides two interfaces for users wishing to use MATLAB in
their analysis:
1. The first option allows MATLAB commands to be called directly from within the FDTD
Solutions scripting environment. Data can be moved between FDTD workspace and
MATLAB workspace, so the user can take advantage of the combined functionality
provided by both programs. This is accomplished by using the script commands,
matlab 122 , matlabput 124 , and matlabget 123 . To use this option, both FDTD and
MATLAB must be installed on the same computer.
2. The second option allows simulation data to be exported to MATLAB .mat files for
subsequent data analysis in MATLAB. For more information, see the matlabsave 120
command.
The FDTD Solutions Online Help provides an example of how each option can be used.
See the User Guide - Scripting language section.
MATLAB is a registered trademark of The Mathworks, Inc.
106
Reference Guide
10
Scripting Language
Lumerical provides a powerful scripting language to manipulate simulation objects, launch
simulations and analyze results. Script commands can be entered directly into a script
prompt, be run from a saved script file, or entered into a group object. Group objects run
setup scripts every time they are edited, and analysis scripts when these are called.
To view the script prompt, select VIEW->WINDOWS-> SCRIPT PROMPT from VIEW
menu on the main title bar. You can type and execute commands in the script region.
Script files can be created and edited in the script file editor, which is opened by selecting
VIEW->WINDOWS-> SCRIPT FILE EDITOR from VIEW menu on the main title bar.
They can also be created and edited in another text editor. All files with the extension .lsf
are recognized as script files. To run a saved script file, open a file in the script file editor
and press the run script button, or select RUN SCRIPT from the SIMULATE menu on the
main title bar. Scripts can also be run by typing their file name at the script prompt or in
another script file.
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, and then any other folders in the path, THEN the directory of the
script file.
Structure and analysis groups both have associated set up scripts. These script are run
whenever the group is edited, or the when the TEST button located below the scripts in
the edit GUI is pressed. In addition, analysis groups have an analysis script. The analysis
script is not run automatically. It can be run using the runanalysis script command, or by
choosing to edit the properties of the script, selecting the ANALYSIS tab, and pressing
the RUN ANALYSIS button just below where the script is.
The script functions have been organized into the following sections.
Section
System level
107
Manipulating variables
Operators
130
Functions
139
124
Loop and conditional statements

156
Plotting commands
158
Manipulating objects
161
Scripting Language
Material database functions
User defined GUIs
107
183
186
FDTD Solutions toolbox
190
Creating your own script

commands 238
The online help version of the Scripting Language section includes examples for many of
the script functions.
10.1 System level

System level commands for interacting with the OS file system, running script files, etc.
System commands
Command
Description
del 109
rm 109
Deletes a file.
ls 110
dir 109
Lists the files in a directory.
cd
Changes the working directory.
110
pwd
cp
Returns the current working directory.
110
Copy a file.
110
mv
exit
Move a file
111
Exit the application.
111
system
Run command prompts.
111
fileexists
Check if a file exists.
112
currentfilename
filebasename
filedirectory
112
112
Get the file base name from a string.

Get the file directory from a string.
113
fileextension
Get the current filename.
Get the file extension from a string.
113
Starting and stopping scripts

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

of commands from executing
115
File input and output
115
Command
Description
format
Set the precision of the script interpreter.
116
STD OUT
write
Writes strings to text files or to standard output.
117
LDF files
loaddata
Load variables or d-card data from ldf file.
116
savedata
Save variables to ldf file.
116
savedcard
Saves d-card data to an ldf file.
117
Text files
readdata
write
Read text files.
117
Writes strings to text files or to standard output.
117
fld (field) files

asapexport
asapload
Export monitor data to fld file.
118
Load data from fld file.
118
asapimport 119
See Also
exportfigure 160 , load
Import data from fld file to Import source.

195
, save
196
MATLAB functions
Command
matlabsave
lum2mat
121
Description
120
Save workspace data to a Matlab .mat file.

Convert data from an .ldf file to a Matlab .mat file.
Scripting Language
lum2mat command line
matlab
122
Run lum2mat from the command line.

Execute a MATLAB command
122
matlabget
123
Get a variable from the MATLAB workspace
matlabput
124
Send a variable to the MATLAB workspace
10.1.1 del
Delete a file.
Syntax
Description
del("filename");
rm("filename");
Deletes the file "filename".

This function does not return any data.
See Also
System level
107
, delete
163
10.1.2 rm
Delete a file.
Syntax
Description
del("filename");
rm("filename");
Deletes the file "filename".

See Also
System level
107
, delete
163
10.1.3 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
107
109
110
Reference Guide
10.1.4 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.
See Also
System level
107
10.1.5 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
107
10.1.6 pwd
Returns the current working directory.
Syntax
Description
out = pwd;
Returns the current working directory as a string.
See Also
System level
107
, currentfilename
112
10.1.7 cp
Copy a file.
Syntax
Description
Scripting Language
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
107
, mv
111
, pwd
110
, copy (objects)
111
166
10.1.8 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
107
, cp
110
, pwd
110
10.1.9 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.
The default option is 1.
See Also
System level
107
10.1.10 system
The system command is used to have the Operating System execute a command, rather
than the script prompt.
Only available in FDTD Solutions.
112
Reference Guide
Syntax
Description
system("command");
Run the command prompt "command".
See Also
System level
107
10.1.11 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
107
, getpath
113
, which
114
, pwd
110
10.1.12 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 107 , fileexists 112 , getpath
filebasename 112 , filedirectory 113
113
, which
114
, pwd
110
, fileextension
113
10.1.13 filebasename
Get the file basename from a string.
Syntax
Description
out = filebasename(
"location/filename.ext" );
Returns the file basename as a string.
See Also
Scripting Language
System level
107
, currentfilename
112
, getpath
113
, which
114
, pwd
110
10.1.14 fileextension
Get the file extension from a string.
Syntax
Description
out = fileextension(
"name.ext");
Returns the file extension as a string.
See Also
System level
107
, currentfilename
112
, getpath
113
, which
114
, pwd
110
10.1.15 filedirectory
Get the file directory from a string.
Syntax
Description
out = filedirectory(
"location/filename.ext" );
Returns the file directory as a string.
See Also
System level
107
, currentfilename
112
, getpath
113
, which
114
, pwd
110
10.1.16 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.
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
107
, getpath
113
, addpath
114
, which
114
10.1.17 getpath
Get the current path. The path always contains the current working directory.
Syntax
Description
113
114
Reference Guide
out = getpath;
See Also
System level
107
Returns the current path as a string.

Use ?getpath; to print it to the screen.
, addpath
114
, which
114
, pwd
110
10.1.18 addpath
Add a directory to the path.
Syntax
Description
addpath("directory");
Adds a directory to the path.

See Also
System level
107
, getpath
113
, which
114
, pwd
110
10.1.19 which
Returns the full file pathname for the specified file. This is useful when checking what
script file will run.
Syntax
Description
out = which("filename");
Returns the pathname of the file "filename.lsf" as a string.

Use ?which("filename"); to display the result to the
screen.
See Also
System level
107
, getpath
113
, addpath
114
, pwd
110
, currentfilename
112
, fileexists
112
10.1.20 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
Scripting Language
System level
107
, break
115
, ESCAPE key
115
115
10.1.21 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
107
, ESCAPE key
115
, pause
114
10.1.22 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,
or hold it down to interrupt the script.
See Also
System level
107
, break
115
, pause
114
10.1.23 File IO background

The following commands are used to read and write data between files and FDTD
Solutions. By defualt, FDTD Solutions saves its data in ldf (Lumerical Data Files) files. A
number of other file formats are also supported, including text files, matlab files, and
ASAP files.
Data exported from FDTD Solutions is provided in the base units described in the Units
and normalization 20 section. When exporting the entire simulation dataset, the data is
not normalized to its continuous-wave response. The following units are used:
Distance in m
Time in s
Frequency in Hz
E(t) in V/m
H(t) in A/m
E(w) in V/(m Hz)
H(w) in A/m/Hz
P(w) in W/(m2 Hz2)
116
Reference Guide
See Also
System level
107
10.1.24 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
107
, num2str
137
,?
139
10.1.25 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
107
, savedata
116
, savedcard
117
, workspace
129
, showdata
180
10.1.26 savedata
Saves workspace variables to a Lumerical data file (ldf) file.
Syntax
Description
savedata("filename");
Saves all current variables to the specified file.

savedata("filename", var1,
var2,...);
Saves only variables with the specified names to file.
Scripting Language
See Also
System level
107
, savedcard
117
, loaddata
116
, workspace
129
, lum2mat
117
121
10.1.27 savedcard
Saves d-card data to a Lumerical data file (ldf) file. D-cards are generally used to store
monitor data.
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
107
, savedata
116
, loaddata
116
, showdata
180
, lum2mat
121
10.1.28 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
107
, rm
109
, write
117
10.1.29 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. The write command can only write to standard output in FDTD
Solutions.
118
Reference Guide
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
107
, readdata
117
, rm
109
, num2str
137
,?
139
, endl
139
, format
116
10.1.30 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.
Syntax
Description
asapexport(
"monitorname");
Export data from monitorname. By default, the first

frequency point is exported.
asapexport( "monitorname", Exports the frequency point specified by the index f.

f);
asapexport( "monitorname", Exports to the specified "filename" without opening a file
f, "filename");
browser window.
See Also
System level
107
, asapload
118
, asapimport
119
, addimportedsource
205
10.1.31 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 "fl_data" exists, it will be called
"fl_data_2". After loading an asapfile with asapload, you can extract any desired data.
Data 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.
Scripting Language
See Also
System level
107
, asapexport
118
, asapimport
119
, addimportedsource
119
205
10.1.32 asapimport
Import an ASAP fld file into an ASAP source. This is equivalent to editing the properties
of the ASAP source, and clicking on the READ ASAP SOURCE button.
Syntax
Description
asapimport( "sourcename"); Imports the fld file into the sourcename source. A file
browser will open to select the file.
asapimport( "sourcename",
"filename");
See Also
System level
107
, asapexport
Specify the file to open.
118
, asapload
118
, addimportedsource
205
10.1.33 gdsimport
Import a layer from a GDSII 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 for more information.
Syntax
Description
gdsimport("filename",
"cellname", layer);
Imports the specified layer from the specified cell in the

specified file into the current simulation environment. The
objects created will have their material set to an object
defined dielectric. In 3D, the 2D geometric data will be
extruded to default values in the Z dimension
"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 GDSII file to import. May contain complete

path to file, or path relative to current working
directory
120
Reference Guide
cellname
string
the name of the cell to import from the GDSII file
layer
number
or string
the layer number from the GDSII file to import. If

only elements matching a certain data type are
desired, this can be specified by using a string of
the form:
"6:2"
where the desired layer is 6 and the desired data
type is 2.
material
string
a valid name of a material in your current layout

environment. Partial names of materials can be
matched starting at the beginning of the string. For
example, "Al (3" would match "Al (300nm)".
z min
number
the minimum z value for extruding 2D GDSII data

into 3D objects
z max
number
the maximum z value for extruding 2D GDSII data

into 3D objects
See Also
System level
107
, setnamed
168
10.1.34 matlabsave
Save workspace data to Matlab .mat data files.
Matlab has recently changed its .mat file format. The primary advantage is that the new
format supports files larger than 2GB. Matlab 7.3 is the first version to support the new
format, but can also read the previous file format. All Matlab Pre 7.3 cannot read the new
format.
There is currently no option to this function to cause a version 7.3 Matlab .mat file to be
written. This command can only produce the older format .mat file. For more information
about the Matlab file formats and how to save to a version 7.3 .mat file refer to the
lum2mat script commmand.
Syntax
Description
matlabsave("filename");
Saves all current variables to the specified .mat file.

matlabsave("filename",
var1, ..., varN);
Saves only variables with the specified names to the .mat

file.
Scripting Language
See Also
System level
107
, lum2mat
121
, lum2mat command line
122
, matlabput
121
124
10.1.35 lum2mat
Convert Lumerical .ldf, .fsp, .lms files into Matlab .mat data files.
The name of the Matlab file will be the same name as the input file, but with a .mat file
extension. Within the Matlab file, source/monitor data is stored in named variables. All of
the names of variables associated with a particular monitor/source are prefixed with the
monitor/source name, as set in the monitor/source properties. The remainder of the
variable name describes the contents of the data, such as EM field components, spatial
coordinates, time vectors and frequency vectors.
When exporting script variables to Matlab file, they will appear in the Matlab workspace
with the same name as in the Lumerical scripting workspace.
Matlab has recently changed its .mat file format. The primary advantage is that the new
format supports files larger than 2GB. Matlab 7.3 is the first version to support the new
format. Matlab 7.3 can also read the previous file format. All Matlab Pre 7.3 canhgnot
read the new format.
The 64-bit version of FDTD Solutions exports to the new Matlab file format by default.
The 32-bit version of FDTD Solutions exports to the Matlab Pre 7.3 file format by default.
The defaults can be overridden with an extra option added to the command.
For more information about Matlab, please see:
http://www.mathworks.com/products/matlab/
For information on how to use the Matlab output file please see:
http://www.mathworks.com/access/helpdesk/help/techdoc/ref/load.shtml#
Syntax
Description
lum2mat ("filename");
Will convert the data in a lumerical file named "filename"

to a Matlab .mat file with the same name. The filename
should specify the extension, valid extensions are "ldf",
"fsp", and "lms".
lum2mat
("filename",option);
Option
1 : export to new Matlab file format
2 : export to Matlab Pre 7.3 file format
See Also
System level 107 , lum2mat command line
savedcard 117 , showdata 180
122
, matlab
122
, loaddata
116
, savedata
116
122
Reference Guide
10.1.36 lum2mat command line

Convert Lumerical .ldf, .fsp, .lms files into Matlab .mat data files.
By default, the command line version of lum2mat uses the Matlab Pre 7.3 file format
when creating .mat files. If the option -v73 is included, the new file format is used.
For more information, please see the lum2mat help.
Syntax
Description
lum2mat filename
Convert the data in a Lumerical file named "filename" to a

Matlab .mat file with the same name.
filename should include the file extension; valid
extensions are "ldf", "fsp", and "lms".
lum2mat -nw filename
No graphical window option.
lum2mat -v73 filename
Use the new Matlab file format introduced in version 7.3.

The default option is the previous file format.
See Also
System level
107
, lum2mat
121
10.1.37 matlab
Runs a MATLAB command from the FDTD Solutions script prompt. This gives access to
extended mathematical and visualization functionality from the FDTD Solutions script
environment. If MATLAB is not installed, this function will return an error.
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 FDTD Solutions
workspaces are completely separate and independent. A MATLAB command cannot act
on a variable defined in the FDTD Solutions 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 FDTD Solutions script
prompt. One limitation of the matlab function is that no error reporting is provided to either
the FDTD script prompt or the MATLAB prompt. MATLAB commands should be tested
by typing them directly into the MATLAB prompt before they are used in FDTD Solutions.
When using a number of MATLAB commands together, it is recommended that the
commands are stored in a MATLAB m-file. Instead of embedding many commands into a
single matlab script function call, you may simply call the m-file with the matlab script
Scripting Language
123
command. Using MATLAB m-files in this way will allow you to interactively test your
MATLAB code at the MATLAB script prompt before running it from FDTD Solutions.
Supported MATLAB versions
This function requires that MATLAB version 7.0 (2004) or newer to be installed on the
computer. Also, please remember that 32 bit and 64 bit applications can not be mixed.
For example, if you have the 32 bit version of MATLAB, then you MUST use the 32 bit
version of FDTD. NOTE: The student version of MATLAB is 32 bit.
To check if the Matlab script integration is enabled, select the Help - Matlab integration
status menu option. This window will report that the script integration is active or inactive.
If FDTD is unable to establish a connection with MATLAB, even when a supported
version is installed, try re-installing MATLAB, then reinstalling FDTD in their respective
default directories. This usually fixes the problem. If not, please contact Lumerical
support.
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
107
, matlabget
123
, matlabput
124
, lum2mat
121
10.1.38 matlabget
Copies a variable from the MATLAB workspace to the FDTD Solutions workspace. The
resulting variable in the FDTD Solutions workspace will have the same name as in
MATLAB, 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.
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
107
, matlab
122
, matlabput
124
124
Reference Guide
10.1.39 matlabput
Copies a variable from the FDTD Solutions workspace to the MATLAB workspace. The
resulting variable in the MATLAB workspace will have the same name as in FDTD
Solutions, and will overwrite any existing variable with the same name. If the variable
does not exist in FDTD Solutions, 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 refer to variables in the Mode Solutions
workspace.
See Also
System level
107
, matlab
122
, matlabget
123
10.2 Manipulating variables

The following commands are used to create and access variables.
Command
Description
Assignment operator.
:
[]
125
Array operator.
125
Create matrix.
125
Create variable with space in the name
126
linspace
matrix
Creates a linear spaced array.
126
Creates a matrix filled with zeros.
126
randmatrix
127
Creates a matrix with all elements randomly set

between 0 and 1
meshgridx
127
Create a 2D meshgrid in x direction.
meshgridy
127
Create a 2D meshgrid in y direction.
meshgrid3dx
127
Create a 3D meshgrid in x direction.
meshgrid3dy
128
Create a 3D meshgrid in y direction.
meshgrid3dz
128
Create a 3D meshgrid in z direction.
clear
Clears all stored script variables from memory.
128
workspace
129
Returns a string of all the currently defined scripting
Scripting Language
125
variables.
Matrix elements
How to assign and access matrix elements.
129
Matrix operations
Describes how operators and functions act on

matrices.
130
Pre-defined constants
List of pre-defined constants.
130
10.2.1 =
Assignment operators.
Syntax
Description
x = 5+2i;
Assign a value to a variable.
See Also
124
, ==
133
10.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
124
, linspace
126
10.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
126
Reference Guide
matrices of compatible dimension.
See Also
124
, linspace
126
, matrix
126
10.2.4 %
Used to create variables with spaced in the names.
Command
Description
%variable with space%
See Also
124
To create a variable name that contains spaces,

such as "variable with space", put a percentage sign
before and after the variable name.
10.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
124
,:
125
, []
125
10.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
124
, linspace
126
, []
125
Scripting Language
10.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

random numbers between 0 and 1.
See Also
124
, matrix
126
, rand
156
, randreset
156
10.2.8 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);
Will create a 2D matrix of dimension nXm where
X(i,j)=x(i).
See Also
124
, image
159
, meshgridy
127
, meshgrid3dx
127
10.2.9 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
124
, image
159
, meshgridx
10.2.10 meshgrid3dx
Create a 3D meshgrid in the x direction
Syntax
Description
127
, meshgrid3dx
127
127
128
Reference Guide
out = meshgrid3dx(x,y,z);
See Also
124
The 3D version of meshgridx and meshgridy.
, meshgridx
127
, meshgridy
127
, meshgrid3dy
128
, meshgrid3dz
128
10.2.11 meshgrid3dy
Create a 3D meshgrid in the y direction
Syntax
Description
out = meshgrid3dy(x,y,z);
See Also
124
, meshgridx
127
, meshgridy
127
, meshgrid3dx
127
, meshgrid3dz
128
10.2.12 meshgrid3dz
Create a 3D meshgrid in the z direction
Syntax
Description
out = meshgrid3dz(x,y,z);
See Also
124
, meshgridx
127
, meshgridy
127
, meshgrid3dx
127
, meshgrid3dy
128
10.2.13 clear
Clears all stored workspace variables. This will not clear any simulation data stored in
d-cards. The variables c, pi, eps0, mu0 will be reset to their default values.
Syntax
Description
clear;
Clears all workspace variables.

See Also
124
, cleardcard
181
Scripting Language
129
10.2.14 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.
Use ?workspace; to print this to the screen.
See Also
124
, showdata
180
10.2.15 Accessing and assigning matrix elements

Accessing and assigning matrix elements.
The square brackets method of defining matrices is only available in FDTD solutions.
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
sub-matrix 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
124
130
Reference Guide
10.2.16 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 Operation
y
Dimension of Value of z
z
1x1
N/A
z = sin(x)
1x1
z11 = sin(x11)
1x1
1x1
z=x*y
1x1
z11 = x11 * y11
10x10
1x1
z=x*y
10x10
Zij = xij * y11
10x10
10x10
z=x*y
10x10
Zij = xij * yij
10x10
11x11
z=x*y
Error
Error
See Also
124
10.2.17 Pre-defined constants

Name
Description
pi
The number p.
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.
See Also
124
10.3 Operators
Standard mathematical and string operators.
Algebraic operators
Command
Description
132
Multiplication. Ex: y = x * z;
132
Division. Ex: y = x / z;
132
Addition. Ex: y = x + z;
Scripting Language
131
132
Subtraction. Ex: y = x z;
132
Negative. Ex: y = -x;
133
Power. Ex: y = x^3;

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

Command
Description
==
Comparison.
133
almostequal
!=
133
Almost equal comparison operator.

Not equal.
134
<=
134
Less than or equal to.
>=
134
Greater than or equal to.
<
135
Less than.
>
135
Greater than.
&
135
AND.
and
AND.
135
| 136
OR.
or
OR.
136
NOT.
136
NOT.
137
String operators
Command
Description
num2str
Convert number to a string.
137
"
137
Create a string variable.
'
138
Create a string variable.
Add strings
132
endl
139
Output to screen
end of line character.
132
Reference Guide
Command
Description
Display output on screen.
139
script file comments
Comment script files with #
139
10.3.1 *
Multiplication.
Syntax
Description
y = x * z;
Multiply x and z.
See Also
Operators
130
,*
132
,/
132
,+
132
,-
132
,^
133
10.3.2 /
Division.
Syntax
Description
y = x / z;
Divide x by z.
See Also
Operators
130
,*
132
,/
132
,+
132
,-
132
,^
133
10.3.3 +
Addition.
Syntax
Description
y = x + z;
Add x and z.
y = string1 + string2;
Concatenate strings together.
See Also
Operators
130
,*
132
,/
132
,+
132
,-
132
,^
133
10.3.4 Subtraction, or negative.

Syntax
Description
y = x - z;
Subtract z from x.
Scripting Language
y = -x;
See Also
Operators
133
Negative
130
,*
132
,/
132
,+
132
,-
132
,^
133
10.3.5 ^
Power. In expression A^B, if B is complex, the phase of A is evaluated from -p to p.
Syntax
Description
y = x^3;
x cubed.
See Also
Operators
130
,*
132
,/
132
,+
132
,-
132
,^
133
10.3.6 ==
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 130 , = 125 , almostequal
, or 136 , ! 136 , ~ 137
133
, !=
134
, <=
134
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136
10.3.7 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*1e-15. 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.
134
Reference Guide
See Also
Operators
136 , ~ 137
130
,=
125
, ==
133
, !=
134
, <=
134
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136 , or
136
,!
10.3.8 !=
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 130 , ==
136 , ! 136 , ~ 137
133
, almostequal
133
, <=
134
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136 , or
10.3.9 <=
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 130 , ==
136 , ! 136 , ~ 137
133
, !=
134
, almostequal
133
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136 , or
10.3.10 >=
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 130 , ==
136 , ! 136 , ~ 137
133
, !=
134
, <=
134
, almostequal
133
,<
135
,>
135
,&
135
, and
135
, | 136 , or
Scripting Language
135
10.3.11 <
Logical less than. Imaginary components of x and y are ignored.
Syntax
Description
out = y < x;
Less than.
See Also
Operators 130 , ==
136 , ! 136 , ~ 137
133
, !=
134
, <=
134
, >=
134
, almostequal
133
,>
135
,&
135
, and
135
, | 136 , or
135
, and
135
, | 136 , or
10.3.12 >
Logical greater than. Imaginary components of x and y are ignored.
Syntax
Description
out = y > x;
Greater than.
See Also
Operators 130 , ==
136 , ! 136 , ~ 137
133
, !=
134
, <=
134
, >=
134
,<
135
, almostequal
133
,&
10.3.13 &
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
130
, ==
133
, !=
134
, <=
134
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136 , or
136
,!
136
,~
137
10.3.14 and
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.
136
Reference Guide
y and x;
See Also
Operators
Same as &.
130
, ==
133
, !=
134
, <=
134
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136 , or
136
,!
136
,~
137
10.3.15 |
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
130
, ==
133
, !=
134
, <=
134
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136 , or
136
,!
136
,~
137
10.3.16 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
130
, ==
133
, !=
134
, <=
134
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136 , or
136
,!
136
,~
137
10.3.17 !
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;
applies logical not operator to a
out = ~a;
Scripting Language
See Also
Operators
130
, ==
133
, !=
134
, <=
134
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136 , or
136
,!
137
136
,~
137
10.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
out = !a;
out = ~a;
See Also
Operators
130
, ==
133
, !=
134
, <=
134
, >=
134
,<
135
,>
135
,&
135
, and
135
, | 136 , or
136
,!
136
,~
137
10.3.19 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
130
,"
137
,+
132
,?
139
, endl
139
, write
117
, format
116
10.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
Double quotes within strings are only available in FDTD Solutions.
Strings created with single quotes are only available in FDTD Solutions.
Syntax
Description
out="my string";
use double quotes to create strings
138
Reference Guide
NOTE: Literal backslashes 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
mystring = "C:\Program Files\Lumerical";
# use double quotes
mystring = "C:\\Program Files\\Lumerical"; # use double quotes
and \\ escape character
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
130
,'
138
, num2str
137
,+
132
, endl
139
, write
117
10.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
Syntax
Description
out='my string';
use single quotes to create strings
See Also
Scripting Language
Operators
130
,"
137
, num2str
137
,+
132
, endl
139
, write
139
117
10.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
130
, num2str
137
,+
132
,"
137
, write
117
10.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
107
, write
117
, format
116
10.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
107
10.4 Functions
Standard mathematical and matrix functions.
Trigonometric and complex
Command
Description
sin
Trigonometric sin function.
141
140
Reference Guide
cos
142
Trigonometric cos function.
tan
142
Trigonometric tan function.
asin
Inverse trigonometric sin function.
142
acos
143
Inverse trigonometric cos function.
atan
143
Inverse trigonometric tan function.
atan2
real
abs
Returns the imaginary part of variable
144
Complex conjugate
144
Absolute value
144
angle
Same as atan, but returns angle in correct quadrant.

Returns the real part of variable
143
imag
conj
143
144
unwrap
145
Phase of a complex number.

Removes phase difference of more than 2p
Logarithmic, exponential and power

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

negative.
145
log10
145
The log, base 10. Input can be complex or

negative.
sqrt
145
The square root.
exp
146
The exponential.
Matrix functions
Command
Description
size
Returns the dimensions of a matrix.
146
length
pinch
146
146
Returns the total number of elements in a matrix.

Remove singleton dimensions from a matrix
sum
147
The sum of a matrix
max
147
The max value in a matrix
min
147
The min value in a matrix
Scripting Language
dot
The dot product of two vectors
cross
The cross product of two vectors
flip
Flip a matrix in one dimension
interp
148
Linear interpolation function
spline
148
Cubic spline interpolation
integrate
find
141
Integrate a matrix
148
Find values that satisfy a condition in a matrix
149
findpeaks
149
Find peaks in a matrix
transpose
150
Transpose a matrix
ctranspose 150
See also
Transpose a matrix, and do complex conjugate.

124
Frequency and time-domain

Command
Description
fft
Fast Fourier transform.
150
fftw
fftk
Returns the spatial wavevector kx.
153
invfft
czt
Returns the angular frequency vector.
152
Inverse fft.
154
Chirped z-transform.
155
Miscellaneous
Command
Description
round
Rounds to the nearest integer.
rand
155
Returns a uniformly distributed random number

between 0 and 1.
156
randreset
156
Resets the random number seed.
10.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 -p and p.
Syntax
Description
142
Reference Guide
out = sin(x);
See Also
Functions
139
Returns the complex sine of x.
, asin
142
10.4.2 cos
Trigonometric cosine function. Angle units are in radians. Function is defined for
complex angles. Phase of a complex number is evaluated between -p and p.
Syntax
Description
out = cos(x);
Returns the complex cosine of x.
See Also
Functions
139
, acos
143
10.4.3 tan
Trigonometric tangent function. Angle units are in radians. Function is defined for
complex angles. Phase of a complex number is evaluated between -p and p.
Syntax
Description
out = tan(x);
Returns the complex tangent of x.
See Also
Functions
139
, atan
143
, atan2
143
10.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 -p and p. If x is
complex, or abs(x) > 1, the following equation is used:
asin(x) = -i ln( ix + sqrt(1-x^2))
Syntax
Description
out = asin(x);
Returns the complex arcsine of x.
See Also
Functions
139
, sin
141
Scripting Language
143
10.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
139
, cos
142
10.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
139
, atan2
143
, tan
142
10.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
Functions
139
, atan
143
, tan
142
10.4.8 real
Returns the real part of a number or matrix.
Syntax
Description
144
Reference Guide
out = real(x);
See Also
Functions
139
Returns the real part of x.
, imag
144
10.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
139
, real
143
, conj
144
10.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
139
, real
143
, imag
144
10.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
139
, real
143
, imag
144
10.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
Scripting Language
Functions
139
, real
143
, imag
144
, unwrap
145
145
10.4.13 unwrap
Removes changes of more than 2p from a 1D array. It can be useful after angle(x) to see
phase without discontinuities.
Syntax
Description
out = unwrap(x);
Return the values of x without discontinuities.
See Also
Functions
139
, real
143
, imag
144
, angle
144
10.4.14 log
The natural logarithm. Input can be complex or negative.
Syntax
Description
out = log(x);
See Also
Functions 139 , log10
The natural logarithm. Input can be complex or negative.

145
10.4.15 log10
The log, base 10. Input can be complex or negative.
Syntax
Description
out = log10(x);
See Also
Functions 139 , log
The log, base 10. Input can be complex or negative.

145
10.4.16 sqrt
The square root.
Syntax
Description
out = sqrt(x);
The square root.
See Also
Functions
139
,^
133
146
Reference Guide
10.4.17 exp
The exponential.
Syntax
Description
out = exp(x);
The exponential.
See Also
Functions
139
, log
145
,^
133
10.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
139
, length
146
, flip
10.4.19 length
Returns the number of elements in a matrix.
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
139
, size
146
10.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
Scripting Language
147
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);
See Also
Functions
139
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)
, find
149
, size
146
, flip
10.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
139
10.4.22 max
The maximum value in a matrix.
Syntax
Description
out = max(x);
The maximum value in a matrix.
See Also
Functions
139
10.4.23 min
The minimum value in a matrix.
Syntax
Description
out = min(x);
The minimum value in a matrix.
148
Reference Guide
See Also
Functions
139
10.4.24 interp
Linear interpolation of a data set.
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);
The 3D version of interp.
See Also
Functions
139
, spline
148
10.4.25 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
139
, interp
148
10.4.26 integrate
Returns the integral over the specified dimension of a matrix. For more details on the use
of this function, see also Integrating over lines, surfaces and volumes 31 .
Integrals over singleton dimension will return zero (i.e. the area under a single point is
zero).
Scripting Language
149
Syntax
Description
out = integrate(A, 1, x1);
Integrates A over the first dimension in the matrix.

x1 is the corresponding position vector.
out = integrate(A, d, x1, x2,

...);
Calculates the integral of A over the specified

dimension(s) d.
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 = integrate(A,1:2,x,y) will integrate A over an x-y
surface.
See Also
Functions
139
, max
147
, min
147
, interp
148
, find
149
, pinch
146
, round
155
, getdata
181
10.4.27 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
139
, pinch
146
, findpeaks
149
10.4.28 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
150
Reference Guide
the data, a value of 1 is returned.
findpeaks(y,n);
See Also
Functions
139
, find
Returns a matrix containing the positions of the largest n

peaks found in the data. The returned values are ordered
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.
149
10.4.29 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
139
, ctranspose
150
, flip
10.4.30 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
139
, transpose
150
10.4.31 fft
Compute the 1D, 2D or 3D Fast Fourier Transform (fft) of a matrix. In the 1D case the
transform is given by
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
Scripting Language
151
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 = 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
152
Reference Guide
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:
Lumerical code
Matlab code
fft(y,1,0)
ifft(y)*N
invfft(y,1,0)
fft(y)/N
See Also
Functions
139
, invfft
154
, fftw
152
, fftk
153
, czt
155
10.4.32 fftw
Returns the angular frequency vector corresponding to time vector t.
,
where N=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(Ex). If N <=
length(Ex), it will zero pad up to the next power of 2
Scripting Language
153
example, as 2^12.
See Also
Functions
139
, fft
150
, fftk
153
, invfft
154
10.4.33 fftk
Returns the spatial wavevector kx associated with a fourier transform of a function of x.
,
where N=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
corresponding to your spectrum. Invfft and fftk work in the same way.
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(Ex). If N <=
length(Ex), it will zero pad up to the next power of 2
example, as 2^12.
See Also
Functions
139
, fft
150
, fftw
152
, invfft
154
154
Reference Guide
10.4.34 invfft
Compute the 1D,2D or 3D inverse Fast Fourier Transform (fft) of a matrix. In the 1D case
the transform is given by
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 corresponding to your spectrum. Invfft and fftk work in the same way.
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
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
Scripting Language
155

example, as 2^12.
See Also
Functions
139
, fft
150
, fftw
152
, fftk
153
10.4.35 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.
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
139
, fft
150
10.4.36 round
Rounds a number to the nearest integer.
Syntax
Description
out = round(x);
Rounds x to the nearest integer.
See Also
Functions
139
156
Reference Guide
10.4.37 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
139
, randreset
156
, randmatrix
127
10.4.38 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
139
, rand
156
, randmatrix
127
10.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
For loop.
if
157
If statement.
157
while
157
A for loop must be used. See the for loop section.
Scripting Language
157
10.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 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 156 , if
157
10.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
158
Reference Guide
Loops
156
, for
157
10.6 Plotting commands

Line and image plots are supported. These figures can be exported to jpeg images.
Plotting functions.
Command
Description
plot
Makes line plots
158
legend
image
setplot
Makes a legend on a figure with line plots.
159
Makes 2D image plots
159
Set figure properties.
160
Miscellaneous plotting functions.

Command
Description
selectfigure
160
Selects a figure.
exportfigure
160
Exports a figure.
closeall
161
Closes all figure windows.
10.6.1 plot
Create line plots.
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)
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

logplot
plot lines OR plot points
greyscale OR color
Scripting Language
159
polar (used for imaging far field projections)

any comma separated list of the above, for example
"logplot,greyscale,polar"
Returns the figure number.
See Also
Plotting commands
158
, legend
159
, image
159
, closeall
161
, setplot
160
, exportfigure
160
10.6.2 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
158
, legend
159
, plot
158
, closeall
161
10.6.3 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
Returns the figure number.
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

label", "title", "options");
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
158
, plot
158
, closeall
161
, setplot
160
, exportfigure
160
160
Reference Guide
10.6.4 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
158
, image
159
, plot
158
10.6.5 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
158
, exportfigure
160
, image
159
, plot
158
, setplot
160
, closeall
161
10.6.6 exportfigure
Exports the current figure to a JPG image. If the file extension is not specified, ".jpg" will
be used.
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".
exportfigure("filename",
width and height specify the size in pixels of the resulting
Scripting Language
width, height);
161
image. 100 pixels is the minimum value
See Also
Plotting commands
158
, selectfigure
160
, image
159
, plot
158
, setplot
160
, closeall
161
10.6.7 closeall
Close all open figure windows.
Syntax
Description
closeall;
Close all open figure windows.

See Also
Plotting commands
158
, plot
158
, image
159
10.7 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
deleteall
Deletes all objects in the current TAB.
delete
163
selectall
Selects all objects in the current TAB.
164
unselectall
select
Deletes the selected objects in the current TAB.
163
Unselects all objects in the current TAB.
164
Selects all objects with the name "name", in the

current TAB.
164
selectpartial
shiftselect
Selects any objects where partialname can be found

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

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

not unselect currently selected objects. Can be used
to select multiple objects.
162
Reference Guide
Command
Description
move
Move an object.
copy
166
Copy an object.
166
addtogroup
Add an object/objects into a group.
166
Object properties
Command
Description
adduserprop
set
Set a property of selected objects.
167
setnamed
setglobal
get
Add a user property to a structure group.
167
Set a property of any objects with a given name.
168
Used to set the global variables in the current tab.
168
Get a property of selected objects.
169
getnumber
getnamed
Get the number of selected objects.
170
Get a property of any objects with a given name.
170
getnamednumber
getglobal
importsurface
171
172
importsurface2
173
174
importnk2
Get the number of objects with a given name.

Get the value of global variables in the current tab.
171
haveproperty
importnk
171
175
Returns the number of selected objects with a

particular property.
Import surface data from a file. Only applies to
import primitives.
Import surface data from script variables. Only
applies to import primitives.
Import n and k data from a file. Only applies to
import primitives.
Import n and k data from script variables. Only
applies to import primitives.
Controlling the view

Command
Description
redraw
Redraw graphics.
176
redrawoff
176
Turn automatic redraw off.
redrawon
176
Turn automatic redraw on.
Scripting Language
redrawmode
setview
177
getview
178
orbit
Get the current status of automatic redrawing; turn it

off or on
176
Control how the graphics are drawn in the Layout

Editor
Get the current view control properties from the
Layout Editor.
A built in function to do an orbit of the perspective
view with option of creating a movie.
178
Undo and redo commands

Command
Description
undo
Undo last modify object command.
redo
179
Redo command after an undo.
179
10.7.1 deleteall
Syntax
Description
deleteall;

See Also
161
, delete
163
, selectall
164
, select
164
10.7.2 delete
Deletes selected objects in the current TAB.
Syntax
Description
delete;
Deletes selected objects in the current TAB.

See Also
163
161
, deleteall
163
, select
164
, selectall
164
, del
109
164
Reference Guide
10.7.3 selectall
Syntax
Description
selectall;

See Also
161
, unselectall
164
, select
164
, set
167
, deleteall
163
10.7.4 unselectall
Unselect all objects in the current TAB.
Syntax
Description
unselectall;
Unselects all objects in the current TAB.

See Also
161
, select
164
, selectall
164
10.7.5 select
Selects objects with a given name, in the current TAB.
Syntax
Description
select("name");
Selects all objects with the name "name", in the current

TAB.
select("group
name::name");
Selects all objects with the name "name" located in the

group named "group name" in the current TAB. Groups
are only available in FDTD Solutions.
See Also
Manipulating objects 161 , set 167 , delete 163 , deleteall
selectpartial 164 , shiftselect 165 , shiftselectpartial 165
163
, selectall
164
, unselectall
164
10.7.6 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
Scripting Language
165
the object name provided the object is not in a group, in

the current TAB. To select objects located in groups see
the command below.
selectpartial("partialgroupna Selects any objects where "partialgroupname" can be
me::partialname");
found in the group name and "partialname" can be found
in the object name. Groups are only available in FDTD
Solutions.
See Also
Manipulating objects 161 , select 164
10.7.7 shiftselect
Same as select, but does not unselect other currently selected objects.
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. Groups are only
available in FDTD Solutions.
See Also
161
, select
164
10.7.8 shiftselectpartial
Same as selectpartial, but does not unselect other currently selected objects.
Syntax
Description
shiftselectpartial("partialnam The same as selectpartial("partialname"), but does not

e");
unselect currently selected objects. Can be used to select
multiple objects.
shiftselectpartial("partialgro
upname::partialname");
See Also
161
The same as selectpartial("

partialgroupname::partialname"), but does not unselect
currently selected objects. Can be used to select multiple
objects. Groups are only available in FDTD Solutions.
, select
164
166
Reference Guide
10.7.9 move
Move selected objects.
Syntax
Description
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
161
, copy
166
, select
164
10.7.10 copy
Copy selected objects.
Syntax
Description
copy;
Copy the selected objects. The new objects will have

have the same name. Their position will be shifted by a
default amount.
This function does not return any data. This syntax is only
available in FDTD Solutions.
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.

In 2D, dz is ignored.
See Also
161
, move
166
, select
164
, cp (copy files)
110
10.7.11 addtogroup
Add selected objects to a group.
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
Scripting Language
167
name" is created.
See Also
161
10.7.12 adduserprop
Add user properties to a structure group.
Syntax
Description
adduserprop("property
name", type, value);
See Also
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.
161
10.7.13 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
168
Reference Guide
tree. The uppermost selected object is given the index 1,
and the index numbers increase as you go down the tree.
See Also
haveproperty 171
161
, get
169
, setnamed
168
, setmaterial
184
, addmaterial
183
10.7.14 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.Groups are only available in FDTD
Solutions.
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
161
, set
167
, get
169
, getnamed
170
, getnamednumber
171
10.7.15 setglobal
Used to set the global variables in the current tab. Only applicable in the Sources and
Monitors tabs.
Syntax
Description
Scripting Language
169
?setglobal;
Returns a list of the properties of the global properties in

the current tab.
out = setglobal("name",
value);
Sets the global variable called "name" for the current tab
to value. Set global returns 1 if it was successful in setting
the values.
See Also
161
, getglobal
171
, set
167
, get
169
10.7.16 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.
Note: Beam profiles
In addition to the properties available through the Edit dialogue, it is possible to get the
beam profile for gaussian, planewave and mode sources. The property names are "x
vector","y vector","z vector","Ex","Ey","Ez","Hx","Hy", and "Hz". In addition, for mode
sources, the real part of the effective index for the mode can be obtained. This property is
named "neff".
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
haveproperty 171
161
, getnumber
170
, getnamed
170
, getnamednumber
171
, set
167
170
Reference Guide
10.7.17 getnumber
Get the number of objects that are selected.
Syntax
Description
out = getnumber;
Returns the number of objects that are selected;
See Also
161
, get
169
, getnamed
170
, getnamednumber
171
, set
167
10.7.18 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
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
161
, get
169
, getnumber
170
, getnamednumber
171
, set
167
, setnamed
168
Scripting Language
171
10.7.19 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
See Also
161
, get
169
, getnamed
170
, getnumber
170
, set
167
, setnamed
168
10.7.20 getglobal
Get the value of global properties in the current tab. Only applicable in the Sources and
Monitors tabs.
Syntax
Description
?getglobal;
Returns a list of the properties of the global properties in

the current tab.
out = getglobal("name");
Returns the value of the global property called "name".

Out can be a matrix or a string, depending on the property
requested.
See Also
161
, setglobal
168
, set
167
, get
169
10.7.21 haveproperty
Returns the number of selected objects with a particular property.
Syntax
Description
out = haveproperty
("property");
Returns the number of selected objects with the specified

property.
See Also
161
, get
169
, set
167
172
Reference Guide
10.7.22 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.
Syntax
Description
out = importsurface(filename,
Import a surface from the file in the string filename
upper_surface,file_units,x0,y0,z0, in a three dimensional simulation. All arguments
invertXY);
after filename are optional.
out = importsurface(filename,
upper_surface,file_units,x0,y0,
invertXY);
Parameter
filename
upper_surface
file_units
Import a surface from the file in the string filename

in a two dimensional simulation. All arguments after
filename are optional.
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.
x0
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 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.
Scripting Language
See Also
161
, importsurface2
173
173
10.7.23 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.
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.
out = importsurface2(Y,x,
upper_surface);
Import a surface from the variables Y and x in two

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
See Also
number This optional argument should be

1 to import the upper surface and
0 to import the lower surface.
required
161
, importsurface
172
matrix
This argument should be an Nx1

matrix that defines the surface for
two dimensional simulations.
174
Reference Guide
10.7.24 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.
Syntax
Description
out = importnk(filename,file_units, Import n (and k) data from filename in three

x0,y0,z0,reverse_index_order);
dimensional simulations. All arguments after the
out = importnk(filename,file_units, Import n and k data from filename in two
x0,y0,reverse_index_order);
dimensional simulations. All arguments after the
Parameter
Default value
Type
Description
filename
required
string
name of the file with n (and k)

data to import. May contain
complete path to file, or path
relative to current working
directory
file_units
"m"
string
The optional string argument

file_units can be "m", "cm, "mm",
"microns" or "nm" to specify the
units in the file.
x0
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 defined your
volume with respect 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
Scripting Language
175
graphical import before using the

script command.
See Also
161
, importnk2
175
10.7.25 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.
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

dimensional simulations. All arguments are
required.
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

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

should have dimension Mx1. For
two dimensional simulation, if n is
an NxM matrix then y should
have dimension Mx1.
See Also
number If n is an NxMxP matrix, then z

should have dimension Px1.
176
Reference Guide
161
, importnk
174
10.7.26 redraw
Redraws graphics.
Syntax
Description
redraw;
Redraws graphics.
See Also
161
, redrawon
176
, redrawoff
176
, redrawmode
176
10.7.27 redrawoff
This command will prevent redrawing while a script file is executing, unless you explicitly
request a redraw with the redraw command. This can speed up the execution of a script
file if you are manipulating many objects.
Syntax
Description
redrawoff;
Prevents redrawing of graphics.

See Also
161
, redrawon
176
, redraw
176
, redrawmode
176
10.7.28 redrawon
This command turns the redrawing back on. The graphics will be redrawn after any script
command that may change the properties of a graphical object.
Syntax
Description
redrawon;
Turns redrawing back on.

See Also
161
, redraw
176
, redrawoff
176
, redrawmode
176
10.7.29 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.
Scripting Language
177
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
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
161
, redraw
176
, redrawoff
176
10.7.30 setview
This command allows the viewing properties of the Layout Editor to be modified.
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.
178
Reference Guide
phi
See Also
Controls the azimuthal angle of the perspective view, in

degrees.
161
, getview
178
, orbit
178
, redraw
176
10.7.31 getview
This command allows the viewing properties of the Layout Editor to be retrieved.
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
See Also
161
, setview
177
, orbit
178
, redraw
177
176
10.7.32 orbit
This command performs an elliptical viewing orbit of the structure in the perspective view.
Note that the commands setview 177 , getview 178 and redraw 176 make it possible to
create any type of orbit you would like in your own script file.
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.
orbit(zoom_factor, frame_rate,
"filename");
The orbit will be streamed to the mpeg file filename

for later viewing.
Scripting Language
See Also
161
, setview
177
, getview
179
178
10.7.33 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
161
, redo
179
10.7.34 redo
Redo a command after a previous undo.
Syntax
Description
redo;
Redo command after previous undo.

See Also
161
, undo
179
10.8 Measurement data

Measurement and simulation data is stored within data structures called d-cards that are
either created by the user or created automatically to record and store appropriate
calculation data. D-cards can be:
Local: This means that they are a generated by the current simulation and will be lost
when switching back to layout mode.
Global: This means that they persist until deliberately cleared with a call to cleardcard.
Global d-cards are not saved with the file, and should be saved separately in an ldf
file.
The following commands are used to take inventory of which data structures exist, and to
determine the types of data available within each data structure.
Command
Description
showdata
180
Provides a list of existing d-cards, or shows the data

contained in a specific d-card.
havedata
180
Used to see if there is any data stored within a d-
180
Reference Guide
card.
copydcard
181
Creates a copy of a d-card.
cleardcard
181
Clears a d-card.
The following commands are used to retrieve data from d-cards.

Command
Description
getdata
Gets specific data from a d-card.
181
getelectric
Get |E|2
182
getmagnetic
Get |H|2
182
read and write data to file
182
Read and write data to a file.
10.8.1 showdata
Provides a list of existing d-cards, or shows the data contained in a specific d-card. To
retrieve data from the d-card, use getdata.
Syntax
Description
out = showdata;
Creates a string which lists all of the d-cards currently in

memory.
Use ?showdata; to display the list of data structures.
showdata("name");
Used to see the data stored within a particular d-card.

Creates a string with the names of all the variables
associated with a given data structure called "name".
See Also
Measurements
179
, getdata
181
, havedata
180
, copydcard
181
, cleardcard
181
, workspace
129
10.8.2 havedata
Used to see if there is any data stored within a d-card.
Syntax
Description
havedata;
Returns 1 if any of the d-cards currently in memory have

data, and 0 if none of the d-cards have any data.
havedata("name");
Returns 1 if the d-card named "name" has data, and 0 if it

does not have any data.
Scripting Language
See Also
Measurements
179
, getdata
181
, copydcard
181
, cleardcard
181
, workspace
181
129
10.8.3 copydcard
Will create a global copy of any d-card currently in memory.
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
179
, showdata
180
, havedata
180
, cleardcard
181
10.8.4 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.
Syntax
Description
cleardcard;
Clears all the global d-cards.

cleardcard( "name1",
"name2", ...);
Clears any number of specified d-cards.
See Also
Measurements
179
, showdata
180
, havedata
180
, copydcard
181
10.8.5 getdata
Gets monitor data from a d-card. To see what data is available, use showdata. The
output of this function will be normalized if the CW norm option is enabled.
Syntax
Description
out = getdata
( "monitorname",
"dataname");
Gets data from a d-card. For example, you could use

Ex = getdata("Monitor1","Ex");
To get the Ex field data from a data structure called
182
Reference Guide
"Monitor1".
getdata( "monitorname",
"dataname", option);
See Also
Measurements 179 , showdata
208 , cwnorm 208
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.
180
, havedata
180
, getelectric
182
, getmagnetic
182
, nonorm
10.8.6 getelectric
Returns the sum of the amplitude squares for all electric field components, i.e. it returns |
Ex|2+|Ey|2+|Ez|2.
Syntax
Description
out = getelectric
( "monitorname");
Returns |Ex|2+|Ey|2+|Ez|2 from the monitor.
See Also
Measurements
179
, showdata
180
, getdata
181
, getmagnetic
182
, cwnorm
208
, nonorm
208
10.8.7 getmagnetic
Returns the sum of the amplitude squares for all magnetic field components, i.e. it returns
|Hx|2+|Hy|2+|Hz|2.
Syntax
Description
out = getmagnetic
( "monitorname");
Returns |Hx|2+|Hy|2+|Hz|2 from the monitor.
See Also
Measurements
179
, showdata
180
, getdata
181
, getelectric
182
, cwnorm
208
, nonorm
208
10.8.8 Read and write data to files

Please see the following section for file I/O commands.
System level commands: File input and output 107
Scripting Language
183
10.9 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.
Command
Description
addmaterial
Adds a new material into the material database.
183
copymaterial
Copies an existing material in the material database
183
setmaterial
184
Sets any property of an existing material in the

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

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

FDTD simulation.
185
10.9.1 addmaterial
Adds a new material to the material database.
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
Material database
183
, setmaterial
184
, getindex
185
, getfdtdindex
10.9.2 copymaterial
Makes a copy of a material in the material database.
Syntax
Description
185
184
Reference Guide
out = copymaterial
("materialname");
See Also
Material database
183
Creates a copy of the material "materialname". The new

name is returned.
, setmaterial
184
, getindex
185
, getfdtdindex
185
10.9.3 setmaterial
Modifies properties of a material in the material database.
Syntax
Description
?setmaterial;
Displays the common property names of the base

material that can be modified.
setmaterial
( "materialname");
Displays the property names of the specified material that

can be modified.
setmaterial
Sets the property named "propertyname" of the material
( "materialname",
with the name "materialname" to newvalue. The argument
"propertyname", newvalue); 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
183
, addmaterial
183
, getmaterial
184
, getindex
185
, getfdtdindex
185
10.9.4 getmaterial
Returns properties of a material in the material database.
Syntax
Description
?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
183
, addmaterial
183
, setmaterial
184
, getindex
185
, getfdtdindex
185
Scripting Language
185
10.9.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.
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, Optional argument component can be 1, 2 or 3 to specify

component);
the x, y or z component for anisotropic materials. The
default is 1.
See Also
Material database
183
, getfdtdindex
185
, addmaterial
183
, setmaterial
184
10.9.6 getfdtdindex
This function returns the material index of a material in the database as it will be used in
an actual FDTD simulation.
In FDTD Solutions, many materials (such as Experimental 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.
Syntax
Description
out = getfdtdindex
( "materialname", f, fmin,
fmax);
Returns the complex index of the material with the given

name. The index is returned for the specified frequency f.
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", f,fmin,
fmax, 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
183
, getindex
185
, addmaterial
183
, setmaterial
184
186
Reference Guide
10.10User defined GUIs

Custom GUIs can be created with the following commands.
Command
Description
message
Creates a message window that displays some

text.
186
newwizard
Used to create a new user defined wizard.
187
newwizardpage
wizardwidget
runwizard
Adds a new widget to the current wizard window.
187
Runs the wizard and returns a value indicating

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

1. Open a new wizard with newwizard 187
2. Add a new wizard page with newwizardpage 187
3. Add widgets to the wizard page with wizardwidget 187
4. Call runwizard 188 to run the wizard
5. Use wizardgetdata 188 to obtain values entered into widgets by the user
6. Depending on the values returned by runwizard 188 , the wizard can be closed with
killwizard 188 , or a new wizard page is started with newwizardpage 187 .
10.10.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.

See Also
User defined GUI
186
, newwizard
187
Scripting Language
187
10.10.2 newwizard
Used to create a new user defined wizard. Opens a new wizard window.
Syntax
Description
newwizard( w, h, "title");
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
186
, message
186
10.10.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
186
, newwizardpage
187
10.10.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
"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.
188
Reference Guide
If the "type" of widget is a "menu", then the menu choices
must be provided. These choices should be separated by
the character "|". For example, to create a pulldown
wizardwidget( "type", "label",
widget with the name "simulation type" and 3 choices
"choices", defaultValue);
"TE","TM","3D", with the default choice "3D", the
command is
wizardwidget("menu","simulation type","TE|TM|3D",3);
See Also
User defined GUI
186
, newwizardpage
187
10.10.5 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
User defined GUI
186
, newwizardpage
187
10.10.6 wizardgetdata
Returns data entered into a specific widget.
This function is only available in MODE Solutions.
Syntax
Description
out = wizardgetdata(N);
See Also
User defined GUI
186
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.
, newwizardpage
187
10.10.7 killwizard
This closes the wizard window. It should only be called after a wizard window has been
created with the newwizard command.
Syntax
Description
Scripting Language
killwizard;
See Also
User defined GUI
189
This closes the wizard window.
186
, newwizardpage
187
10.10.8 wizardoption
Sets some options for wizard widgets and labels.
Syntax
Description
wizardoption ("optionname", The options are

setting);
"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
User defined GUI
186
, newwizard
187
10.10.9 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
186
, filesavedialog
190
190
Reference Guide
10.10.10 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 selects.
See Also
User defined GUIs
186
, fileopendialog
189
10.11FDTD Solutions toolbox

The Lumerical scripting language is designed to be the same throughout all Lumerical
products. However, each product has an additional set of specialized functions that will
differ from product to product.
Creating a workspace and working with fsp files
Command
Description
new2d
194
Creates a new 2D layout environment.
new3d
195
load
save
run
Loads an fsp file.
195
Saves the current environment as an fsp file.
196
Launch the simulation.
196
runparallel
197
Launch the simulation in parallel mode.
setparallel
197
Sets options for parallel simulations.
runanalysis
198
Runs the analysis script in analysis objects
Moving between tabs

Command
Description
structures
198
Switch to the STRUCTURES TAB.
simulation
198
Switch to the SIMULATION TAB.
sources
199
monitors
199
Switch to the SOURCES TAB.

Switch to the MONITORS TAB.
Scripting Language
switchtolayout
layoutmode
Closes the analysis window and allows you to

manipulate simulation objects for a new simulation.
199
Used to determine if the simulation file is open in

layout or in analysis mode.
199
Adding objects
Command
Description
addcircle
Add a circle primitive.
200
addcustom
addimport
Add a custom primitive.
200
Add an import primitive.
200
addpyramid
Add a pyramid primitive.
201
addpoly
201
Add a polygon primitive
addrect
201
Add a rectangle primitive.
addring
201
Add a ring primitive.
addsphere
addsurface
addfdtd
Add a sphere primitive.
202
Add a surface primitive.
202
addstructuregroup
202
Add a structure group.

Add an FDTD simulation area.
203
addmesh
203
Add a mesh override region.
adddipole
203
Add a dipole source.
addgaussian
Add a Gaussian source.
203
addplane
204
Add a plane source.
addmode
204
Add a mode source.
addtfsf
Add a TFSF source.
204
addimportedsource
addindex
addtime
191
205
205
205
Add an imported source.

Add an index monitor.
Add a time monitor.
addmovie
205
Add a movie monitor.
addprofile
206
Add a profile monitor.
addpower
206
Add a power monitor.
192
Reference Guide
addanalysisgroup
Add an analysis group.
206
Source settings, normalization and measurements

Command
Description
setsourcesignal
Set a custom source time signal.
207
updatesourcemode
clearsourcedata
getsourceangle
207
Updates the mode for a mode source.

Clears source data for an imported source, or the
selected mode for a mode source.
207
Get source angle.
208
nonorm
208
Use no normalization.
cwnorm
208
Use CW normalization.
sourcenorm
Returns the normalization used in the cwnorm state.
209
sourcenorm2_avg
sourcenorm2_pavg
dipolepower
210
Returns the source power.
211
sourcepower_avg
Returns the total spectral average power injected

into the simulation by the source.
212
sourcepower_pavg
sourceintensity
Returns the source normalization spectrum used to

normalize data in the cwnorm state for the partial
spectral averaged quantities
Returns the power injected into the simulation by a
dipole source.
211
sourcepower
213
215
sourceintensity_pavg
215
Returns the total spectral average intensity injected

Returns the partial spectral average intensity
injected into the simulation by the source.
Returns the power transmission through a monitor.
216
transmission_avg
Returns the partial spectral average power injected

Returns the source intensity.
214
sourceintensity_avg
transmission
Returns the source normalization spectrum used to

normalize data in the cwnorm state for the total
spectral averaged quantities
209
217
Returns the total spectral average power through a

monitor surface, normalized to the total spectral
average of the source.
Scripting Language
transmission_pavg
Command
farfieldfilter
farfield2d
218
Description
The far field filter is used to remove ripples in the far
field projection due to clipping of the near fields. It
should be used when the near fields at the edge of
the monitor are small but not precisely zero.
221
Projects a given power or field profile monitor to the

far field.
222
farfieldvector2d
farfieldpolar2d
farfieldangle
farfield3d
Returns the partial spectral average power through

a monitor surface, normalized to the partial spectral
average of the source.
217
Near to far field projections
193
223
223
Farfieldpolar2d is identical to farfield2d, however the

data is returned as matrix of Nx1x3, where the last
index refers to Er, Eq and Ez, in cylindrical
coordinates.
For 2D simulations. It returns the matrix of angles,
in degrees, corresponding to the data in farfield2d.
224
Projects a given power or field profile monitor to the

far field.
225
farfieldvector3d
farfieldpolar3d
Farfieldvector2d is identical to farfield2d, however

the data is returned as matrix of Nx1x3, where the
last index refers to Ex, Ey and Ez.
226
226
Farfieldvector3d is identical to farfield3d, however

the data is returned as matrix of NxMx3, where the
last index refers to Ex, Ey and Ez.
Farfieldpolar3d is identical to farfield3d, however the
data is returned as matrix of NxMx3, where the last
index refers to Er, Eq and Ef, in spherical
coordinates.
farfieldux
227
For 3D simulations. It returns the matrix of ux

corresponding to the data in farfield3d.
farfielduy
227
For 3D simulations. It returns the matrix of uy

corresponding to the data in farfield3d.
farfieldspherical
farfieldexact2d
227
229
Interpolates far field projection data from E(ux,uy) to

E(theta,phi).
Calculates the far field at any specified position.
194
Reference Guide
farfieldexact3d
farfieldexact
Calculates the far field at any specified position.
230
Similar to farfieldexact2d and farfieldexact3d,

however the far field is only evaluated at positions
explicitly specified by the vector list.
231
farfield2dintegrate
224
Calculates the integral of the far field projection over

some range of theta in 2D simulation
farfield3dintegrate
228
Calculates the integral of the far field projection over

a specified cone in 3D simulation
Grating calculations
232
Command
Description
grating
Returns the strength of all physical grating orders.
233
gratingn
Returns vector of integers corresponding to data

from grating function.
233
gratingm
Returns vector of integers corresponding to data

from grating function
234
gratingpolar
Returns the relative strength of all physical grating

orders in spherical coordinates.
234
gratingvector
235
Returns the relative strength of all physical grating

orders in Cartesian coordinates.
gratingperiod1
236
Returns grating period ax.
gratingperiod2
236
Returns grating period ay.
gratingbloch1
236
Returns bloch vector (kin)x.
gratingbloch2
237
Returns bloch vector (kin)y.
gratingu1
236
Returns first component of the unit vector ux.
gratingu2
237
Returns first component of the unit vector uy.
gratingangle
237
Returns the angle of each order.
10.11.1 new2d
Syntax
Description
new2d;

Scripting Language
new2d(option);
See Also
FDTD toolbox
190
195
The options are

1: use default fsp file and material database as
template
2: use current fsp file and material database as
template
3: open a file browser to select and existing fsp file as a
template
, new3d
195
10.11.2 new3d
Syntax
Description
new3d;

new3d(option);
The options are

1: use default fsp file and material database as
template
2: use current fsp file and material database as
template
3: open a file browser to select and existing fsp file as a
template
See Also
FDTD toolbox
190
, new2d
194
10.11.3 load
Loads an fsp file. These files contain all the simulation setup such as physical structures,
source position, etc. If the simulation has already been run, the file will also contain
simulation results.
Syntax
Description
load("filename.fsp");
Loads the fsp file.

See Also
FDTD toolbox
190
, loaddata
116
, save
196
, savedata
116
, savedcard
117
196
Reference Guide
10.11.4 save
Saves an fsp file. These files contain all the simulation setup such as physical structures,
source position, etc. If the simulation has already been run, the file will also contain
simulation results.
Syntax
Description
save;
Open a file browser to save the fsp file.

save("filename.fsp");
Save with the specified name
See Also
FDTD toolbox
190
, load
195
, loaddata
116
, savedata
116
, savedcard
117
10.11.5 run
Launch the simulation. When the simulation finishes, all simulation data will be saved to
the current file.
Syntax
Description
run;
Launch the simulation.

run(option1);
The option1 can be:

1: run fdtd with GUI progress tool (default)
2: run non-graphical fdtd. This is useful to prevent
warning windows from interrupting your simulations.
3: run parallel fdtd. equivalent to runparallel 197 .
run(option1,option2);
option2 can be:

0: When it is 0 no temporary material files are created
or saved.
1: When it is 1, a temporary material file called
filename.lmf (or filename_pN.lmf in parallel simulations)
is created, where the simulation file is called filename.
fsp.
>= 2: When it is greater than or equal to 2, the
temporary material file called called filename.lmf (or
filename_pN.lmf in parallel simulations) is read. The
default value is 0.
run(option1,option2,
filename);
The optional filename argument allows you to specify a

filename for the temporary material files, instead of the
default filename. This file will be forced automatically have
Scripting Language
the extension ".lmf".
See Also
FDTD toolbox
190
, runparallel
197
, runanalysis
198
10.11.6 runparallel
Launch the simulation in parallel mode. Equivalent to run(3). When the simulation
finishes, all simulation data will be saved to the current file.
Syntax
Description
runparallel;
Launch the simulation in parallel mode.

See Also
FDTD toolbox
190
, run
196
, setparallel
197
, runanalysis
198
10.11.7 setparallel
Sets the options required for parallel simulations. The property to be set has the same
name as shown in the Parallel Computing Options Window, as shown below. The
property name is not case sensitive and does not have to be complete: for example,
"command line arguments <args>" can be replace with "command line".
Syntax
Description
197
198
Reference Guide
setparallel("number of
nodes",8);
See Also
FDTD toolbox
190
, runparallel
Sets any available option in the Parallel Computing

Options window to the desired value.
197
10.11.8 runanalysis
Runs the analysis script in analysis objects.
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
FDTD toolbox
190
, run
196
10.11.9 structures
Syntax
Description
structures;

See Also
FDTD toolbox
190
, switchtolayout
199
10.11.10 simulation
Syntax
Description
simulation;

See Also
FDTD toolbox
190
, switchtolayout
199
Scripting Language
10.11.11 sources
Syntax
Description
sources;

See Also
FDTD toolbox
190
, switchtolayout
199
10.11.12 monitors
Syntax
Description
monitors;

See Also
FDTD toolbox
190
, switchtolayout
199
10.11.13 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 ob
jects.
Syntax
Description
switchtolayout;
Switches to LAYOUT mode.

See Also
FDTD toolbox
190
, layoutmode
199
10.11.14 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.
199
200
Reference Guide
See Also
FDTD toolbox
190
, switchtolayout
199
10.11.15 addcircle
Adds a circle primitive to the simulation environment. If necessary, the structures TAB
will be selected before adding the object.
Syntax
Description
addcircle;
Adds primitive to the simulation environment.

See Also
FDTD toolbox
190
10.11.16 addcustom
Adds a custom primitive to the simulation environment. If necessary, the structures TAB
Syntax
Description
addcustom;

See Also
FDTD toolbox
190
10.11.17 addimport
Adds an import primitive to the simulation environment. If necessary, the structures TAB
Syntax
Description
addimport;

See Also
FDTD toolbox
190
Scripting Language
201
10.11.18 addpyramid
Adds a pyramid primitive to the simulation environment. If necessary, the structures TAB
Syntax
Description
addpyramid;

See Also
FDTD toolbox
190
10.11.19 addpoly
Adds a polygon primitive to the simulation environment. If necessary, the structures TAB
Syntax
Description
addpoly;

See Also
FDTD toolbox
190
10.11.20 addrect
Adds a rectangle primitive to the simulation environment. If necessary, the structures
TAB will be selected before adding the object.
Syntax
Description
addrect;

See Also
FDTD toolbox
190
10.11.21 addring
Adds a ring primitive to the simulation environment. If necessary, the structures TAB will
be selected before adding the object.
Syntax
Description
addring;
202
Reference Guide
See Also
FDTD toolbox
190
10.11.22 addsphere
Adds a sphere primitive to the simulation environment. If necessary, the structures TAB
Syntax
Description
addsphere;

See Also
FDTD toolbox
190
10.11.23 addsurface
Adds a surface primitive to the simulation environment. If necessary, the structures TAB
Syntax
Description
addsurface;

See Also
FDTD toolbox
190
10.11.24 addstructuregroup
Adds a structure group to the simulation environment. If necessary, the structures TAB
Syntax
Description
addstructuregroup;
Adds a structure group to the simulation environment.

See Also
FDTD toolbox
190
, addtogroup
166
, adduserprop
167
, addanalysisgroup
206
Scripting Language
203
10.11.25 addfdtd
Adds a FDTD simulation area to the simulation environment. If necessary, the simulation
Syntax
Description
addfdtd;
Adds a simulation area to the simulation environment.

See Also
FDTD toolbox
190
10.11.26 addmesh
Adds a mesh override region to the simulation environment. If necessary, the simulation
Syntax
Description
addmesh;
Adds a mesh override region to the simulation

environment.
See Also
FDTD toolbox
190
10.11.27 adddipole
Adds a dipole source to the simulation environment. If necessary, the sources TAB will
Syntax
Description
adddipole;
Adds source to the simulation environment.

See Also
FDTD toolbox
190
10.11.28 addgaussian
Adds a gaussian source to the simulation environment. If necessary, the sources TAB
Syntax
Description
204
Reference Guide
addgaussian;
See Also
FDTD toolbox

190
10.11.29 addplane
Adds a plane wave source to the simulation environment. If necessary, the sources TAB
Syntax
Description
addplane;

See Also
FDTD toolbox
190
10.11.30 addmode
Adds a mode source to the simulation environment. If necessary, the sources TAB will
Syntax
Description
addmode;

See Also
FDTD toolbox
190
10.11.31 addtfsf
Adds a Total Field Scattered Field (tfsf) source to the simulation environment. If
necessary, the sources TAB will be selected before adding the object.
Syntax
Description
addtfsf;

See Also
FDTD toolbox
190
Scripting Language
205
10.11.32 addimportedsource
Adds an imported source to the simulation environment. If necessary, the sources TAB
Syntax
Description
addimportedsource;

See Also
FDTD toolbox
190
, asapimport
119
, asapload
118
, asapexport
118
10.11.33 addindex
Adds an index monitor to the simulation environment. If necessary, the monitors TAB will
Syntax
Description
addindex;
Adds monitor to the simulation environment.

See Also
FDTD toolbox
190
10.11.34 addtime
Adds a time monitor to the simulation environment. If necessary, the monitors TAB will
Syntax
Description
addtime;

See Also
FDTD toolbox
190
10.11.35 addmovie
Adds a movie monitor to the simulation environment. If necessary, the monitors TAB will
Syntax
Description
addmovie;
206
Reference Guide
See Also
FDTD toolbox
190
10.11.36 addprofile
Adds a profile monitor to the simulation environment. If necessary, the monitors TAB will
Syntax
Description
addprofile;

See Also
FDTD toolbox
190
10.11.37 addpower
Adds a power monitor to the simulation environment. If necessary, the monitors TAB will
Syntax
Description
addpower;

See Also
FDTD toolbox
190
10.11.38 addanalysisgroup
Adds an analysis group to the simulation environment. If necessary, the monitors TAB
Syntax
Description
addanalysisgroup;
Adds an analysis group to the simulation environment.

See Also
FDTD toolbox
190
, addtogroup
166
, addstructuregroup
202
Scripting Language
207
10.11.39 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 by FDTD Solutions.
Syntax
Description
setsourcesignal("name", t, Sets the time domain signal of source named "name". t,

amplitude, phase);
amplitude, and phase are 1D vectors with the same length.
setsourcesignal("name", t, Allows you to specify the precise center frequency and
amplitude, phase, fcentre, bandwidth that will be used for all simulations. These
bandwidth);
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
FDTD toolbox
190
, sourcepower
211
10.11.40 updatesourcemode
Updates the mode profile of a 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.
Syntax
Description
updatesourcemode;
Updates mode profile of a MODE source.
See Also
FDTD toolbox
190
, addmode
204
, clearsourcedata
207
10.11.41 clearsourcedata
Clears source data for an imported source, or the selected mode for a mode source.
Syntax
Description
clearsourcedata;
Clears source data for the selected source.
See Also
FDTD toolbox
190
, updatesourcemode
207
, asapimport
119
, asapload
118
, asapexport
118
208
Reference Guide
10.11.42 getsourceangle
Broadband sources inject fields that have a constant in-plane wavevector at all
frequencies. Therefore, the injection angle must change as a function of frequency. The
in-plane wavevector is chosen such that the incidence angle at the center frequency of
the simulation will match the source angle theta specified in the source properties.
Higher frequencies will be injected at smaller angles, while lower frequencies will be
injected at larger angles.
This function returns the injection angle as a function of frequency.
Syntax
Description
theta = getsourceangle(
"sourcename", f);
Returns the source angle theta (degrees) as a function of

frequency. f is a vector of frequencies (Hz).
See Also
FDTD toolbox 190 , sourcepower
injection angles
211
, Online Help-User Guide-Sources-Broadband
10.11.43 nonorm
Do not normalized the data to the source power. The actual field intensities will be used
in all calculations.
This function controls the checkbox located in Settings - Frequency domain.
Syntax
Description
nonorm;
Use no normalization.
See Also
FDTD toolbox
190
, cwnorm
208
, Units and Normalization
20
10.11.44 cwnorm
Use CW normalization. All simulation data will be normalized to the injected source
power. Most users prefer to do their analysis in the CW normalization state, since it
removes any effect caused by the finite pulse length of the source. It also converts the
units of all electromagnetic fields to be the same as in the time domain.
This function controls the checkbox located in Settings - Frequency domain.
Syntax
Description
cwnorm;
Use CW normalization.
Scripting Language
See Also
FDTD toolbox
190
, nonorm
208
209
20
10.11.45 sourcenorm
Returns the source normalization spectrum used to normalize data in the cwnorm state
for standard fourier transform quantities. See the Units and normalization chapter for
more information.
If the source time signal of the jth source in the simulation is sj(t), and N is the number of
active sources then
Syntax
Description
out = sourcenorm(f);
Returns the source normalization used to normalize data

in the cwnorm state at the vector of frequency points f. (f
is the frequency in Hz)
out = sourcenorm(f, name);
This function makes it possible to perform the

normalization using the spectrum of one source, rather
than the sum of all the sources.
See Also
FDTD toolbox 190 , sourcenorm2_avg 209 , sourcenorm2_pavg
cwnorm 208 , nonorm 208 , Units and Normalization 20
210
, sourcepower
211
10.11.46 sourcenorm2_avg
for the total spectral averaged quantities. See the Units and normalization - Spectral
averaging 24 section for more information.
The script function sourcenorm is defined as
If sourcenorm2_avg is called without any arguments, it returns
Syntax
Description
210
Reference Guide
out = sourcenorm2_avg;
This function returns the source normalization for total

spectral averaged quantities.
out = sourcenorm2_avg(
"sourcename");

See Also
FDTD toolbox 190 , sourcenorm 209 , sourcenorm2_pavg 210 , sourcepower_avg
cwnorm 208 , nonorm 208 , Units and Normalization 20 , Spectral averaging 24
212
10.11.47 sourcenorm2_pavg
for the partial spectral averaged quantities. See the Units and normalization - Spectral
If the source time signal of the jth source in the simulation is sj(t), and N is the number of
active sources then
Partial spectral averaging uses a Lorentzian weighting of the following form. Delta is the
FWHM of |h|2.
If this function is called without any arguments, it returns
Syntax
Description
out = sourcenorm2_pavg( f, This function returns the source normalization for partial
delta);
spectral averaged quantities.
out = sourcenorm2_pavg( f, This function makes it possible to perform the
delta, "sourcename");
See Also
FDTD toolbox
190
, sourcenorm
209
, sourcenorm2_avg
209
, sourcepower_pavg
213
Scripting Language
cwnorm
208
, nonorm
208
20
, Spectral averaging
211
24
10.11.48 dipolepower
Returns the power injected into the simulation region by a dipole source. In 3D
simulations, the units will be in Watts if cw norm is used, and Watts/Hertz2 if no norm is
used.
The dipolepower script command returns the power that was injected into the simulation
region, and is equivalent to measuring the power transmitted out of a small box
surrounding the dipole. In contrast, sourcepower 211 will return the power that an ideal
dipole would radiate in a homogeneous material. dipolepower and sourcepower are
equivalent for homogeneous materials.
Advanced notes:
There can be some numerical errors in this calculation that become significant when
small mesh sizes are used. If the mesh step is the order of, or smaller than, l/500, it
may be necessary to measure this quantity using a small box of power monitors
surrounding the dipole.
If the dipole is injected into a dispersive medium with a non-zero imaginary part of the
refractive index, then the results of this function are not reliable.
Please contact support@lumerical.com for more assistance if you are using a dipole in
dispersive medium, or in a fine mesh region, and would like to calculate the total power
emitted by the dipole.
Syntax
Description
out = dipolepower(f);
Returns the dipole power used to normalize transmission

calculations at the vector of frequency points f. (f is the
frequency in Hz)
out = dipolepower(f, name);

See Also
FDTD toolbox 190 , sourcenorm 209 , sourcepower 211 , sourcepower_avg 212 ,
sourcepower_pavg 213 , transmission 216 , cwnorm 208 , nonorm 208 , Units and
Normalization 20
10.11.49 sourcepower
Returns the power injected into the simulation by the source. In 3D simulations, the units
will be in Watts if CW norm is used, and Watts/Hertz2 if No norm is used.
The exact output of sourcepower depends on the type of source used.
For beam sources (plane wave, gaussian, etc), each source records the poynting vector
212
Reference Guide
at its position, which is integrated to give the sources injected power.
For point sources (dipoles), sourcepower will return the power that an ideal dipole would
inject into homogeneous material. Use the dipolepower 211 script function to obtain the
power that was actually injected into the simulation region.
Syntax
Description
out = sourcepower(f);
Returns the source power used to normalize transmission

calculations at the vector of frequency points f. (f is the
frequency in Hz)
out = sourcepower(f,
option);
The additional 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
out = sourcepower(f, option, This function makes it possible to perform the

name);
See Also
FDTD toolbox 190 , sourcenorm 209 , sourcepower_avg 212 , sourcepower_pavg 213 ,
dipolepower 211 , transmission 216 , cwnorm 208 , nonorm 208 , Units and Normalization
20
10.11.50 sourcepower_avg
Returns the total spectral average power injected into the simulation by the source. See
the Units and normalization - Spectral averaging 24 section for more information.
This script function calculates the following quantities, depending on whether the
normalization state is cwnorm or nonorm:
Scripting Language
213
where sourcepower is the quantity returned by the sourcepower script function, s(w) is
returned by sourcenorm, and w=2pf. Typically, this function should be used in the cwnorm
state. Also see the sourcenorm2_pavg script function.
Syntax
Description
out = sourcepower_avg;
Returns the spectrally averaged source power as defined

above.
out =
sourcepower_avg(option);

out =
sourcepower_avg(option,
"sourcename");

See Also
FDTD toolbox 190 , sourcenorm2_avg 209 , sourcepower 211 , sourcepower_pavg 213 ,
transmission_avg 217 , cwnorm 208 , nonorm 208 , Units and Normalization 20 , Spectral
averaging 24
10.11.51 sourcepower_pavg
Returns the partial spectral average power injected into the simulation by the source. See
the Units and normalization - Spectral averaging 24 section for more information.
Partial spectral averaging uses a Lorentzian weighting of the form
This script function calculates the following quantities, depending on whether the
normalization state is cwnorm or nonorm:
214
Reference Guide
where sourcepower is the quantity returned by the sourcepower script function, s(w) is
returned by sourcenorm, and w=2pf. Typically, this function should be used in the cwnorm
state. Also see the sourcenorm2_pavg script function.
Syntax
Description
out = sourcepower_pavg(f);

above. The quantity f is the frequency in Hz.
out = sourcepower_pavg(f,
option);

out = sourcepower_pavg(f,
option, "sourcename");

See Also
FDTD toolbox 190 , sourcenorm2_pavg 210 , sourcepower 211 , sourcepower_avg 212 ,
transmission_pavg 217 , cwnorm 208 , nonorm 208 , Units and Normalization 20 , Spectral
averaging 24
10.11.52 sourceintensity
Sourceintensity returns the source power divided by the area of the source. In 3D
simulations, the units will be in Watts/m2 if CW norm is used, and Watts/m2/Hertz2 if No
norm is used. For more information see the sourcepower 211 script command.
Syntax
Description
out = sourceintensity(f);
Returns the source intensity at the vector of frequency

points f (f is the frequency in Hz).
out = sourceintensity(f,
option);

Scripting Language
215

out = sourceintensity(f,
option, name);

See Also
FDTD toolbox 190 , sourcenorm 209 , sourcepower 211 , sourceintensity_avg 215 ,
sourceintensity_pavg 215 , dipolepower 211 , transmission 216 , cwnorm 208 , nonorm
Units and Normalization 20
208
10.11.53 sourceintensity_avg
Returns the total spectral average intensity injected into the simulation by the source. The
average intensity is equal to the average power divided by the source area. See the
sourcepower_pavg 213 command and the Units and normalization - Spectral averaging 24
section for more information.
Syntax
Description
out = sourceintensity_avg;
Returns the spectrally averaged source intensity as

defined above.
out =
sourceintensity_avg(option); 2. If it is 2, the data is unfolded where possible according
out =
sourceintensity_avg(option,
"sourcename");

See Also
FDTD toolbox 190 , sourcenorm2_avg 209 , sourceintensity 214 , sourcepower 211 ,
transmission_avg 217 , cwnorm 208 , nonorm 208 , Units and Normalization 20 , Spectral
averaging 24
10.11.54 sourceintensity_pavg
Returns the partial spectral average intensity injected into the simulation by the source.
The partial average intensity is equal to the partial average power divided by the source
area. See the sourcepower_pavg 213 command and the Units and normalization Spectral averaging 24 section for more information.
216
Reference Guide
Syntax
Description
out =
sourceintensity_pavg(f);

above. The quantity f is the frequency in Hz.
out =
sourceintensity_pavg(f,
option);

out =
sourceintensity_pavg(f,
option, "sourcename");

See Also
FDTD toolbox 190 , sourcenorm2_pavg 210 , sourcepower 211 , sourcepower_avg 212 ,
transmission_pavg 217 , cwnorm 208 , nonorm 208 , Units and Normalization 20 , Spectral
averaging 24
10.11.55 transmission
The transmission function returns the amount of power transmitted through power
monitors and profile monitors, normalized to the source power. The transmission is
calculated with the following formula.
where T(f) is the normalized transmission as a function of frequency

P(f) is the Poynting vector
dS is the surface normal
The normalization state (cwnorm or nonorm) does not affect the result because of the
source power normalization.
Syntax
Description
out = transmission(
"monitorname");
Calculate transmission through monitorname. It must be

obvious from the shape of the monitor which axis is
normal to the monitor surface.
out = transmission(
"monitorname", option);

Scripting Language
See Also
FDTD toolbox 190 , sourcepower
transmission_pavg 217
211
, dipolepower
211
, transmission_avg
217
217
10.11.56 transmission_avg
Returns the total spectral average power through a monitor surface, normalized to the
total spectral average of the source. See the Units and normalization - Spectral averaging
24 section for more information.
where Tavg is the normalized total spectral average transmission

<P> is the total spectral average Poynting vector
Syntax
Description
out = transmission_avg(
"monitorname");
Returns the total spectral average transmission through

monitorname. It must be obvious from the shape of the
monitor which axis is normal to the monitor surface.
out = transmission_avg(
"monitorname", option);

See Also
FDTD toolbox 190 , sourcepower_avg 212 , transmission
and Normalization 20 , Spectral averaging 24
216
, transmission_pavg
217
, Units
10.11.57 transmission_pavg
Returns the partial spectral average power through a monitor surface, normalized to the
partial spectral average of the source. See the Units and normalization - Spectral
where Tpavg is the normalized partial spectral average transmission

<P> is the partial spectral average Poynting vector
218
Reference Guide
Syntax
Description
out = transmission_pavg(
"monitorname" );
Returns the partial spectral average transmission through

monitorname. It must be obvious from the shape of the
monitor which axis is normal to the monitor surface.
out = transmission_pavg(
"monitorname", option );

See Also
FDTD toolbox 190 , sourcepower_pavg 213 , transmission
and Normalization 20 , Spectral averaging 24
216
, transmission_avg
217
, Units
10.11.58 Near to far field projections

FDTD Solutions allows you to perform projections of the near field electromagnetic field to
the far field with simple script commands. The far field projections can be performed in
two cases:
Case 1
The electromagnetic fields are known on a
surface, for example at z=0. The field can be
projected to any point in the half-space above
the surface (z>0). This will be accurate when
The electromagnetic fields are zero at the
edges of the surface used for the projection.
The surface is one unit cell of a periodic
structure and periodicity is assumed in the
far field projection.
Symmetric and anti-symmetric boundaries can
be used in the simulation because the data is
unfolded prior to performing the projection.
In this case, we typically project the field as a
function of angle into the half-space above the
surface. This projection is fast because it can
make use of ffts to perform the projection. This
projection cannot be used to calculate the
fields at an intermediate distance of a few
Scripting Language
219
wavelengths.
Case 2
The electromagnetic fields are known on the
surface of a box. The field can be projected to
any point outside the box.
It is necessary to surround the scattering
object with 6 surface monitors and add the
results of 6 projections coherently using an
exact far field projection. This projection is
slow because it does not make use of ffts. This
projection can be used to calculate the fields
as close as a few wavelengths from where
they were recorded.
Field normalization
The far field projection functions farfield2d, farfield3d, farfieldvector2d,
farfieldvector3d, farfieldpolar2d and farfieldpolar3d return either the
complex electric field( ) or electric field intensity (|E|2) at a distance of 1m. To scale the
field to a different distance we can recognize that the electric field intensity decreases like
1/R in 2D and 1/R2 in 3D. This means that
|E(R)|2 = |E0|2/R in 2D
|E(R)|2 = |E0|2/R2 in 3D
where E0 is the field at a distance of 1 m as returned by the far field scripting functions
and R is measured in meters. The electric field will scale as
in 2D
in 3D
Power Integrals
In general, we want to integrate power over a given solid angle in the far field. There are 2
ways this can be done
1. We integrate the fraction of total electric field intensity (|E|2) over the solid angle that
we are interested in, and multiply by the normalized power transmission through the
monitor in the near field.
2. We calculate the Poynting vector in the far field and integrate the power over a given
solid angle. We then normalize to the original source power. In the far field, we can use
plane wave relationships between E and H. Therefore the Poynting vector is simply
Both methods will give the same result.
220
Reference Guide
Coordinate Systems
For some far field projections, it is important to calculate the vectorial components of the
electric field in order to determine the polarization properties. In 3D, the commands
farfieldvector3d and farfieldpolar3d will return the vector field components. In
2D, use farfieldvector2d and farfieldpolar2d.
These commands return three complex components of the electromagnetic field. All the
properties of the polarization of the field can be determined from the amplitudes and
phases of these components.
The difference between farfieldvector3d and farfieldpolar3d is the coordinate
system for defining the components of the electric field. farfieldvector3d uses a
Cartesian coordinate system and farfieldpolar3d uses a spherical coordinate
system.
farfieldvector3d
farfieldpolar3d
Note on performing integrals

We typically want to perform integrals in spherical coordinates such as the following
where P is the poynting vector and R is the radius. The far field projections in FDTD
Solutions return the electric field as a function of the variables ux and uy which are the x
and y components of the unit direction vector. The unit direction vector is related to the
angular variables by
Scripting Language
221
When changing integration variables from (q,j) to (ux,uy), it can be shown that
Care must be taken to avoid numerical errors due to the cos(q) term. Examples can be
found in the FDTD Online Help - User Guide - Analysis - Far Field Projections section
of Lumerical's website.
See Also
FDTD toolbox
190
, farfield2d
222
, farfield3d
225
10.11.59 farfieldfilter
The far field filter is used to remove ripples in the far field projection due to clipping of the
near fields. It should be used when the near fields at the edge of the monitor are small but
not precisely zero. The far field filter has a single input parameter, which is a number
between 0 and 1. By default, it is 0, which turns the filter off. This filter is applied to all far
field projections.
222
Reference Guide
The bumpy blue line of the figure shows the
near field electric field that will be used for a
far field projection. In this case, the field
does not go to zero at the edge of the
monitor, which will lead to ripples in the far
field projection. The green line shows the
the spatial filter that will be applied to the
fields, ensuring they go to zero. The filter
parameter defines the width of the filter by
the following formula: a=(a)/(a+b).
Syntax
Description
out = farfieldfilter;
Get the current far field filter setting.
farfieldfilter(alpha);
Set the current far field filter setting.
Note: Periodic structures

The far field filter option should not be used for periodic structures. Set it to zero when
using the 'assume periodic' option.
See Also
FDTD toolbox
190
, farfield2d
222
, farfield3d
225
10.11.60 farfield2d
Projects a given power or field profile monitor to the far field. The electric field intensity
|E|2 is returned.
Syntax
Description
E2 = farfield2d("mname", f,
n, illumination, periods,
index, direction);
Projects a given power or field profile monitor to the far

field.
Parameter
Default
value
mname
required
optional
Type
Description
string
Name of the monitor
number
Index of the desired frequency

point.
Scripting Language
223
optional
2000
number
The number of points in the

far field.
illumination
optional
number
For periodic structures

Gaussian illumination: 1
Plane wave illumination: 2
periods
optional
number
number of periods to be used
index
optional
value at
monitor
center
number
The index of the material to

use for the projection.
direction
optional
direction of
max power
flow
number
Direction: this can be +1 or

-1.
See Also
FDTD toolbox 190 , Far field projections
223 , farfieldpolar2d 223 , farfieldexact2d
218
229
, farfield3d 225 , farfieldangle 224 , farfieldvector2d

, farfieldfilter 221 , farfieldexact 231
10.11.61 farfieldvector2d
The function farfieldvector2d is similar to farfield2d, but it returns the complex electric
fields, rather than field intensity. The data is returned as matrix of Nx3, where the last
index refers to Ex, Ey and Ez which are the complex components of the electric field
vector.
Syntax
Description
out = farfieldvector2d(
"mname",...);
Returns the cartesian complex electric fields. Same

arguments as farfield2d.
See Also
FDTD toolbox
190
, farfield2d
222
10.11.62 farfieldpolar2d
The function farfieldpolar2d is similar to farfield2d, but it returns the complex electric
fields, rather than field intensity. The data is returned as matrix of Nx3, where the last
index refers to Er, Eq and Ez, in cylindrical coordinates. For TM simulations, this function
gives precisely the result of farfieldvector2d because the only non-zero field component is
Ez.
Syntax
Description
out = farfieldpolar2d(
"mname",...);
Returns the polar complex electric fields. Same

224
Reference Guide
See Also
FDTD toolbox
190
, farfield2d
222
, farfieldvector2d
223
10.11.63 farfieldangle
Used for 2D simulations. It returns the matrix of angles, in degrees, corresponding to the
data in farfield2d. This is required because the projection does not use a set of linearly
spaced angles for the projection. It is often useful to re-interpolate the data onto a set of
linearly spaced angles using the interp or spline functions.
Syntax
Description
theta = farfieldangle(
"mname", f, n, index);
Returns the matrix of angles corresponding to the data in

farfield2d
Parameter
Default
value
Type
Description
string
Name of the monitor from

which far field is calculated
mname
required
optional
number

point.
optional
2000
number

far field.
index
optional
value at
monitor
center
number

See Also
FDTD toolbox
190
, farfield2d
222
10.11.64 farfield2dintegrate
Used in 2D simulations, this function integrates the far field projection over some range of
theta. Angles are specified in degrees, but the integral is done in radians.
Syntax
Description
out =
farfield2dintegrate(E2,
Integrate 2D far field projection data.
Scripting Language
225
theta, halfangle, theta0);

Parameter
Default
value
Type
Description
E2
required
matrix
E field data from farfield2d
theta
required
matrix
Theta from farfieldangle
halfangle
optional
90
vector
Half angle (in degrees) of the

integration region. Must have
same length as theta0 or
length 1.
theta0
optional
vector
Center angle (in degrees)

theta of the integration region.
Must have same length as
halfangle or length 1.
See Also
FDTD toolbox
190
, Near to far field projections
218
, farfield2d
222
, farfieldangle
224
10.11.65 farfield3d
Projects a given power or field profile monitor to the far field. The electric field intensity
|E|2 is returned.
Syntax
Description
out = farfield3d("mname",f,
na, nb, illumination,
periodsa, periodsb, index,
direction);

field. For directions, when projecting in
x: a is y and b is z
y: a is x and b is z
z: a is x and b is y
Parameter
Default
value
Type
Description
string
Name of the monitor
mname
required
optional
number

point.
na
optional
150
number

far field.
nb
optional
150
number

far field.
226
Reference Guide
illumination
optional
number
For periodic structures.

Gaussian illumination: 1
Plane wave illumination: 2
periodsa
optional
number

for periodic illumination
periodsb
optional
number

for periodic illumination
index
optional
value at
monitor
center
number

direction
optional
direction of
max power
flow
number
Direction: this can be +1 or -1.
See Also
FDTD toolbox 190 , Far field projections 218 , farfield2d 222 , farfieldvector3d 226 ,
farfieldpolar3d 226 , farfieldux 227 , farfielduy 227 , farfieldexact3d 230 , farfieldfilter
221
10.11.66 farfieldvector3d
The function farfieldvector3d is similar to farfield3d, but it returns the complex electric
fields, rather than field intensity. The data is returned as matrix of NxMx3, where N and
M are spatial indices and the last index refers to Ex, Ey and Ez. The components Ex, Ey
and Ez are the complex components of the electric field vector.
Syntax
Description
out = farfieldvector3d(
"monitorname",...);
Returns the cartesian complex electric fields. Same

See Also
FDTD toolbox
190
, farfield3d
225
10.11.67 farfieldpolar3d
The function farfieldpolar3d is similar to farfield3d, but it returns the complex electric
fields, rather than field intensity. The data is returned as matrix of NxMx3, where N and
M are spatial indices and the last index refers to Er, Eq and Ej, in spherical coordinates.
The components Er, Eq and Ej are the complex components of the electric field vector.
Syntax
Description
out = farfieldpolar3d(
"monitorname",...);
Returns the spherical complex electric fields. Same

Scripting Language
See Also
FDTD toolbox
190
, farfield3d
225
, farfieldvector3d
227
226
10.11.68 farfieldux
Used for 3D simulations. It returns the matrix of ux corresponding to the data in farfield3d.
When projecting in
x: ux corresponds to y
y: ux corresponds to x
z: ux corresponds to x
Syntax
Description
farfieldux("mname",f,na,nb,i See farfield3d help. Arguments are same as for

ndex);
farfield3d.
See Also
FDTD toolbox
190
, farfield3d
225
, farfielduy
227
, farfieldspherical
227
, farfieldexact
231
10.11.69 farfielduy
Used for 3D simulations. It returns the matrix of uy corresponding to the data in farfield3d.
When projecting in
x: uy corresponds to z
y: uy corresponds to z
z: uy corresponds to y
Syntax
Description
farfielduy("mname",f,na,nb,i See farfield3d help. Arguments are same as for

ndex);
farfield3d.
See Also
FDTD toolbox
190
, farfield3d
225
, farfieldux
227
, farfieldspherical
227
, farfieldexact
231
10.11.70 farfieldspherical
This functions interpolates far field data (3D simulations) from E(ux,uy) to E(theta,phi).
The far field projections functions generally return the projection as a function of ux,uy
(direction cosines). farfieldspherical can be used to interpolate this data into the more
common units of theta, phi.
Syntax
Description
out = farfieldspherical( E2, interpolate far field data to spherical coordinates.

ux, uy, theta, phi);
228
Reference Guide
Parameter
Default
value
Type
Description
E2
required
matrix
ux
required
vector
ux data from farfieldux
uy
required
vector
uy data from farfielduy
theta
required
vector
theta vector, in degrees. Must

have length L or 1.
phi
required
vector
phi vector, in degrees. Must

have length L or 1.
See Also
FDTD toolbox
190
, Far field projections
218
, farfield3d
225
, farfieldux
227
, farfielduy
227
10.11.71 farfield3dintegrate
Used in 3D simulations, this function integrates the far field projection over a cone
centered at theta0 and phi0, with a width specified by halfangle. The far field electric field
is a function of the direction cosines (ux,uy), but farfield3dintegrate automatically does the
change of variables. Similarly, angles are specified in degrees, but converted to radians
before the integral is calculated.
Syntax
Description
out =
farfield3dintegrate(E2, ux,
uy, halfangle, theta0,
phi0);
Integrate 3D far field projection data.
Parameter
Default
value
Type
Description
E2
required
matrix
ux
required
vector
ux data from farfieldux
uy
required
vector
uy data from farfielduy
halfangle
optional
vector
half angle of the integration

cone. unit in degrees. must
have length L or 1.
90
Scripting Language
229
theta0
optional
vector
center angle theta of the

integration cone. unit in
degrees. must have length L
or 1.
phi0
optional
vector
center angle phi of the

integration cone. unit in
degrees. must have length L
or 1.
See Also
FDTD toolbox 190 , Near to far field projections
227 , farfieldspherical 227
218
, farfield3d
225
, farfieldux
227
, farfielduy
10.11.72 farfieldexact2d
This function projects complete complex vector fields to specific locations. It is expected
to be correct down to distances on the order of one wavelength. The projections from
multiple monitors can be added to create a total far field projection.
farfieldexact2d projects any surface to the grid points defined by the vectors x, y. The
data is returned in the form of a matrix that is of dimension NxMx3 where N is the length
of the x vector, M is the length of the y vector and the final index represents Ex, Ey, and
Ez. Note that N and M can be 1; when they are both 1, the function is the same as
farfieldexact.
Syntax
Description
out = farfieldexact2d(
"mname", x, y, f, index);

field at grid points specified by the vectors x,y.
Parame
ter
Default
value
Type
Description
mname
required
string
name of the monitor from which far field is

calculated
required
vector
x coordinates of the grid points where far field is

calculated
required
vector
y coordinates of the grid points where far field is

calculated
optional
index
optional index at number The index of the material to use for the
monitor
projection.
center
number Index of the desired frequency point.
230
Reference Guide
See Also
FDTD toolbox
190
, farfield2d
222
, farfieldexact3d
230
, farfieldexact
231
10.11.73 farfieldexact3d
The three dimension form of farfieldexact2d. This function projects complete complex
vector fields to specific locations. It is expected to be correct down to distances on the
order of one wavelength. The projections from multiple monitors can be added to create a
total far field projection.
farfieldexact3d projects any surface to the grid points defined by the vectors x,y and z.
The data is returned in a matrix of dimension NxMxKx3 where N is the length of the
vector x, M the length of the vector y, K is the length of the vector z and the final index
represents Ex, Ey, and Ez. Note that N, M and K can be 1, and when they are all 1, the
function is the same as farfieldexact.
Syntax
Description
out = farfieldexact3d(
"mname", x, y, z, f, index);

field at grid points specified by the vectors x,y,z.
Parameter
Default
value
Type
Description
mname
required
string
name of the monitor from

required
vector
x coordinates of the grid points

where far field is calculated
required
vector
y coordinates of the grid points

required
vector
z coordinates of the grid points

optional
number

point.
index
optional
value at
monitor
center
number

See Also
FDTD toolbox
190
, farfield3d
225
, farfieldexact2d
229
, farfieldexact
231
Scripting Language
231
10.11.74 farfieldexact
This function projects complete complex vector fields to specific locations. It is expected
to be correct down to distances on the order of one wavelength. The projections from
multiple monitors can be added to create a total far field projection.
farfieldexact projects any surface fields to a series of points defined by vector lists. The
x,y, z coordinates of each evaluation point are taken element-by-element from the vector
lists. i.e., the i-th point in a 2D simulation would be at [x(i),y(i)].
3D
Vectors lists x,y,z must have the same length L or be length 1. The data is returned in a
matrix of dimension Lx3. The first index represents positions defined by one element
from each of x,y, z. [x(i),y(i),z(i)]; the second index represents Ex, Ey, and Ez.
2D
Vector lists x, y must have the same length L or be length 1. The data is returned in the
form of a matrix that is of dimension Lx3. The first index represents positions defined by
one element from each of x,y. [x(i),y(i)]; The second index represents Ex, Ey, and Ez.
Syntax
Description
out =
farfieldexact("mname", x, y,
f, index)
2D far field exact projection
out =
farfieldexact("mname", x, y,
z, f, index);
3D far field exact projection
Parameter
Default
mname
Type
Description
required
string

required
vector
x coordinates of points where

far field is calculated. must
have length L or 1.
required
vector
y coordinates of points where

have length L or 1.
required
vector
z coordinates of points where

have length L or 1.
optional
number

point.
Default
value
232
Reference Guide
index
See Also
FDTD toolbox
optional
190
, farfield2d
value at
monitor
center
222
, farfield3d
number
225

, farfieldexact2d
229
, farfieldexact3d
230
10.11.75 Grating calculations

The following commands are used to obtain information on the strengths of orders from
gratings. They should be used for periodic structures that were simulated using periodic
or Bloch boundary conditions.
To understand the meaning of these functions, consider a grating as shown below:
The grating orders are defined by:
where ax and ay are the grating periods in the x and y directions respectively and (n,m)
are any integers where the condition
can be satisfied. In the
following grating functions, the x and y components of the incoming k vector are
determined from the Bloch boundary conditions (or periodic boundary conditions) used
during the simulation. They should also correspond to the x and y components of the
source k vector.
See Also
FDTD toolbox
190
Scripting Language
233
10.11.76 grating
Returns the relative strength of all physical grating orders for a given simulation. The
result corresponds to the fraction of power that is reflected or transmitted into a particular
order. Results are normalized such that the sum of all the orders is equal to 1.
3D simulations: Data is returned in a N x M matrix where N,M are the number of grating
orders.
2D simulations: Data is returned in a N matrix where N is the number of grating orders.
Syntax
Description
out =
grating("monitorname",f,
index, direction );
Returns the strength of all physical grating orders from

monitorname.
Parameter
Default
value
Type
Description
string

monitornam
e
required
optional
number

point.
index
optional
value at
monitor
center
number

direction
optional
direction of
max power
flow
number

-1.
See Also
FDTD toolbox 190 , Grating calculations 232 , gratingn 233 , gratingperiod1
236 , gratingu1 236 , gratingangle 237 , gratingpolar 234 , gratingvector 235
236
, gratingbloch1
10.11.77 gratingn
Returns the vector of integers, n, corresponding to the values returned by grating.
Syntax
Description
out = gratingn(
"monitorname",...);
Same arguments as grating function.
See Also
FDTD toolbox
190
, grating
233
, gratingm
234
234
Reference Guide
10.11.78 gratingm
Returns the vector of integers, m, corresponding to the values returned by grating. Only
used in 3D simulations.
Syntax
Description
out = gratingm(
"monitorname",...);
See Also
FDTD toolbox
190
, grating
233
, gratingn
233
10.11.79 gratingpolar
order. Results are normalized such that the sum of all the orders is equal to 1. Very
similar to the basic grating function, except that the vector field information is returned in
spherical coordinates. This is useful when studying the polarization effects.
3D simulations: Data is returned in a N x M x 3 matrix where N,M are the number of
grating orders. The third dimension is Er, Etheta, Ephi.
2D simulations: Data is returned in a N x 3 matrix where N is the number of grating
orders. The second dimension is Er, Etheta, Ephi.
Syntax
Description
out = gratingpolar(
"mname", f, index,
direction);

the monitor. Output is in spherical coordinates.
Parameter
Default
value
Type
Description
string

mname
required
optional
number

point.
index
optional
value at
monitor
center
number

direction
optional
direction of
max power
number

-1.
Scripting Language
235
flow
See Also
FDTD toolbox 190 , Grating calculations 232 , grating 233 , gratingn 233 , gratingperiod1
gratingbloch1 236 , gratingu1 236 , gratingangle 237 , gratingvector 235
236
10.11.80 gratingvector
order. Results are normalized such that the sum of all the orders is equal to 1. Very
similar to the basic grating function, except that the vector field information is returned in
Cartesian coordinates. This is useful when studying the polarization effects.
3D simulations: Data is returned in a N x M x3 matrix where N,M are the number of
grating orders. The third dimension is Ex, Ey, Ez.
2D simulations: Data is returned in a N x3 matrix where N is the number of grating orders.
The second dimension is Ex, Ey, Ez.
Syntax
Description
out = gratingvector(
"mname", f, index,
direction);

monitorname. Output is in Cartesian coordinates.
Parameter
Default
value
Type
Description
string

mname
required
optional
number

point.
index
optional
value at
monitor
center
number

direction
optional
direction of
max power
flow
number

-1.
See Also
FDTD toolbox 190 , Grating calculations 232 , grating 233 , gratingn 233 , gratingperiod1
gratingbloch1 236 , gratingu1 236 , gratingangle 237 , gratingpolar 234
236
236
Reference Guide
10.11.81 gratingperiod1
Returns the grating period ax based on the value from the simulation area.
Syntax
Description
out = gratingperiod1(
"monitorname", ...);
See Also
FDTD toolbox
190
, grating
233
, gratingperiod2
236
10.11.82 gratingperiod2
Returns the grating period ax based on the value from the simulation area. Only used in
3D simulations.
Syntax
Description
out = gratingperiod2(
See Also
FDTD toolbox
190
, grating
233
, gratingperiod1
236
10.11.83 gratingbloch1
Returns the value of the bloch vector (kin)x used for the calculation, based on the value for
the simulation area.
Syntax
Description
out = gratingbloch1(
See Also
FDTD toolbox
190
, grating
233
, gratingbloch2
237
10.11.84 gratingu1
Returns first component of the unit vector (ux) corresponding to the values returned by
grating.
Syntax
Description
out = gratingu1(
Scripting Language
See Also
FDTD toolbox
190
, grating
233
, gratingu2
237
237
10.11.85 gratingu2
Returns first component of the unit vector (uy) corresponding to the values returned by
grating. Only used in 3D simulations
Syntax
Description
out = gratingu2(
See Also
FDTD toolbox
190
, grating
233
, gratingu1
236
10.11.86 gratingangle
Returns the angle of each order corresponding to the values returned by grating, in
degrees. Only available for 2d simulations.
Syntax
Description
out = gratingangle(
See Also
FDTD toolbox
190
, grating
233
10.11.87 gratingbloch2
Returns the value of the bloch vector (kin)y used for the calculation, based on the value for
the simulation area. Only used in 3D simulations.
Syntax
Description
out = gratingbloch2(
See Also
FDTD toolbox
190
, grating
233
, gratingbloch1
236
238
Reference Guide
10.12Creating your own script commands

You can run any script file simply by typing the name of the file (without the .lsf
extension), as long as the file is in your current working directory or in the current path
(see getpath 113 and addpath 114 ). 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 directory
C:\Program Files\Lumerical\FDTD\scripts (Windows)
/usr/local/lumerical/scripts (Linux)
is always in the path. Therefore, you can save any script files to that directory and they
will always be in the path.
Script files must follow these formatting rules:
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 should terminate with a semicolon.
On any line, all characters after a # symbol are ignored.
The last line in the script file must have a carriage return.
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 and will return an error.
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;
script_2;
?i;
script_2.lsf
Scripting Language
for(i=1:10) {
# do something
}
239
240
Reference Guide
11
Appendix
11.1 Software acknowledgement

Lumerical Solutions, Inc. gratefully acknowledges the inclusion of software developed by
the following third-parties:
Arnoldi Package (ARPACK)
R. Lehoucq, K. Maschhoff, D. Sorensen and C. Yang
http://www.caam.rice.edu/software/ARPACK/
The users guide can be found on the Society for Industrial and Applied Mathematics
(SIAM) site: http://www.ec-securehost.com/SIAM/SE06.html
Message Passing Interface Chameleon (MPICH and MPICH2)
MPICH is a freely available, portable implementation of MPI, the Standard for
message-passing libraries.
MPICH2 is a high-performance and widely portable implementation of the Message
Passing Interface (MPI) standard (both MPI-1 and MPI-2).
W. Gropp: (630) 252-4318; FAX: (630) 252-5986; e-mail: gropp@mcs.anl.gov
E. Lusk: (630) 252-7852; FAX: (630) 252-5986; e-mail: lusk@mcs.anl.gov
Mathematics and Computer Science Division, Argonne National Laboratory, Argonne IL
60439
MPICH: http://www.mcs.anl.gov/research/projects/mpi/mpich1/
MPICH2: http://www.mcs.anl.gov/research/projects/mpich2/
Quadratic Programming Routines (Quadprog)
Release 1.4 by Berwin A Turlach. Used under the terms of the GNU Library General
Public License
Quadprog is a Fortran77 routines for solving quadratic programming problems.
For more information, please see:
http://www.maths.uwa.edu.au/~berwin/software/quadprog.html
Unsymmetric MultiFrontal Package (UMFPACK)
UMFPACK, Copyright (c) 1995-2006 by Timothy A. Davis. All Rights Reserved.
Used by permission without modification under the GNU Lesser General Public License.
UMFPACK is a set of routines for solving unsymmetric sparse linear systems, Ax=b,
using the Unsymmetric MultiFrontal method. For more information, please see:
http://www.cise.ufl.edu/research/sparse/umfpack/
Index
Index
' 138
- 132
! 136, 137
!= 134
" 137
# 139
% 126
& 135
* 132
/ 132
: 125
? 139
[] 125
^ 133
| 136
~ 137
+ 132
< 135
<= 134
= 125
== 133
> 135
>= 134
abs 144
absolute 144
access 129
acos 143
addanalysisgroup 206
addcircle 200
addcustom 200
adddipole 203
addfdtd 203
addgaussian 203
addimage 200
addimportedsource 205
addindex 205
addition 132
addmaterial 183
addmesh 203
addmode 204
addmovie 205
addpath 114
addplane 204
addpoly 201
addpower 206
addprofile 206
addpyramid 201
addrect 201
addring 201
addsphere 202
addstructuregroup 202
addsurface 202
addtfsf 204
addtime 205
addtogroup 166
adduserprop 167
almostequal 133
analysis group 58, 101
analysis tools 98
and 135
angle 144
anisotropic 77
apodization 62
arccos 143
arcsin 142
arctan 143
array 125, 129, 130
asap 49, 118, 119
asapexport 118
asapimport 119
asapload 118
asin 142
assign 129
assignment 125
atan 143
241
242
Reference Guide
atan2 143
boundary conditions 45
break 115
c 130
cd 110
clear 128
cleardcard 181
clearsourcedata 207
closeall 161
command line 122
comment 139
comparison 133
conductivity 74
conj 144
conjugate 144
copy 110, 166
copydcard 181
cos 142
cosine 142
cp 110
ctranspose 150
currentfilename 112
custom primitive 37
cwnorm 208
czt 155
data export 104
default settings 86
del 109
delete 163
deleteall 163
Dielectric 74
dipolepower 211
dir 109, 110
division 132
double quote 137
drude 74
else 157
endl 139
eps0 130
equal 125
equal to 133
equation interpreter 65
escape 115
exit 111
exp 146
exponential 146
exportfigure 160
farfield2d 222
farfield2dintegrate 224
farfield3d 225
farfield3dintegrate 228
farfieldangle 224
farfieldexact 231
farfieldexact2d 229
farfieldexact3d 230
farfieldfilter 221
farfieldpolar2d 223
farfieldpolar3d 226
farfieldspherical 227
farfieldux 227
farfielduy 227
farfieldvector2d 223
farfieldvector3d 226
fft 150
fftk 153
fftw 152
filebasename 112
filedirectory 113
fileexists 112
fileextension 113
fileopendialog 189
filesavedialog 190
find 149
findpeaks 149
for 157
format 116
gds 119
gdsii 84, 119
Index
get 169
getdata 181
getelectric 182
getfdtdindex 185
getglobal 171
getindex 185
getmagnetic 182
getmaterial 184
getnamed 170
getnamednumber 171
getnumber 170
getpath 113
getsourceangle 208
getview 178
grating 233
gratingangle 237
gratingbloch1 236
gratingbloch2 237
gratingm 234
gratingn 233
gratingperiod1 236
gratingperiod2 236
gratingpolar 234
gratingu1 236
gratingu2 237
gratingvector 235
greater than 135
greater than or equal to 134
havedata 180
if 157
imag 144
image 159
imaginary 144
import 84, 119
import object 34
importnk 174
importnk2 175
importsurface 172
importsurface2 173
integrate 148
integration 31
interp 148
interpolate 148
inverse 154
invfft 154
Kerr nonlinear 74
killwizard 188
layout 81
layoutmode 199
legend 159
length 146
less than 135
less than or equal to 134
linspace 126
ln 145
load 116, 195
loaddata 116
log 145
log10 145
loop 157
lorentz 74
ls 110
lum2mat 121, 122
mat 121
material database 72
material models 74
matlab 104, 121, 122
matlabget 123
matlabput 124
matlabsave 120
matrix 126, 130
max 147
Max coefficients 74
mesh 77
mesh refinement region 43
meshgrid3dx 127
meshgrid3dy 128
meshgrid3dz 128
243
244
Reference Guide
meshgridx 127
meshgridy 127
message 186
min 147
mod 155
mode solver 67
monitor 58
monitors 199
move 111, 166
mu0 130
multiplication 132
mv 111
natural 145
negative 132
new2d 194
new3d 195
newwizard 187
newwizardpage 187
nonorm 208
normalization 20
not 134, 136, 137
num2str 137
or 136
orbit 178
order 77
output 139
path 113, 114
pause 114
PEC 74
permeability 130
permittivity 130
phase 144
pi 130
pinch 146
plasma 74
plot 158
power 133
priorities 77
pwd 110
quit 111
rand 156
randmatrix 127
random 156
randreset 156
readdata 117
real 143
redo 179
redraw 176
redrawmode 176
redrawoff 176
redrawon 176
rm 109
round 155
run 113, 196
runanalysis 198
running a simulation 96
runparallel 197
runwizard 188
sampled data 74
save 116, 117, 196
savedata 116
savedcard 117
screen 139
script 113
seed 156
select 164
selectall 163, 164
selectfigure 160
selectpartial 164
Sellmeier 74
set 167
setglobal 168
setmaterial 184
setnamed 168
setparallel 197
setplot 160
setsourcesignal 207
setview 177
Index
shiftselect 165
shiftselectpartial 165
showdata 180
simulation 198
simulation region 43
sin 141
sine 141
single quote 138
size 146
source 49
sourceintensity 214
sourceintensity_avg 215
sourceintensity_pavg 215
sourcenorm 209
sourcenorm2_avg 209
sourcenorm2_pavg 210
sourcepower 211
sourcepower_avg 212
sourcepower_pavg 213
sources 199
spectral averaging 62
speed of light 130
spline 148
sqrt 145
square root 145
strings 137, 138
structure 34
structures 198
structures group 34
subtraction 132
sum 147
surface 41
surface object 41
switchtolayout 199
system 111
tan 142
tangent 142
Tolerance 74
toolbar 87
transmission 216
transmission_avg 217
transmission_pavg 217
transpose 150
undo 179
units 20
unselectall 164
unwrap 145
updatesourcemode 207
variables with spaces 126
which 114
wizardgetdata 188
wizardoption 189
wizardwidget 187
workspace 129
write 117
z-transform 155
245

Reference Guide: Solutions

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Reference Guide: Solutions

Încărcat de

Drepturi de autor:

Formate disponibile

FDTD Solutions

Part II The physics of the FDTD algorithm

1 FDTD and Maxwell's

Part III Units and normalization

Part IV Simulation objects

Part V Integrated mode solver

2003 - 2009 Lumerical Solutions, Inc

Part VI Material database

Part VII CAD layout editor

4 View ports ............................................................................................................ 92

Part VIII Running a simulation

Part IX Analysis tools

Part X Scripting Language

2003 - 2009 Lumerical Solutions, Inc

3 Operators ............................................................................................................ 130

4 Functions ............................................................................................................ 139

5 Loop and conditional

2003 - 2009 Lumerical Solutions, Inc

2003 - 2009 Lumerical Solutions, Inc

2003 - 2009 Lumerical Solutions, Inc

2003 - 2009 Lumerical Solutions, Inc

New features for version 6.5

1.1.1 Structure groups

1.1.2 Analysis (monitor) groups

1.1.3 Object tree browser

1.1.4 Built in script file editor

2003 - 2009 Lumerical Solutions, Inc

1.1.5 Script syntax highlighting

1.1.6 Copy and Paste

1.1.7 Dipole radiated power calculation

1.1.8 New MODE source script commands

1.1.9 New script functions

1.1.10 Online Help search bar

2003 - 2009 Lumerical Solutions, Inc

1.1.11 Simplified installation

1.1.12 Improved material fits

New features for version 6.0

1.2.1 Multi coefficient material model

1.2.2 Auto fitting of experimental data

1.2.3 Improved material database GUI

2003 - 2009 Lumerical Solutions, Inc

1.2.4 Expanded list of material data

1.2.5 Spectral averaging

1.2.6 More far field analysis

1.2.7 GUI upgrade

1.2.8 User defined source signals

2003 - 2009 Lumerical Solutions, Inc

for more information.

1.2.9 Shorter source pulses

1.2.10 Unicode characters

New features for version 5.1

1.3.1 GDSII import

1.3.2 Improved figure windows

1.3.3 n and k import

1.3.4 Set view and orbit

2003 - 2009 Lumerical Solutions, Inc

1.3.5 Surface imports

1.3.6 Windows Vista support

New features for version 5.0

1.4.1 Graded mesh

1.4.2 Polygon and triangle primitives

1.4.3 Quadrics and Infinipath interconnects

1.4.4 Native support for the Windows x64 platform