Startup Code Lecture L5.2. Reference MC9S12C Family Device User Guide V01.05 9S12C128DGV1.pdf.
DEVICE Reference Guide
-
Upload
sreevatsakurudi -
Category
Documents
-
view
182 -
download
11
description
Transcript of DEVICE Reference Guide
Reference Guide
DEVICE
Release 3.1
1Contents
© 2003 - 2013 Lumerical Solutions, Inc
Table of ContentsPart I New Features 11
............................................................................................................ 111 New features for version 1.5
............................................................................................................ 122 New features for version 2.0
............................................................................................................ 133 New features for version 3.1
Part II Solver physics 15
............................................................................................................ 151 FDTD
................................................................................................................................................. 16FDTD and Maxwell's equations
................................................................................................................................................. 18Meshing in FDTD
............................................................................................................ 192 Eigenmode Solver
................................................................................................................................................. 20Meshing in the Eigenmode solver
............................................................................................................ 213 Propagator
................................................................................................................................................. 212.5D FDTD
................................................................................................................................................. 23Eigenmode expansion
................................................................................................................................................. 23Meshing in the propagator
............................................................................................................ 244 INTERCONNECT
................................................................................................................................................. 24Time Domain Simulator
................................................................................................................................................. 25Frequency Domain Simulator
............................................................................................................ 255 DEVICE
................................................................................................................................................. 25System of Equations
................................................................................................................................................. 28Meshing in DEVICE
Part III CAD layout editor 29
............................................................................................................ 291 Main title bar
............................................................................................................ 302 Toolbars
................................................................................................................................................. 30Main
................................................................................................................................................. 31Edit
................................................................................................................................................. 33Mouse mode
................................................................................................................................................. 34View
................................................................................................................................................. 35Simulation
................................................................................................................................................. 36Search bar
............................................................................................................ 363 View ports
............................................................................................................ 374 Object Tree
................................................................................................................................................. 37Enable/Disable Simulation Object
............................................................................................................ 385 Results View
............................................................................................................ 386 Optimization and Sweeps
............................................................................................................ 387 Script Prompt and Script Editor
............................................................................................................ 398 Script Workspace and Script Favorites
............................................................................................................ 399 Changing the CAD layout
Part IV Material database 42
Reference Guide2
© 2003 - 2013 Lumerical Solutions, Inc
............................................................................................................ 421 Material database
............................................................................................................ 432 Electrical models
................................................................................................................................................. 44Conductors
................................................................................................................................................. 44Insulators
................................................................................................................................................. 44Semiconductors
............................................................................................................ 543 Mesh order
Part V Simulation objects 56
............................................................................................................ 581 Structures
................................................................................................................................................. 58Primitives
................................................................................................................................................. 59Geometry tab
................................................................................................................................................. 59Material tab
................................................................................................................................................. 60Rotations tab
................................................................................................................................................. 60Graphical Rendering tab
................................................................................................................................................. 60Import Data tab
................................................................................................................................................. 65Properties tab
................................................................................................................................................. 65Script tab
............................................................................................................ 652 Simulation
................................................................................................................................................. 66General tab
................................................................................................................................................. 67Mesh tab
................................................................................................................................................. 67Geometry tab
................................................................................................................................................. 67Transient tab
................................................................................................................................................. 68Results
................................................................................................................................................. 68Advanced options tab
................................................................................................................................................. 69Solver type
................................................................................................................................................. 70Fermi statistics
............................................................................................................ 703 Monitors
................................................................................................................................................. 71General tab
................................................................................................................................................. 72Geometry tab
............................................................................................................ 724 Generation
............................................................................................................ 725 Doping
............................................................................................................ 746 Contacts
............................................................................................................ 767 Equation interpreter
Part VI Running simulations and analysis 77
............................................................................................................ 771 Resource Manager
................................................................................................................................................. 79Resources Advanced Options
............................................................................................................ 802 Running a simulation
............................................................................................................ 813 Analysis tools
................................................................................................................................................. 82Analysis tools and the simulation environment
................................................................................................................................................. 82Figure w indows for plots and images
................................................................................................................................................. 83Data export
................................................................................................................................................. 83Visualizer
................................................................................................................................................. 93Results Manager
............................................................................................................ 974 Optimization and parameter sweeps
3Contents
© 2003 - 2013 Lumerical Solutions, Inc
................................................................................................................................................. 99Optimization
................................................................................................................................................. 101Particle Swarm Optimization
................................................................................................................................................. 103Parameter Sweeps
................................................................................................................................................. 104Nested Sweeps
................................................................................................................................................. 105Yield Analysis
Part VII Scripting Language 108
............................................................................................................ 1091 System
................................................................................................................................................. 112newproject
................................................................................................................................................. 112newmode
................................................................................................................................................. 113save
................................................................................................................................................. 113load
................................................................................................................................................. 113del
................................................................................................................................................. 114rm
................................................................................................................................................. 114dir
................................................................................................................................................. 114ls
................................................................................................................................................. 115cd
................................................................................................................................................. 115pwd
................................................................................................................................................. 115cp
................................................................................................................................................. 116mv
................................................................................................................................................. 116exit
................................................................................................................................................. 116system
................................................................................................................................................. 117fileexists
................................................................................................................................................. 117currentfilename
................................................................................................................................................. 117filebasename
................................................................................................................................................. 118fileextension
................................................................................................................................................. 118filedirectory
................................................................................................................................................. 118getcommands
................................................................................................................................................. 118Run script
................................................................................................................................................. 119getpath
................................................................................................................................................. 119addpath
................................................................................................................................................. 119which
................................................................................................................................................. 120pause
................................................................................................................................................. 120break
................................................................................................................................................. 120Excape key
................................................................................................................................................. 121format
................................................................................................................................................. 121loaddata
................................................................................................................................................. 121savedata
................................................................................................................................................. 122savedcard
................................................................................................................................................. 122readdata
................................................................................................................................................. 123write
................................................................................................................................................. 123asapexport
................................................................................................................................................. 124asapload
................................................................................................................................................. 124asapimport
................................................................................................................................................. 124matlabsave
................................................................................................................................................. 125matlabsavelegacy
................................................................................................................................................. 125matlabload
................................................................................................................................................. 125matlab
................................................................................................................................................. 127matlabget
................................................................................................................................................. 127matlabput
Reference Guide4
© 2003 - 2013 Lumerical Solutions, Inc
................................................................................................................................................. 127copytoclipboard
................................................................................................................................................. 128pastefromclipboard
................................................................................................................................................. 128debug
................................................................................................................................................. 128vtksave
................................................................................................................................................. 129lookupread
................................................................................................................................................. 129lookupopen
................................................................................................................................................. 129lookupclose
................................................................................................................................................. 130lookupwrite
............................................................................................................ 1302 Manipulating variables
................................................................................................................................................. 132=
................................................................................................................................................. 132:
................................................................................................................................................. 132[]
................................................................................................................................................. 133%
................................................................................................................................................. 133linspace
................................................................................................................................................. 133matrix
................................................................................................................................................. 133randmatrix
................................................................................................................................................. 134randnmatrix
................................................................................................................................................. 134histogram
................................................................................................................................................. 134meshgridx
................................................................................................................................................. 135meshgridy
................................................................................................................................................. 135meshgrid3dx
................................................................................................................................................. 135meshgrid3dy
................................................................................................................................................. 136meshgrid3dz
................................................................................................................................................. 136meshgrid4d
................................................................................................................................................. 136clear
................................................................................................................................................. 136workspace
................................................................................................................................................. 137Accessing and assigning matrix elements
................................................................................................................................................. 138Matrix operators
................................................................................................................................................. 138Pre-defined constants
................................................................................................................................................. 139matrixdataset
................................................................................................................................................. 139rectilineardataset
................................................................................................................................................. 140addparameter
................................................................................................................................................. 140addattribute
................................................................................................................................................. 140getparameter
................................................................................................................................................. 141getattribute
................................................................................................................................................. 141eye
................................................................................................................................................. 141Datasets
................................................................................................................................................. 146struct
................................................................................................................................................. 147cell
................................................................................................................................................. 147unstructureddataset
............................................................................................................ 1483 Operators
................................................................................................................................................. 149.
................................................................................................................................................. 150*
................................................................................................................................................. 150/
................................................................................................................................................. 150+
................................................................................................................................................. 150-
................................................................................................................................................. 151^
................................................................................................................................................. 151==
................................................................................................................................................. 151almostequal
................................................................................................................................................. 152!=
5Contents
© 2003 - 2013 Lumerical Solutions, Inc
................................................................................................................................................. 152<=
................................................................................................................................................. 152>=
................................................................................................................................................. 153<
................................................................................................................................................. 153>
................................................................................................................................................. 153&
................................................................................................................................................. 153and
................................................................................................................................................. 154|
................................................................................................................................................. 154or
................................................................................................................................................. 154!
................................................................................................................................................. 155~
................................................................................................................................................. 155"
................................................................................................................................................. 156'
................................................................................................................................................. 157endl
................................................................................................................................................. 157?
................................................................................................................................................. 157comments
............................................................................................................ 1574 Functions
................................................................................................................................................. 162sin
................................................................................................................................................. 162cos
................................................................................................................................................. 162tan
................................................................................................................................................. 162asin
................................................................................................................................................. 163acos
................................................................................................................................................. 163atan
................................................................................................................................................. 163atan2
................................................................................................................................................. 164real
................................................................................................................................................. 164imag
................................................................................................................................................. 164conj
................................................................................................................................................. 164abs
................................................................................................................................................. 165angle
................................................................................................................................................. 165unwrap
................................................................................................................................................. 165log
................................................................................................................................................. 165log10
................................................................................................................................................. 166sqrt
................................................................................................................................................. 166exp
................................................................................................................................................. 166size
................................................................................................................................................. 166length
................................................................................................................................................. 167pinch
................................................................................................................................................. 167sum
................................................................................................................................................. 168max
................................................................................................................................................. 168min
................................................................................................................................................. 168dot
................................................................................................................................................. 168cross
................................................................................................................................................. 169eig
................................................................................................................................................. 169mult
................................................................................................................................................. 170flip
................................................................................................................................................. 170permute
................................................................................................................................................. 170reshape
................................................................................................................................................. 171inv
................................................................................................................................................. 171interp
................................................................................................................................................. 172interptri
................................................................................................................................................. 172spline
Reference Guide6
© 2003 - 2013 Lumerical Solutions, Inc
................................................................................................................................................. 173integrate
................................................................................................................................................. 173integrate2
................................................................................................................................................. 174find
................................................................................................................................................. 174findpeaks
................................................................................................................................................. 175transpose
................................................................................................................................................. 175ctranspose
................................................................................................................................................. 175num2str
................................................................................................................................................. 176str2num
................................................................................................................................................. 176eval
................................................................................................................................................. 176feval
................................................................................................................................................. 176substring
................................................................................................................................................. 177findstring
................................................................................................................................................. 177replace
................................................................................................................................................. 178replacestring
................................................................................................................................................. 178splitstring
................................................................................................................................................. 178fft
................................................................................................................................................. 180fftw
................................................................................................................................................. 181fftk
................................................................................................................................................. 182invfft
................................................................................................................................................. 183czt
................................................................................................................................................. 183polyarea
................................................................................................................................................. 184centroid
................................................................................................................................................. 184polyintersect
................................................................................................................................................. 185inpoly
................................................................................................................................................. 185polygrow
................................................................................................................................................. 186polyand
................................................................................................................................................. 186polyor
................................................................................................................................................. 186polydiff
................................................................................................................................................. 187polyxor
................................................................................................................................................. 187lineintersect
................................................................................................................................................. 188linecross
................................................................................................................................................. 188ceil
................................................................................................................................................. 188floor
................................................................................................................................................. 189mod
................................................................................................................................................. 189sign
................................................................................................................................................. 189round
................................................................................................................................................. 190rand
................................................................................................................................................. 190lognrnd
................................................................................................................................................. 190randn
................................................................................................................................................. 191randreset
................................................................................................................................................. 191finite
................................................................................................................................................. 191solar
................................................................................................................................................. 192stackrt
................................................................................................................................................. 192mean
................................................................................................................................................. 192all
................................................................................................................................................. 193any
................................................................................................................................................. 193var
................................................................................................................................................. 194std
................................................................................................................................................. 194mapfind
................................................................................................................................................. 195quadtri
................................................................................................................................................. 195expand
7Contents
© 2003 - 2013 Lumerical Solutions, Inc
................................................................................................................................................. 196norm
............................................................................................................ 1965 Loop and conditional statements
................................................................................................................................................. 196for
................................................................................................................................................. 197if
............................................................................................................ 1976 Plotting commands
................................................................................................................................................. 198plot
................................................................................................................................................. 199plotxy
................................................................................................................................................. 200polar
................................................................................................................................................. 200polar2
................................................................................................................................................. 201polarimage
................................................................................................................................................. 202histc
................................................................................................................................................. 202legend
................................................................................................................................................. 202image
................................................................................................................................................. 203visualize
................................................................................................................................................. 204selectfigure
................................................................................................................................................. 204setplot
................................................................................................................................................. 204exportfigure
................................................................................................................................................. 205closeall
................................................................................................................................................. 205vectorplot
............................................................................................................ 2057 Adding Objects
................................................................................................................................................. 208switchtolayout
................................................................................................................................................. 209layoutmode
................................................................................................................................................. 209addgroup
................................................................................................................................................. 209addstructuregroup
................................................................................................................................................. 210addanalysisgroup
................................................................................................................................................. 210addobject
................................................................................................................................................. 210addcontact
................................................................................................................................................. 211addcircle
................................................................................................................................................. 211addcustom
................................................................................................................................................. 211addimport
................................................................................................................................................. 212addpyramid
................................................................................................................................................. 212addpoly
................................................................................................................................................. 212addrect
................................................................................................................................................. 213addtriangle
................................................................................................................................................. 213addring
................................................................................................................................................. 213addsphere
................................................................................................................................................. 214addsurface
................................................................................................................................................. 214addfdtd
................................................................................................................................................. 214addeigenmode
................................................................................................................................................. 214addpropagator
................................................................................................................................................. 215addmesh
................................................................................................................................................. 215addmode
................................................................................................................................................. 215addmodesource
................................................................................................................................................. 215adddipole
................................................................................................................................................. 216addgaussian
................................................................................................................................................. 216addplane
................................................................................................................................................. 216addtfsf
................................................................................................................................................. 217addimportedsource
................................................................................................................................................. 217addindex
................................................................................................................................................. 217addtime
Reference Guide8
© 2003 - 2013 Lumerical Solutions, Inc
................................................................................................................................................. 218addmovie
................................................................................................................................................. 218addprofile
................................................................................................................................................. 218createbeam
................................................................................................................................................. 219adddevice
................................................................................................................................................. 219adddope
................................................................................................................................................. 219adddiffusion
................................................................................................................................................. 219addimportdope
................................................................................................................................................. 220addbulkgen
................................................................................................................................................. 220addimportgen
................................................................................................................................................. 220addgridattribute
................................................................................................................................................. 221addelement
................................................................................................................................................. 222addmodeexpansion
................................................................................................................................................. 222addeffectiveindex
................................................................................................................................................. 222addchargemonitor
................................................................................................................................................. 223addfieldmonitor
............................................................................................................ 2238 Manipulating objects
................................................................................................................................................. 226groupscope
................................................................................................................................................. 226deleteall
................................................................................................................................................. 227delete
................................................................................................................................................. 227selectall
................................................................................................................................................. 227unselectall
................................................................................................................................................. 227select
................................................................................................................................................. 228selectpartial
................................................................................................................................................. 228shiftselect
................................................................................................................................................. 229shiftselectpartial
................................................................................................................................................. 229flipelement
................................................................................................................................................. 229rotateelement
................................................................................................................................................. 229move
................................................................................................................................................. 230copy
................................................................................................................................................. 230addtogroup
................................................................................................................................................. 231adduserprop
................................................................................................................................................. 231set
................................................................................................................................................. 232setnamed
................................................................................................................................................. 232setglobalmonitor
................................................................................................................................................. 233setglobalsource
................................................................................................................................................. 233setmodes
................................................................................................................................................. 233setposition
................................................................................................................................................. 234setrectangle
................................................................................................................................................. 234getposition
................................................................................................................................................. 234getrectangle
................................................................................................................................................. 235get
................................................................................................................................................. 235runsetup
................................................................................................................................................. 236getnumber
................................................................................................................................................. 236getnamed
................................................................................................................................................. 237getnamednumber
................................................................................................................................................. 237getglobalmonitor
................................................................................................................................................. 237getglobalsource
................................................................................................................................................. 238getsolver
................................................................................................................................................. 238haveproperty
................................................................................................................................................. 238importsurface
9Contents
© 2003 - 2013 Lumerical Solutions, Inc
................................................................................................................................................. 240importsurface2
................................................................................................................................................. 241importnk
................................................................................................................................................. 243importnk2
................................................................................................................................................. 245importnkobfuscated
................................................................................................................................................. 246importbinary
................................................................................................................................................. 248importbinary2
................................................................................................................................................. 250importbinaryobfuscated
................................................................................................................................................. 251updatesourcemode
................................................................................................................................................. 252setsourcesignal
................................................................................................................................................. 253updatemodes
................................................................................................................................................. 254clearsourcedata
................................................................................................................................................. 254clearmodedata
................................................................................................................................................. 255seteigensolver
................................................................................................................................................. 256geteigensolver
................................................................................................................................................. 256redraw
................................................................................................................................................. 257redrawoff
................................................................................................................................................. 257redrawon
................................................................................................................................................. 257redrawmode
................................................................................................................................................. 258setview
................................................................................................................................................. 259getview
................................................................................................................................................. 259orbit
................................................................................................................................................. 260framerate
................................................................................................................................................. 260undo
................................................................................................................................................. 260redo
................................................................................................................................................. 261addport
................................................................................................................................................. 261removeport
................................................................................................................................................. 262connect
................................................................................................................................................. 262disconnect
................................................................................................................................................. 262setexpansion
................................................................................................................................................. 263removeexpansion
................................................................................................................................................. 263setactivesolver
................................................................................................................................................. 263getname
................................................................................................................................................. 263setname
................................................................................................................................................. 264importdataset
................................................................................................................................................. 264cleardataset
............................................................................................................ 2659 Running simulations
................................................................................................................................................. 265runparallel
................................................................................................................................................. 266addjob
................................................................................................................................................. 266runjobs
................................................................................................................................................. 266clearjobs
................................................................................................................................................. 267runsweep
............................................................................................................ 26710 Measurement and optimization data
................................................................................................................................................. 268getsweepdata
................................................................................................................................................. 269getsweepresult
................................................................................................................................................. 269getdata
................................................................................................................................................. 270getresult
................................................................................................................................................. 270runanalysis
................................................................................................................................................. 271havedata
................................................................................................................................................. 271haveresult
................................................................................................................................................. 272havesweepdata
Reference Guide10
© 2003 - 2013 Lumerical Solutions, Inc
................................................................................................................................................. 272havesweepresult
................................................................................................................................................. 273copydcard
................................................................................................................................................. 273clearanalysis
................................................................................................................................................. 274cleardcard
................................................................................................................................................. 274getelectric
................................................................................................................................................. 274getmagnetic
................................................................................................................................................. 275Read and write data to files
................................................................................................................................................. 275loadsweep
................................................................................................................................................. 275savesweep
............................................................................................................ 27611 Material database
................................................................................................................................................. 276addmaterial
................................................................................................................................................. 277copymaterial
................................................................................................................................................. 277setmaterial
................................................................................................................................................. 277getmaterial
................................................................................................................................................. 278getindex
................................................................................................................................................. 278getfdtdindex
................................................................................................................................................. 279getmodeindex
................................................................................................................................................. 280getnumericalpermittivity
............................................................................................................ 28112 GDSII
................................................................................................................................................. 282gdsopen
................................................................................................................................................. 282gdsclose
................................................................................................................................................. 283gdsbegincell
................................................................................................................................................. 283gdsendcell
................................................................................................................................................. 284gdsaddpoly
................................................................................................................................................. 284gdsaddcircle
................................................................................................................................................. 285gdsaddrect
................................................................................................................................................. 286gdsaddref
................................................................................................................................................. 286gdsimport
............................................................................................................ 28813 User defined GUIs
................................................................................................................................................. 288message
................................................................................................................................................. 289newwizard
................................................................................................................................................. 289newwizardpage
................................................................................................................................................. 289wizardwidget
................................................................................................................................................. 290wizarddata
................................................................................................................................................. 291runwizard
................................................................................................................................................. 291wizardgetdata
................................................................................................................................................. 291killw izard
................................................................................................................................................. 292wizardoption
................................................................................................................................................. 292fileopendialog
................................................................................................................................................. 292filesavedialog
............................................................................................................ 29314 Creating your own script commands
Index 295
New Features 11
© 2003 - 2013 Lumerical Solutions, Inc
1 New Features
DEVICE is constantly being upgraded. See the following sections for a list of the latestnew features.
New features for version 1.5New features for version 2.0New features for version 3.1
1.1 New features for version 1.5New solver option
In the initial versions of the software, the Gummel’s method was used in the solver, inwhich the voltage and charge were solved sequentially (one was used as a input to theother) until the two were consistent. In DEVICE 1.5, the Newton solver has beenintroduced, which solves for the charge and voltage simultaneously. The Newton solver ismore sensitive to the initial conditions (it may not converge), but will converge much fasterfor a wider variety of problems if it’s given a good initial guess.
Advanced contact models
Several modificationshave been made to thecontact models forDEVICE:
Lumped elementloads (R and C) cannow be added ondevice terminals. Customspecification of DCsweep bias voltagesis available. Non-ohmic contactswill use a Schottkybarrier modelaccounting forbarrier lowering dueto the appliedelectric field.
11
12
13
Reference Guide12
© 2003 - 2013 Lumerical Solutions, Inc
Adaptive transient simulation
Transient simulations now employ adaptive time-stepping to optimally vary the simulationinterval while maintaining accuracy. Coupled with the full Newton solver, a wider variety oftransient simulations can now be performed efficiently with DEVICE. To view the newsettings associated with the transient simulation, consult the "Transient" tab in the Deviceregion properties. Here, the user may specify time step constraints, down-sampling, andshuttering for optical generation objects.
Results selection
In the Device region properties, users now how the option to retain a reduced set of spatialdata. Under the "Results" tab, a list of all available results can be viewed, and may betoggled on or off to reduce memory requirements. By default all results are included.
1.2 New features for version 2.0Results manager and VisualizerThe Results Manager is a tool for analyzing simulation data. This includes a ResultsView window which displays all the results for the simulation object that is currentlyselected in the Object Tree. The Results Manager also includes a Script Workspace and aScript Favorites window, providing additional GUI-based functionalities.
Also featured in DEVICE 2.0 is the more improved Visualizer , which significantlysimplifies the process of visualizing simulation data. When used in conjunction, ResultsManager and the Visualizer provide a very useful and intuitive way of analyzing andvisualizing variables and results through the GUI, greatly reducing the need for scripting.
DatasetsLumerical datasets are structured data objects that collect a set of related matrices into asingle convenient object. See Dataset introduction for more information.
Yield analysis toolA new yield analysis tool is available in the Optimization and Sweeps window. The yieldanalysis tool gives users the ability to run extensive Monte Carlo analysis, sweeping
93
83
141
New Features 13
© 2003 - 2013 Lumerical Solutions, Inc
across multiple parameters to assess statistical variations of circuit elements on overallcircuit performance.
Please see the Yield analysis page in the Reference Guide for more details, and theRunning a yield analysis task example in the User Guide.
Other new script commandsThe following script functions were added in DEVICE 2.0. For more information, see thefunction descriptions in the scripting section of the Reference Guide.. operator , addattribute , addparameter , eig , debug ,getattribute , getparameter , getresult , getsweepresult ,integrate2 , matrixdataset , addmodeexpansion , mult ,permute rectilineardataset , reshape
1.3 New features for version 3.1 3D solver
DEVICE is now capable of simulating fully three dimensional geometries. The solver typecan be chosen by the user to be 2D or 3D. This means that arbitrary structures particularlywhere slicing or averaging of imported 3D data is not valid can now be solved for in 3dimensions.
Visualization
The visualizer has been updated for 3D simulations to allow the user to better view theresults, enabling image plots, arbitrary slices of the 3D geometry or line plots of varioustypes of data.
Field and charge monitors
A new object type, monitor, has been added to DEVICE. 2D/3D monitors can be placedanywhere within the simulation region to record the total charge within the monitor and/orelectric field through the monitor boundaries.
Continue from previous solution
It is now possible to specify a project file that has already been run as a reference projectfor solving another simulation. The initialization step in the solver can be skipped with thisfeature, using the converged solution of the specified file. This will save a lot of time inmemory intensive simulations.
105
149 140 140 169 128
141 140 270 269
173 139 222 169
170 139 170
Reference Guide14
© 2003 - 2013 Lumerical Solutions, Inc
Electron-hole density grid attributeFDTD Solutions 8.7 and MODE Solutions 6.6 (and beyond) can import electron-holedensity data recorded on a finite-element mesh directly from a DEVICE simulation. Thisapproach, which offers significant improvement over the previous (n, k) import option,reduces simulation memory requirements and interpolation errors.
XML lookup table supportAs of version 3.0, users can simulate a wide range of device designs with Lumerical'sTCAD tools, the results of which get incorporated into an XML lookup table. This XMLlookup table can then be associated with a specific element as the basis for a validatedcompact model within an INTERCONNECT project. Please see Parameter Extraction andPDKs for detailed examples.
Export viewports to imageAs of version 3.1, users can export CAD viewports into JPEG figures by selecting "View ->Export view" from the main title bar.
new script commandsThe following script functions were added in DEVICE 3.0. For more information, see thefunction descriptions in the scripting section of the Reference Guide. all, any, quadtri, unstructuredataset, loadsweep, savesweep,var, std
Solver physics 15
© 2003 - 2013 Lumerical Solutions, Inc
2 Solver physics
This chapter describes the basic physics and algorithms used in Lumerical's various'Physics' based solvers:
FDTD SolutionsThe Finite-Difference Time-Domain method, which is the method behind both FDTDSolutions and MODE Solutions' Propagator.
MODE Solutions Eigenmode SolverThe method behind MODE Solutions' Eigenmode Solver and FDTD Solutions' IntegratedMODE Solver.
MODE Solutions PropagatorThe method behind MODE Solutions' omnidirectional propagator for planar integratedsystems.
INTERCONNECTThe method behind Lumerical's INTERCONNECT circuit simulator.
DEVICEThe method behind Lumerical's DEVICE electronic device simulator.
2.1 FDTDThe finite-difference time-domain (FDTD) method1,2,3 is a state-of-the-art method for solvingMaxwell's equations in complex geometries. Being a direct time and space solution, itoffers the user a unique insight into all types of problems in electromagnetics andphotonics. In addition, FDTD can also obtain the frequency solution by exploiting Fouriertransforms, thus a full range of useful quantities can be calculated, such as the complexPoynting vector and the transmission / reflection of light.
This section will introduce the basic mathematical and physics formalism behind the FDTDalgorithm used in FDTD Solutions and MODE Solutions' propagator, starting from the linearMaxwell's equations. The simulator can be used for advanced research and development oras an ideal teaching and learning environment in photonics, optics, and electromagnetics.
See the FDTD Numerical methods video for additional information: http://www.lumerical.com/support/courses/fdtd_numerical_methods/video.html
15
19
21
24
25
Reference Guide16
© 2003 - 2013 Lumerical Solutions, Inc
1 Dennis M. Sullivan, Electromagnetic simulation using the FDTD method. New York: IEEEPress Series, (2000).2 Allen Taflove, Computational Electromagnetics: The Finite-Difference Time-DomainMethod. Boston: Artech House, (2005).3 Stephen D. Gedney, Introduction to the Finite-Difference Time-Domain (FDTD) Method forElectromagnetics. Morgan & Claypool publishers, (2011).
2.1.1 FDTD and Maxwell's equations
FDTD solves Maxwell's curl equations in non-magnetic materials:
Ht
D
)()()( 0 ED r
Et
H
0
1
where H, E, and D are the magnetic, electric, and displacement fields, respectively, while
)(r is the complex relative dielectric constant (
2)( nr, where n is the refractive
index).
In three dimensions, Maxwell equations have six electromagnetic field components: Ex, E
y,
Solver physics 17
© 2003 - 2013 Lumerical Solutions, Inc
Ez and H
x, H
y, and H
z. If we assume that the structure is infinite in the z dimension and
that the fields are independent of z, specifically that
),,(),,,( yxzyx rr
0z
H
z
E
then Maxwell's equations split into two independent sets of equations composed of threevector 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 ofequations with the following components:TE: E
x, E
y, H
z
TM: Hx, H
y, E
z
For example, in the TM case, Maxwell's equations reduce to:
y
H
x
H
t
D xyz
)()()( 0 zrz ED
y
E
t
H zx
0
1
x
E
t
Hzy
0
1
FDTD Solutions can solve the two and three dimensional Maxwell's equations in dispersivemedia and some simple non-linear media, where the user can specify arbitrary geometricstructures and various input excitation sources. The two dimensional FDTD simulatorsolves the TE and/or TM Maxwell equations.
FDTD is a time domain technique, meaning that the electromagnetic fields are solved as afunction of time. In general, FDTD Solutions is used to calculate the electromagnetic fieldsas a function of frequency or wavelength by performing Fourier transforms during thesimulation. This allows it to obtain complex-valued fields and other derived quantities suchas the complex Poynting vector, normalized transmission, and far field projections as afunction of frequency or wavelength. The field information can be returned in two differentnormalization states, please see the section on frequency domain normalization for moredetails.
Reference Guide18
© 2003 - 2013 Lumerical Solutions, Inc
Dispersive materials with tabulated refractive index (n,k) data as a function of wavelengthcan be solved using the multi-coefficient models with auto-fitting. Alternatively, specifictheoretical models such as Plasma (Drude), Debye or Lorentz can be used. See thechapter on the Material Database for details.
Boundary conditions are very important in electromagnetics and simulation techniques. FDTD Solutions/propagator supports a range of boundary conditions, such as PML,periodic, and Bloch. See the boundary conditions section here for the complete list.
Sources are another important component of a simulation. FDTD Solutions/propagatorsupports 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 opticalcomponents, and an imported source to interface with external photonic design softwares. Detailed information about each of these sources is contained in the Radiation sourcessection.
Unless otherwise specified, all quantities in FDTD Solutions/propagator are calculated in SIunits. Please see Units and Normalization for more information.
The online User Guide at http://docs.lumerical.com/en/fdtd/knowledge_base.html has manymore details about the physics of FDTD and how to obtain advanced results. Please see,for example, the sections on coherence, and far field calculations in the online User Guide.
2.1.2 Meshing in FDTD
FDTD Solutions uses a rectangular, Cartesian style mesh, like the one shown in thefollowing screenshot. It's important to understand that of the fundamental simulationquantities (material properties and geometrical information, electric and magnetic fields) arecalculated at each mesh point. Obviously, using a smaller mesh allows for a moreaccurate representation of the device, but at a substantial cost. As the mesh becomessmaller, the simulation time and memory requirements will increase. FDTD Solutionsprovides a number of features, including the conformal mesh algorithm, that allow you toobtain accurate results, even when using a relatively coarse mesh.
By default, the simulation mesh is automatically generated.To maintain accuracy, the meshing algorithm will create asmaller mesh in high index (to maintain a constant numberof mesh points per wavelength) and highly absorbing(resolve penetration depths) materials. In some cases, it isalso necessary to manually add additional meshingconstraints. Usually, this involves forcing the mesh to besmaller near complex structures (often metal) where thefields are changing very rapidly.
42
Solver physics 19
© 2003 - 2013 Lumerical Solutions, Inc
2.2 Eigenmode SolverThe Eigenmode Solver (Eigensolver) solves for optical modes in a cross-section of anarbitrary waveguide geometry. The waveguide mode as a transverse field distribution thatpropagates along the waveguide without changing shape.
In the z-normal eigenmode solver simulation example shown in the figure above, we havethe vector fields:
)(),( ztieyxE and
)(),( ztieyxH
where ω is the angular frequency and β is the propagation constant. The modal effective
index is then defined as
cneff
.
MODE Solutions find these modes by solving Maxwell's equations on a cross-sectionalmesh of the waveguide. The finite difference algorithm is the current method used formeshing the waveguide geometry, and has the ability to accommodate arbitrary waveguidestructure. Once the structure is meshed, Maxwell's equations are then formulated into amatrix eigenvalue problem and solved using sparse matrix techniques to obtain the effective
index and mode profiles of the waveguide modes. This method is based on Zhu and Brown1
, with proprietary modifications and extensions.
Reference Guide20
© 2003 - 2013 Lumerical Solutions, Inc
Z. Zhu and T. G. Brown, “Full-vectorial finite-difference analysis of microstructured opticalfibers,” Opt. Express 10, 853–864 (2002), http://www.opticsexpress.org/abstract.cfm?URI=OPEX-10-17-853
2.2.1 Meshing in the Eigenmode solver
The MODE Solutions Eigenmode Solver uses a rectangular, Cartesian style mesh, like theone shown in the following screenshot. It's important to understand that of the fundamentalsimulation quantities (material properties and geometrical information, electric andmagnetic fields) are calculated at each mesh point. Obviously, using a smaller meshallows for a more accurate representation of the device, but at a substantial cost. As themesh becomes smaller, the simulation time and memory requirements will increase. MODE Solutions provides a number of features, including the conformal mesh algorithm,that allow you to obtain accurate results, even when using a relatively coarse mesh.
By default, the simulation will use a uniform mesh. You simply set the number of mesh points alongeach axis. In some cases, it is necessary to addadditional meshing constraints. Usually, this involvesforcing the mesh to be smaller near complexstructures where the fields are changing very rapidly.
Note: In FDTD-based simulations, it's important touse a smaller mesh in high index materials, and tomaintain a minimum number of mesh points perwavelength. This constraint does not exist for theEigenmode solver.
Solver physics 21
© 2003 - 2013 Lumerical Solutions, Inc
2.3 PropagatorMODE Solutions currently supports 2 methods of propagating fields.
1) The 2.5D FDTD propagator. This propagator accurately describes the propagation oflight in planar integrated optical systems, from ridge waveguide-based systems to morecomplex geometries such as photonic crystals. The propagator allows for planar (omni-directional) propagation without any assumptions about an optical axis, which allows forstructures like ring resonators and photonic crystal cavities to be efficiently modeled –devices that have been traditionally treated with 3D FDTD. The propagator can modeldevices on the scale of hundreds of microns quickly.
2) The eigenmode expansion propagator. This script based, unidirectional eigenmodeexpansion propagator allows you to decompose one input or waveguide mode onto themodes of another waveguide section and propagate the modes an arbitrary distance. It isuseful for waveguide couplers, long tapers and other devices where the propagation can beassumed to be essentially unidirectional.
2.3.1 2.5D FDTD
The FDTD propagator is based on collapsing a 3D geometry into a 2D set of effectiveindices that can be solved with 2D FDTD . This works best with waveguides made fromplanar structures. For additional information on the 2.5D Propagator, see the Lumerical’s2.5D FDTD Propagation Method whitepaper on our website.
The main assumption of this method is that there is little coupling between differentsupported slab modes. For many devices, such as SOI based slab waveguide structures,that only support 2 vertical modes with different polarizations, this is an excellentassumption.
The calculation steps involve:1. Identification of the vertical slab modes of the core waveguide structure, over a desired
range of wavelengths. 2. Meshing of the structure and collapse of the 3rd dimension by calculation of the
corresponding effective 2D indices (taking into account the vertical slab mode profile).There are currently two approaches to doing this in the Propagator:
VariationalA variational procedure based on Hammer and Ivanova1. Here, the effective permittivities ofthe TE and TM-like modes have the form:
21
23
15
Reference Guide22
© 2003 - 2013 Lumerical Solutions, Inc
z
z
r
rTEeff
dzzM
dzzMzzyx
kyx
2
2
2
),(
),(),(),,(
),,(
z
z r
z
z rrTMeff
dzMzyx
k
dzz
M
zyx
dzMzyx
dzM
kyx
22
2
2
22
),,(
1
),,(
11
||),,(
1
||1
),,(
where εr, M and βr are the 1-D reference permittivity profile, the associated guided slabmode and the propagation constant.
Reciprocity BasedThis is a procedure based on the reciprocity theorem, as described in Snyder and Love2:
z
z
r
reff
dznP
dzzEzzyx
kyxn
2
2
1
0
0
),(),(),,(
),,(
Note that in both cases, the generated effective materials are also dispersive, where thedispersion comes both from the original material properties (material dispersion) and theslab waveguide geometry (waveguide dispersion). These new materials are then fitted usingLumerical Solutions' multi-coefficient model into a time-domain form that can be used in the2D FDTD simulation in step 3. Note that the effective index treatment may lead togenerated materials that have properties that are unphysical (for example, having anartificial negative imaginary index). In this case, one has the option of restricting the rangeof generated indices to the min/max values defined by the physical material properties ofthe original materials. All of these settings can be found under the Effective index tab of thePropagator simulation region.
3. Simulation of the structure in 2D by FDTD .4. If desired, re-expansion of the fields into 3D.
The Ring resonator getting started example contains step-by-step instructions anddiscussions on how to carry out a propagator simulation using the variational FDTDmethod.
1 Manfred Hammer and Olena V. Ivanova, MESA Institute for Nanotechnology, University ofTwente, Enschede, The Netherlands
15
Solver physics 23
© 2003 - 2013 Lumerical Solutions, Inc
"Effective index approximation of photonic crystal slabs: a 2-to-1-D assessment", Opticaland Quantum Electronics ,Volume 41, Number 4, 267-283, DOI: 10.1007/s11082-009-9349-32 Allan W. Snyder and John D. Love, Optical Waveguide Theory. Chapman & Hall, London,England, 1983.
2.3.2 Eigenmode expansion
This unidirectional eigenmode expansion method is implemented in the propagatecommand.
The propagate command calculates the resulting mode profile of an arbitrary mode after ithas propagated through a waveguide for some distance. This is done by decomposing themode into modes supported by the waveguide (ie. the currently calculated modes) using overlap integrals. Each supported mode is then propagated through the waveguide. Theresulting modes are then added coherently to give the final mode profile.
This technical is useful for waveguide couplers, long tapers and other devices where thepropagation can be assumed to be essentially uni-directional. Please see MODE Solutions'applications library for some use case examples:Evanescent waveguide couplersTapered waveguidesPolarization rotator
2.3.3 Meshing in the propagator
The MODE Solutions Propagator uses a rectangular, Cartesian style mesh, like the oneshown in the following screenshot. It's important to understand that of the fundamentalsimulation quantities (material properties and geometrical information, electric andmagnetic fields) are calculated at each mesh point. Obviously, using a smaller meshallows for a more accurate representation of the device, but at a substantial cost. As themesh becomes smaller, the simulation time and memory requirements will increase. MODE Solutions provides a number of features, including the conformal mesh algorithm,that allow you to obtain accurate results, even when using a relatively coarse mesh.
By default, the simulation mesh is automaticallygenerated. To maintain accuracy, the meshingalgorithm will create a smaller mesh in high index (tomaintain a constant number of mesh points perwavelength) and highly absorbing (resolve penetrationdepths) materials. In some cases, it is alsonecessary to manually add additional meshingconstraints. Usually, this involves forcing the mesh tobe smaller near complex structures (often metal)
Reference Guide24
© 2003 - 2013 Lumerical Solutions, Inc
where the fields are changing very rapidly.
Note: meshing timeThe general meshing algorithm can take a reasonable amount of time compared to thesimulation because the mesh must be effectively completed in 3D. It is possible for theuser to specify if the structure is composed of purely extruded structures - that isstructures that are extruded along z with perfectly vertical sidewalls. In this case, themeshing can be accomplished much faster.
2.4 INTERCONNECTINTERCONNECT is a circuit simulator that can support mixed signal representation ofoptical single and multi-mode signals as well as electrical signals. The signals canpropagate fully bidirectionally through the circuit topology for both Time Domain andFrequency Domain simulations.
Users can choose elements from an extensive list of pre-defined PIC elements, as well ascreate custom elements from pre-defined primitives or via Lumerical’s powerful scriptlanguage. In addition, elements can also be characterized accurately using results directlyfrom Lumerical's electromagnetic simulators (FDTD Solutions and MODE Solutions).
2.4.1 Time Domain Simulator
Time domain simulation is performed using a data flow system simulator, allowing for moreflexibility than using traditional discrete time or time-driven simulators. The simulatorscheduler calculates each element in order to generate time domain waveform samples andpropagate them bidirectionally. Very close coupling between components can be simulatedallowing, for example, the analysis of optical resonators.
24
25
Solver physics 25
© 2003 - 2013 Lumerical Solutions, Inc
2.4.2 Frequency Domain Simulator
Frequency domain simulation is performed using scattering data analysis to calculate theoverall circuit response.
The circuit is composed a series of elements connected by an arbitrary number of input/output (or bidirectional) ports. Users can define all the modes supported by the device andtheir frequency dependent properties.
Once all the ports are defined, INTERCONNECT carries out the scattering data analysis forthe entire circuit by solving a sparse matrix that represents the circuit as connectedscattering matrices, each one of them representing the frequency response of an individualelement.
2.5 DEVICEDEVICE is an physics-based electrical simulation tool for semiconductors, which self-consistently solves the system of equations describing the electrostatic potential anddensity of free charge (electrons and holes). DEVICE solves the drift-diffusion equation todescribe the spatial distribution of electrons and holes, and solves the Poisson equation toestablish the electrostatic potential. Solving the drift-diffusion (DD) equations is anestablished and robust method that will produce accurate results for a wide range ofsemiconductor devices under common operating conditions.
This section will introduce the basic mathematical and physics formalism behind the self-consistent algorithm used in DEVICE, starting from the non-linear Poisson and drift-diffusion equations. The simulator can be used for advanced research and development oras an ideal teaching and learning environment in semiconductor electronics andoptoelectronics.
2.5.1 System of Equations
DEVICE solves the drift-diffusion equations for electrons and holes (carriers)
nqDnq nnn EJ
pqDpq ppp EJ
where Jn,p is the current density (A/cm2), q is the positive electron charge, µ n,p is themobility, E is the electric field, Dn,p is the diffusivity, and n and p are the densities of the
Reference Guide26
© 2003 - 2013 Lumerical Solutions, Inc
electrons and holes, respectively (the subscripts n and p indicate quantities that arespecific to the carrier type). Each carrier (electron or hole) moves under the influence of twocompeting processes: drift due to the applied electric field, and random thermal diffusiondue to the gradient in the density. These processes are represented in the drift-diffusionequations as the sum of two terms.
The mobility µ n,p describes the ease with which carriers can move through thesemiconductor material, and is related to the diffusivity Dn,p through the Einstein relation
q
TkD B
pnpn ,,
where kB is the Boltzmann constant. The mobility is a key property of the material, andmay be modeled as a function of temperature, impurity (doping) concentration, carrierconcentration, and electric field. For further details, please see the section on materialmodels.
To solve the drift-diffusion equations, the electric field must be known. To determine theelectric field, Poisson's equation is solved:
qV
where ε is the dielectric permittivity, V the electrostatic potential )( VE
and ρ thenet charge density,
Cnp
which includes the contribution C from the ionized impurity density.
Finally, the auxiliary continuity equations are required to account for charge conservation
nn Rqt
nJ
1
pp Rqt
pJ
1
where Rn,p is the net recombination rate (the difference between the recombination rateand generation rate). The physical processes associated with the material are assumed toact equivalently when applied to electrons or holes, and as a result, R = Rn = Rp. Therecombination and generation processes are important factors in the material-specificcalculation of carrier behavior. Multiple recombination and generation processes aremodeled, which may depend on temperature, impurity (doping) concentration, carrierconcentration, electric field, and current density. For further details, please see the sectionon material models.
Solver physics 27
© 2003 - 2013 Lumerical Solutions, Inc
DEVICE discretizes and solves the drift-diffusion and Poisson’s equations on anunstructured finite-element mesh in one and two dimensions. The simulation region ispartitioned into multiple domains along boundaries between materials with unique physicaldescriptions. The materials used in the simulation may be categorized as insulators,semiconductors, or conductors; each type of material has an associated user-specifiedmodel or collection of models that describe its behavior. In particular, specialized multi-coefficient models are provided for semiconductors that describe the fundamentalproperties, mobility, and recombination processes inherent to that material.
The system of equations solved by DEVICE admits both a steady-state and time-varyingresult. By enforcing the condition
0t
p
t
n
in the continuity equations, the carrier density and electrostatic potential can be solved atsteady-state. Steady-state simulations can be used to examine the system’s behavior at afixed operating point, and are also useful when extracting small-signal parameters for acomponent (e.g. for frequency response analysis). Alternately, by specifying an initialcondition for the carrier density and electrostatic potential, the equations can be solved in asequence of discrete times. The time-dependent behavior of the component can then beused to directly evaluate its large-signal time-domain response or extract large-signal ACparameters.
Boundary conditions are very important in an accurate semiconductor device simulation.Two categories of boundary condition are present in DEVICE: those that relate to theelectrostatic potential (Poisson’s equation) and those that relate to the carrier densities(the drift-diffusion equations). Poisson’s equation and the drift-diffusion equations aresecond-order partial differential equations (PDE), and each requires that the solution beexplicitly specified for at least one location. This is known as a Dirichlet boundarycondition. For the electrostatic potential, the Dirichlet condition takes the form of aboundary (internal or external) with a fixed voltage specified,
1)( VxV
as is typical of an electrical contact. For the carrier densities, the majority carrierconcentration is set to its equilibrium value at the interface between a contact and thesemiconductor, such that
0Cnp
At internal boundaries between two domains that are not contacts, the boundary conditionsare determined from the physical properties of the interface. In the case of the electrostaticpotential, the electric flux density must be continuous across the boundary in the absenceof a surface charge. For the electron and hole densities, boundary conditions between the
Reference Guide28
© 2003 - 2013 Lumerical Solutions, Inc
semiconductor and adjacent materials may be specified in terms of a surfacerecombination current density, which will default to zero (no carrier flux across theboundary) for insulators or an infinite recombination velocity (forcing the carrier density toits equilibrium value) for contacts. At the external (open) boundaries of the simulationdomain, homogenous Neumann boundary conditions are applied: the electric field normal tothe boundary is set to zero as is the surface recombination current density. Physically, thiscorresponds to an insulating boundary across which no charge can flow.
By convention, the length units in semiconductor models are chosen to be centimeters.This is reflected in the semiconductor device literature, and in the parameter coefficients forthe material models. Energies are calculated in electron Volts (eV), where the electronenergy E is related to the local electrostatic potential (voltage) as E = -qV. All energies(and voltages) are referenced from the (equilibrium) Fermi level of an electrical contact inthe system.
2.5.2 Meshing in DEVICE
DEVICE uses an unstructured, finite-element mesh, like the one shown in the followingscreenshot. The solution to the system of equations used to determine the physicalquantities of interest is estimated from the discrete formulation of those equations.Consequently, it's important to understand that of the fundamental simulation quantities(material properties, geometry information, electrostatic potential, and carrierconcentrations) are calculated at each mesh vertex.
A finer mesh (with shorter edge lengths and smallerelements) will better approximate the exact solutionto the system of equations, but at a substantial cost.As the mesh features become smaller, the simulationtime and memory requirements will increase. DEVICE provides a number of tools, including theautomatic and guided mesh refinement, that allowyou to obtain accurate results, while minimizingcomputational effort.
CAD layout editor 29
© 2003 - 2013 Lumerical Solutions, Inc
3 CAD layout editor
The image below shows a typical Lumerical CAD Layout Editor. This tool is used to setupand analyze all simulations, and to run all script files.
In this screenshot,different regions of theCAD in Layout modeare highlighted. Theyinclude:
Main title barToolbarsView portsObject TreeOptimization andSweepsScript Prompt
The Layout Editor has two modes of operation: Layout mode and Analysis mode. Layoutmode is used to setup your simulation. Simulation objects can be added, modified anddeleted in this mode. After a simulation runs, the Layout Editor automatically switches toAnalysis mode. In analysis mode, it is not possible to edit the simulation objects, sincewe want the object settings to match the data from the simulation. To edit simulation
objects, switch back to layout mode with the button.
3.1 Main title barThe menus on the main title bar are listed below. If any of the options can be selectedusing a button on a toolbar, the icon is drawn to the left of the name. Similarly, shortcutkeys are located to the right.
File The file menu includes options to create, save and load simulation files. The Import menuallows users to import structural data stored in GDSII files files.
29
30
36
37
38
38
60
Reference Guide30
© 2003 - 2013 Lumerical Solutions, Inc
EditThe edit menu allows users to undo/redo their actions, and to copy/paste/edit object in thesimulation.
ViewThe view menu provides options to control the layout and visibility windows and toolbars.
SettingThis setting menu contains options to change the unit setting within the graphical interface. These option only apply to the GUI. Scripts always use SI units.
Simulation This menu contains settings for configuring resources and running simulations.
HelpThe help menu provides links to local PDF copies of the product documentation and linksto the larger set of online documentation, as well as options for checking which version of the software is installed.
3.2 ToolbarsThe following sections describe the various toolbars. Toolbars visibility can be controlled inthe View - Toolbars menu.
3.2.1 Main
The main toolbar contains buttons to add various Simulation objects, open the Materialdatabase and import files, as described below. When available, clicking the arrow to theright of the icon expands a drop-down menu containing related buttons. If one of the relatedbuttons is pressed, it replaces the default button in the toolbar. See the Simulation objectschapter for information about specific objects.
Material Database This button opens material database window. For more information, see the Materialdatabase chapter.
StructuresThis button will insert the shown structure primitive into the simulation. Pressing the arrowwill show all available primitives.
42
42
CAD layout editor 31
© 2003 - 2013 Lumerical Solutions, Inc
GroupsThis button will add an analysis, container or structure group into the simulation. Pressingthe arrow will allow selection of which group to add.
SimulationThis button will insert simulation or mesh override regions. Pressing the arrow will allowselection of which simulation object to add.
ImportThis button will open a window for importing files from other programs. Pressing the arrowwill allow selection of which kind of import.
DopingThis button will insert various doping regions into the simulation. Pressing the arrow willallow selection of which monitor to add.
GenerationThis button will insert various generation rate objects into the simulation. Pressing thearrow will allow selection of which monitor to add.
3.2.2 Edit
The edit toolbar contains tools used to copy, delete, or modify settings of simulationobjects.. When applicable, the shortcut key used to run the function from the keyboard isgiven in brackets next to the name of the tool. An object must be selected in order to usethese tools.
Edit properties (E) This command opens the edit properties window. See the Simulation objects chapter forinformation about specific properties for each object.
Tip: Group edit of multiple objects
Reference Guide32
© 2003 - 2013 Lumerical Solutions, Inc
The properties of multiple structure objects can be edited together by selecting multipleobjects prior to entering edit mode. This option is only available for structure objects, notsources or monitors. Any properties which are identical between all of the selectedobjects 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 arecreated are identical to the originals, apart from a one grid cell offset in their x positionwhich allows the user to distinguish between the original and the copy. When multipleobjects are selected, all of the selected objects will be copied. When copying sources andmonitors, it is important to rename the copies so that each object has a unique name.
MoveThe move command allows shifting a single or multiple selected objects by a specifieddistance in each of the x,y,z dimensions. A pop-up window appears with field entries tospecify the shift amount.
ArrayThe array command allows the user to create an array or arrays of objects.
The array edit window that pops up contains several properties :A1 LATTICE: the distance between adjacent elements in the a1 directionA2 LATTICE: the distance between adjacent elements in the a2 directionANGLE BETWEEN A1 AND X-AXIS: the angle (in degrees) between the a1 direction andthe x-axisANGLE BETWEEN A1 AND A2: the angle (in degrees) between the a1 and the a2directions. COLUMNS, ROWS: the number of rows and columns that comprise the array.AZ LATTICE: the distance between adjacent elements in the z direction (valid for 3Dsimulations only)LAYERS: the number of elements in the z direction (valid for 3D simulations only)
The parameters in the edit window below produce the resulting array shown in the diagram.
CAD layout editor 33
© 2003 - 2013 Lumerical Solutions, Inc
Delete (Del)The delete command removes the currently selected object, or objects, from thesimulation.
3.2.3 Mouse mode
The mouse mode allows you to control the behavior of the mouse. Depending on themode, the user can edit objects, pan or zoom in the view ports or measure the distancefrom one point to another. When applicable, the shortcut key used to run the function fromthe keyboard is given in brackets next to the name of the tool. Only one mouse mode maybe selected at a time.
Select (S)This function puts the mouse into the select mode. This allows objects to be selectedthrough the view ports (objects may be selected in the objects tree regardless of whetherthe mouse is in select mode or not).
For reference, the current location of the mouse within the view ports is shown in the field atthe bottom right-hand corner of the CAD window (see the image below). The < and >buttons at the right decrease or increase the number of decimal places shown.
Changing aspect ratio settingsA feature available when in the select mode is changing aspect ratio settings. Right clickin one of the view windows to see the menu, and then select Change aspect ratiosettings.
Zoom (Z)
Reference Guide34
© 2003 - 2013 Lumerical Solutions, Inc
This function sets the mouse to be in the zoom mode. The default aspect ratio of the XYview and perspective views are locked at 1:1, which means circles always appear round(rather than as ovals). The aspect ratio for the XZ and YZ is not locked. Use the left clickto zoom in and the right click to zoom out. To zoom to a particular area, drag diagonallyacross the desired region. Finally, double clicking either button zooms to extent. Toadjust the view, it's easiest to set the XY view first, then adjust the Z view in the XZ or YZviews.
Pan view (P)The pan view mode allows the user to drag the view in the plane of the view port. In thePerspective window, the pan mode is used to rotate the view.
Scrolling in the view portsThe other method of adjusting the view ports is by using the arrow buttons on yourkeyboard. Each press of a button results in the view shifting in the direction indicated bythe arrow.
Ruler (R)Once the ruler mode is selected, a distance measurement can be made by pressing theleft mouse button and then dragging the mouse. A non-permanent triangle is drawnbetween the locations where the mouse button was pressed (A) and released (B). Thedistances are given in the lower left-hand corner of the CAD window (see the image below).The dx and dy fields correspond to the horizontal and vertical distance between A and B,and the AB field corresponds to the length of the hypotenuse.
3.2.4 View
The view toolbar contains tools to zoom to the extents of objects, edit grid settings andview the mesh used for the simulation. When applicable, the shortcut key used to run thefunction from the keyboard is given in brackets next to the name of the tool.
Zoom Extent (X)Selecting this tool centers and scales the view ports around the selected simulationobjects. For instance, pressing zoom extent while a structure is selected arranges theview such that only the structure are shown, while other simulation objects may appearoutside the extent of the view. When no objects are selected, pressing this button zoomsto the the largest object in the model. This function is also accessed via double-clickingeither the left- or right-hand mouse button while in zoom mode.
CAD layout editor 35
© 2003 - 2013 Lumerical Solutions, Inc
Drawing GridClicking on the drawing grid brings up a window in which the following options can beedited:
SHOW GRID: when checked, the grid will be plotted in the drawing paletteSNAP TO GRID: when checked, objects can only be moved so that their centers alignwith intersection points of the gridA1 LATTICE: the distance between grid lines in the a1 directionA2 LATTICE: the distance between grid lines in the a2 directionAZ LATTICED: the distance between grid lines in the z directionANGLE BETWEEN A1 AND X-AXIS: the angle (in degrees) between the a1 direction andthe x-axisANGLE BETWEEN A1 AND A2: the angle (in degrees) between the a1 and the a2directions
Recalculate simulation mesh (F5)Mesh generation is too computationally intensive to be done constantly as the simulationsetup is modified. If you wish to see the current mesh, use this option to update andrecalculate the mesh. The mesh is always recalculated before running a simulation.
3.2.5 Simulation
The simulation tools are:
ResourcesOpens the resource configuration manager. This window can add/remove and enable/disable computational resources. It also contains a useful configuration test tool to checkthe resource setup.
RunRun the current simulation. For more information on how to run simulation, see Running asimulation.
Run scripts This function will allow the user to run a Lumerical script file (*.lsf) to perform automated
commands such as plotting and saving data. This button is located in the CAD environmenttwice if the script editor is open: once in the simulation toolbar and once at the top of thescript editor. Pressing the button on the toolbar brings up an open file dialog. Pressing thebutton in the script editor runs the script that is selected in the editor window.
Reference Guide36
© 2003 - 2013 Lumerical Solutions, Inc
Switch to layout editor This function returns the simulation environment from analysis mode back to the layouteditor mode. If you switch to layout editor and then save the file, the data from thesimulation will be overwritten and lost.
3.2.6 Search bar
The search toolbar can be used to quickly search for topics in the online productdocumentation knowledge base. This will bring up the search results in a new tab in yourdefault browser.
Online help toolbarSearch the online knowledge base for the specified term. Requires internet connection. Ifan internet connection is not available, some product documentation is available in the Help- Reference Guide menu.
3.3 View portsThe view ports show a graphicalrepresentation of the simulation froman XY, XZ, YZ and 3D perspectiveview.
Depending on the current mousemode, the mouse pointer will eitherhave the shape of an arrow (select),a hand (pan), a magnifying glass(zoom) or a ruler (measurement).You can toggle between theseoptions with the mouse modetoolbar. When objects are selected,the vertices are drawn with redsquares (also, the object will behighlighted in the Object tree. It ispossible to copy and paste selectedobjects between different CADwindows using the standard Ctrl+Cand Ctrl+V shortcut keys.
CAD layout editor 37
© 2003 - 2013 Lumerical Solutions, Inc
3.4 Object TreeAs previously discussed, a simulation requires thatthe user define a set of objects, simulation region,sources and monitors. As a complete setup maycontain a large number of objects, the object tree wasdesigned to allow for organization and easy selection. All simulation objects are within the group, model,which represents the current simulation. Within'model', objects are listed as they are inserted by theuser. Press F2 or double-click to change the name.
To move the objects up and down the tree as well as into groups, we use the orange arrowsat the top of the window. The up and down arrows shift the objects relative to each other,while the left and right arrows move them out of and into groups. To add groups, we usethe button called groups in the main toolbar. Structure groups can only contain structuresand likewise, analysis groups can only contain monitors. See the online user guide sectionfor more information and examples about Structure groups and Analysis groups. The thirdgroup, "Containers" act like folders and can hold any type of object. In the image above,the 'Sources/Monitors' container group has both individual sources and monitors as well asan analysis group.
Note that there are buttons with green crosses at the top of the objects tree. These buttonscan be used to hide or display certain types of objects. When objects are selected, theyare highlighted blue in the objects tree and the vertices are marked with red squares in theview ports. Objects can always be selected by left-clicking on their name in the object treeor edited by right-clicking. Using the tree is the preferred method of selection especially incomplicated simulation setups with many overlapping elements. In the image above, thepower monitor, above, is selected.
3.4.1 Enable/Disable Simulation Object
User can enable/disable simulation objects by right-clicking on each and selecting"Enable/Disable". Disabled simulation objects will remain in the object tree (and can be
Reference Guide38
© 2003 - 2013 Lumerical Solutions, Inc
re-enabled), they will have no effect on the simulation.
See alsosetnamed , set
3.5 Results ViewSee the Results View section of the Reference Guide for more information.
3.6 Optimization and SweepsSee the Optimization and parameter sweeps section of the Reference Guide for moreinformation.
3.7 Script Prompt and Script EditorThe scripting language is useful for setting up complex structures and advanced dataanalysis. See the Scripting chapter for a list of all the script commands, as well asexamples on how to use them.
By default the script editor is located on the right hand side of the view ports and sharesthe same frame as the analysis window. When both windows are open, it is possible totoggle between the two through tabs located at the right side of the frame. The script fileeditor contains buttons to create, open, save and run script files. When multiple script filesare open, pressing on the run script button runs the one in the forefront. Note that whenentering scripting code in the script file editor, each command must be followed with asemicolon.
When running a script file in the a different directory using the GUI, the current workingdirectory 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 thecurrent directory first, then any other folders in the path, and then the directory of the scriptfile.
232 231
93
97
CAD layout editor 39
© 2003 - 2013 Lumerical Solutions, Inc
By default the script prompt islocated at the bottom of the CADwindow. Script commands areexecuted as soon as the ENTERbutton is pressed on the commandline. If a semicolon is missing at theend of the command line, it isautomatically inserted it for you.Multiple lines can be pasted into thescript prompt, and will run as in thescript editor. In this case though,only the last semicolon can beneglected.
3.8 Script Workspace and Script FavoritesSee the Script Workspace and Script Favorites section of the Reference Guide for moreinformation.
3.9 Changing the CAD layoutThere are pre-defined CAD layouts that can be accessed through main title toolbar. Changebetween the default layouts by selecting the drop-down menu VIEW->SET DEFAULTLAYOUT, and choosing one of them. In addition, have control over hiding and dockinglocation of the the windows and toolbars. The current layout is saved when CAD closes sothe next time the program is opened, your previous layout will be used.
95
Reference Guide40
© 2003 - 2013 Lumerical Solutions, Inc
Hiding/showing windows andtoolbarsThere are two methods to hide orshow windows and toolbars1) In the main title toolbar selectVIEW->WINDOWS or VIEW->TOOLBARS. The visible windows/toolbars have a check mark next totheir name; the hidden ones do not.2) By clicking the right buttonanywhere on the main title bar or thetoolbar, the following pop up menuwill show up. As before, checkmarks indicate when windows andtoolbars are visible.
Moving and undocking windowsWindows can be undocked bydouble clicking the name with theleft mouse button. This isparticularly useful when you want tomake the script file editor windowlarger. Non-view-port windows canbe docked on top of each othereither to the right or to the left of theview ports. If they are placed on topof each other, tabs on the sidesallow toggling between them.
Tip: To reposition an undockedwindow on Linux, hold down the Altkey before attempting to move thewindow.
Moving toolbarsTo move a toolbar, hover the mouse over the top of the toolbar, where the dotted line is.When the mouse cursor becomes a four-headed arrow, press the left mouse button and
CAD layout editor 41
© 2003 - 2013 Lumerical Solutions, Inc
drag-and-drop the toolbar. If you reach a region where you can place a toolbar, the CADenvironment makes room for the toolbar indicated by a blue void.
Reference Guide42
© 2003 - 2013 Lumerical Solutions, Inc
4 Material database
This chapter explains the Material Database. See the following pages for details. Usersmay also find the Material modeling recorded video to be helpful.
Material databaseThe Materials Database allows for the definition of complex materials using experimentaldata or parametrized models. It can be accessed by clicking the material database buttonon the Structures tab. The Material Database stores the material data to be used in thesimulation. It also provides an interface to change material properties like color, meshorder, and model parameters. Experimental data can also be loaded into the database. Toview the resulting index profile, use the Material Explorer.
Electrical modelsSee this section for information on the available material models; insulators,semiconductors, and conductors.
Mesh orderSee this section for information on the mesh order property, which defines the meshingbehavior (priority) for overlapping objects.
4.1 Material databaseThe Materials Database allows youto manage (create, modify, delete)the materials that are available foruse in your simulations. A copy of the database is stored ineach simulation file. A change tothe database in one file does notautomatically change the materialsin any other files. To modify thedefault materials that appear whenyou create a new simulation, editthe simulation file in the Defaultssubdirectory of the installationdirectory.
Import / ExportThe import and export buttons allow you to transfer material data between simulation filesvia Material Database Files (.mdf) files.
42
43
54
Material database 43
© 2003 - 2013 Lumerical Solutions, Inc
Material list The material list shows the materials stored in the material database. A number ofmaterials are provide with the product installation. To create additional materials, use theAdd button. You can also modify some of the material properties (name, color, meshorder, etc) in the list view.
Default materials provided with the product installation are write protected, and can not bedirectly modified. To modify the properties of a default material, simply use the Copybutton to duplicate the material. The copy will be unlocked. The first column of the listshows which materials are write protected.Materials currently used in the simulation can not be deleted. The second column of thelist shows which materials are in use. To delete these materials, first modify the simulationso they are not used.
Material PropertiesUse the Material properties window to view and edit the material model parameters. Formodel parameter definitions, see the material models section.
4.2 Electrical modelsThis section describes the electrical material models supported by the Material Database. Model parameters can be edited in the Material property panel of the Material Databasewindow. Materials are categorized by their physical characteristics. The three types ofsupported materials are conductors, insulators, and semiconductors.
ConductorMaterials that are defined as conductors are treated as ideal electrical conductors inDEVICE: they are assumed to have zero resistivity. Consequently, the internal electric fieldmust be zero, and the voltage applied to the conductor will be constant across its domain.Materials specified as conductors will be treated as ideal electrical contacts in thesimulation.
See more detailed information on Conductors .
InsulatorMaterials that are defined as insulators are treated as ideal electrical insulators in DEVICE:they are assumed to be perfect dielectrics without free charge.
See more detailed information on Insulators .
SemiconductorSemiconductors, like insulators, are band gap materials. The band gap of a semiconductoris typically small enough to allow a significant fraction of electrons to be thermally excited
44
44
Reference Guide44
© 2003 - 2013 Lumerical Solutions, Inc
from the valence band to the conduction band at room temperature (300K). The band gapfor a semiconductor typically ranges from 0.5-1.5eV. When energetically excited to aconduction band state, electrons leave behind a positively charged mobile vacancy, knownas a hole, which behaves much like a free electron in the semiconductor. The mobility ofthe electrons and holes and the rates at which they are generated and recombine aredetermined by the models described in this section.
See more detailed information on Semiconductors .
4.2.1 Conductors
Conductor Fundamental PropertiesWork FunctionThe defining characteristic of the conductor is its work function, which describes the energycost of removing an electron from the material.
4.2.2 Insulators
Insulator Fundamental PropertiesRelative Dielectric PermittivityThe relative permittivity (or dielectric constant) of the material is equal to the square of therefractive index, and is assumed to be the DC (zero frequency) value.
4.2.3 Semiconductors
In This Section:Semiconductor Fundamental PropertiesMobility Bulk Recombination and GenerationSurface RecombinationReferences
Semiconductor Fundamental PropertiesRelative Dielectric PermittivityThe relative permittivity (or dielectric constant) of the material is equal to the square of therefractive index, and is assumed to be the DC (zero frequency) value.
Work FunctionIn a semiconductor, the work function φs describes the energy cost of removing an electronfrom the intrinsic energy level (the Fermi energy of the undoped semiconductor) and placingit at "infinity." A related value is the electron affinitiy χs, which is the energy cost ofremoving an electron from the conduction band edge.
44
44
46
50
53
54
Material database 45
© 2003 - 2013 Lumerical Solutions, Inc
V
CBGiss
N
NTkEln
22,
where EG is the band gap and NC and NV are the effective density of states in theconduction band and valence band, respectively.
Effective MassTo account for the influence of the crystal lattice potential of the semiconductor, electronsand holes can be approximated as free charges with an effective mass (relative to theelectron rest mass) that depends on the electronic band-structure of the material. InDEVICE, the effective mass is treated as a parameter of the material model.
The temperature variation in the effective mass can be accounted for with a quadraticmodel
2*,
*, )0()( TTmTm pnpn
where coefficients α and β, and the effective mass at T=0K are inputs to the model.
Related to the effective mass is the effective density of states in the conduction andvalence bands
2/3
2
*22
h
TkmN Bn
C
2/3
2
*22
h
TkmN
Bp
V
where h is Planck’s constant.
Band GapA key physical property of the material is the band gap, which, like the effective mass, isderived from the electronic band-structure of the material. In DEVICE, the band gap energyis treated as a parameter of the material model.
The temperature variation in the band gap can be accounted for with a "universal" empiricalmodel
T
TETE GG
2
0,)(
where coefficients α and β, and the band gap energy at T=0K are inputs to the model.
Band Gap Narrowing
Reference Guide46
© 2003 - 2013 Lumerical Solutions, Inc
When impurities are added to the intrinsic (pure) semiconductor, localized allowed energystates may be introduced at energies that lie within the band-gap. In the case of dopants,these impurity states will exist with energies near the conduction or valence band edges(such that the dopants readily ionize at moderate temperatures). When the concentration ofdopants is large, these discrete states will begin to merge and form a thin "band" of allowedstates within the band gap, effectively narrowing the band gap. This can be viewed as anarrowing of the band gap or an increase in the effective density of states.
The Slotboom model1 for band gap narrowing is provided in DEVICE to account for thiseffect,
CN
NN
N
NNVE ADAD
G
0
2
0
1 lnln
where the coefficients V1, N0, and C are inputs to the model, and the effect can bespecified independently for electrons and holes. Note that the sign implies a narrowingeffect for positive coefficients.
Intrinsic Carrier ConcentrationThe intrinsic carrier concentration is calculated from the effective mass and band gap, andis only displayed in the Material Database for reference. It is calculated as
TkENNn BGVCi 2/exp
where T=300K is assumed, and the effective density of states and band gap are treated aretreated as intrinsic quantities (before band gap narrowing).
MobilityThe mobility parameter in the drift-diffusion equations is the physical link between themotion of carriers (electrons and holes) and the semiconductor material. The mobility canbe viewed as a measure of how readily electrons and holes can move through the crystallattice of the semiconductor. In the absence of any interactions with the lattice, impurities,or other carriers, electrons and holes would move freely in the periodic potential of thelattice; interactions that change the momentum of the carriers are termed scatteringevents. Different types of scattering contribute to the mobility of the electrons and holes,including
lattice scattering,ionized and neutral impurity scattering, andcarrier-carrier scattering.
In addition, the velocity of the carriers is observed to saturate at high-fields. Each of thesescattering mechanisms can be addressed in DEVICE by applying the appropriate models,which are detailed in the following sections.
Lattice Scattering
54
Material database 47
© 2003 - 2013 Lumerical Solutions, Inc
The fundamental process that impedes the free motion of the carriers in the lattice isthermal scattering off of the lattice itself. The mobility due to lattice scattering is treated asa basic input into the DEVICE semiconductor model, and may be entered as a constantvalue or with a temperature dependence described by the "universal" temperature model,
300)300()(
TATA
where A(300) is the value of the parameter at T=300K, and η is a temperature exponent. In
the case of the lattice scattering mobility µ L, the temperature dependence reads
300)300()( ,,
TT L
pnL
pn
.where subscripts n and p refer to electrons and holes, respectively.
Impurity and Free-Carrier ScatteringMany models exist to account for the influence of impurities on the carrier mobility.DEVICE provides support for three common models with wide-ranging applicability: the
Caughey-Thomas model2 , the Masetti model3 , and the Klaassen model4 . Eachmodel requires a variety of coefficients; default values are provided with DEVICE forcommon semiconductors.
For general modeling purposes, the Caughey-Thomas model or Masetti models are oftensufficient, and coefficients are available for multiple semiconductor materials. The Klaassenmodel is primarily tuned for silicon at T=300K, and coefficients for other materials are notavailable. At moderate doping densities, the mobility predicted by all models reduces tothat of the Caughey-Thomas model.The most basic model is the Caughey-Thomas model,
ref
pnL
pn
pnLI
pnNN /1
min,,min
,,
where N is the total doping concentration (N = NA + N
D), µ L is the lattice scattering mobility
(as determined from the model chosen in the previous section), and µ min, Nref, and α aretemperature-dependent coefficients described the universal temperature model.
To account for extremely large doping concentrations, the Masetti model can be selected,which adds a correction to the Caughey-Thomas model for large N:
NCCN s
pn
r
pnL
pn
pnLI
pn/1/1
)2(,
min,,min
,,
.
Again, N is the total doping concentration (N = NA + N
D) and µ L is the lattice scattering
54 54 54
Reference Guide48
© 2003 - 2013 Lumerical Solutions, Inc
mobility. Parameters µ min, µ (2), Cr (replacing N
ref of the Caughey-Thomas model), C
s, α,
and β are each temperature-dependent coefficients described the universal temperaturemodel.
Finally, the mobility model proposed by Klaassen can be used to account for theaforementioned doping effects (at moderate and high impurity concentrations), as well asthe influence of carrier-carrier scattering. The Klaassen model combines the basic latticescattering with the impurity and carrier-carrier scattering using Matthisen’s rule
ICpn
Lpn
LICpn ,,,
111
where µ L is the lattice scattering mobility and µ IC is Klaassen’s impurity and carrier-carrier(IC) scattering mobility. The formulation of the IC scattering mobility is complex andinvolves multiple levels of coefficients and models accounting for
majority carrier scattering by dopants,minority carrier scattering by dopants, andelectron-hole scattering.
To begin, the IC mobility is defined as a function of the dopant and carrier concentrations,
..,
min,,
min,,
,
1
..,
,
min,,
2,
, ,,,effscpnpn
Lpn
pnL
pn
scpn
ref
effscpn
scpn
pnL
pn
Lpn
ADIC
pnN
pn
N
N
N
NpnNN
where µ L is the lattice scattering mobility, and coefficients µ min, Nref 1
(equivalent to Nref
or C
r), and α are defined as for the Caughey-Thomas or Masetti models. Note that the Klaassen
model accounts for temperature dependence separately, therefore constant a constantvalue should be used for the lattice scattering mobility.
In the preceding equation, the "scattering densities" are
nNNN
pNNN
DAscp
ADscn
where the donor and acceptor densities, ND and N
A respectively, are corrected according to
the clustering function:
2
,
2
,
/
/
AArefA
AAA
DDrefD
DDD
NNC
NNN
NNC
NNN
Material database 49
© 2003 - 2013 Lumerical Solutions, Inc
Here, CD, N
ref ,D, C
A, and N
ref ,A are coefficients of the model.
The "effective scattering densities" are defined as (using the same clustering-correctedacceptor and donor concentrations)
p
DpAeffsc
p
n
AnDeffsc
n
PF
nNPGNN
PF
pNPGNN
..
..
The function G describes the ratio of scattering cross-sections between repulsive andattractive screened Coulomb potentials as a function of the factor P (itself a function ofcarrier density and majority dopant density). The factor P accounts for the screening effect,and is calculated as the weighted harmonic mean of two parameters accounting for thefree-carrier and ionized impurity screening,
1
,,
1
,,
,
,
pP
f
NP
fpNP
nP
f
NP
fnNP
pBH
BH
ApCW
CWAp
nBH
BH
DnCW
CWDn
Weights fCW
and fBH
are coefficients of the model.
The same factor P is used in the calculation of the function F, which describes the mobilityratio between stationary, infinite-mass secondary scatters (e.g. ionized impurities) andmobile, finite-mass secondary scatters (e.g. free carriers). Both functions F and G areparameterized fitting functions to physical processes, and the coefficients of thosefunctions (r
1 to r
6 for function F and s
1 to s
7 for function G) are also coefficients of the
model.
High-Field SaturationAs the electric field within the semiconductor increases, the drift-velocity of the carriers iscommonly observed to saturate, reducing the mobility accordingly. To account for thiseffect, DEVICE includes a saturation velocity mobility model
satpn
pnLIC
pn
LICpnLICE
pn
v ,
,,
,
,
1
where µ LIC is the mobility accounting for lattice, impurity, and carrier-carrier scattering (as
Reference Guide50
© 2003 - 2013 Lumerical Solutions, Inc
calculated using the active models for those processes) and vsat is the model coefficient
that determines the saturation velocity. The product of the low-field mobility µ LIC and thegradient of the quasi-Fermi level is equivalent to the velocity in the context of the drift-diffusion equations.
Bulk Recombination and GenerationRecombination describes the processes by which an electron from the conduction bandmakes an energetic transition and neutralizes a hole in the valence band. Generationdescribes the complementary behavior, where an electron is excited from the valence bandto the conduction band, creating a hole in the process (often, the term electron-hole-pair isused when referring to generation). The models for bulk recombination and generationprocesses relate to the physical mechanisms by which the carriers make the energetictransition. DEVICE provides models describing
trap-assisted (Shockley-Read-Hall) recombination,Auger recombination, andradiative recombination.
These models and their parameterizations are the subject of the following sections.
Trap-Assisted (Shockley-Read-Hall) RecombinationThe recombination process in the trap-assisted model assumes that there are unoccupied"trap" states (also referred to deep-level defect states) within the band gap. Typically, thesestates result from impurities (either intentional or unintentional), and the most active haveenergy levels near the middle of the band gap. Recombination occurs when an electronrelaxes (transfers energy to the lattice or emits a photon) to the trap state from theconduction band, and sequentially, a hole from the valence band relaxes to the same trapstate. This process is modeled using the Shockley-Read-Hall (SRH) equation,
11
2
ppnn
nnpR
np
iSRH
where τn and τ
p are the electron and hole lifetimes, respectively, and n
1 and p
1 are the
effective densities of carriers in the trap states. The trap states are characterized by theirdensities N
t, capture cross-section σ
t, and energy level Et - Ei (commonly abbreviated as
Et and referenced to the intrinsic energy level). The constants n1 and p
1 are calculated as
TkEie
TkEie
Bt
Bt
enp
enn/
1
/1
The carrier lifetime can be determined from the capture cross-section and trap density as1
*,
,,
3
pn
Btpnpn
m
TkN
Material database 51
© 2003 - 2013 Lumerical Solutions, Inc
but is commonly taken as an input to the model.
DEVICE provides a temperature dependent model for the SRH carrier lifetime, as well asmodels that include corrections for doping density. The basic temperature-dependent modelfor the carrier lifetime follows the usual power-law relation
pnTT srh
pnsrh
pn
,
300)300()( 0,
,0,
,
Alternately, a constant value can be supplied for both electrons and holes.
To account for doping concentration effects, DEVICE provides two correction models thatuse the previous expression for the SRH carrier lifetime as an input. First, a modified modelin the form proposed by Fossum is described by
refpn
DApn
pnpnpnpnpn
srhpnsrh
pnN
NNN
NN pn
,
,
,,,,,
0,,
, where,,
The original model of Fossum can be obtained by setting coefficients α, β, and σ to one (1)and setting γ to zero (0), and this is the default model used in DEVICE.
Alternately, a formulation proposed by Klaassen can be selected, where the SRH carrierlifetime correction is given by the equation
refpn
DApn
pnsrh
pnpn
srhpnsrh
pnN
NNN
T
N
pn
,
,
,0,
,,
0,,
, where,3001
,
Note that this model explicitly includes the temperature dependence, and should only beused in concert with a constant value for the baseline SRH carrier lifetime.
Auger RecombinationAuger transitions are three-particle transitions (two carriers scatter and transfer energy and/or momentum to a third carrier) that describe four related processes, which are illustrated inthe figures below. Each process has an associated rate coefficient. According to theprinciple of detailed balance, the net rate for each type of carrier must be zero atequilibrium, such that
AUepi
AUcp
AUeni
AUcn CnCCnC 22 and
Assuming that the value of the rate coefficients does not change as the system moves fromequilibrium, the net Auger recombination rate is
2i
AUcp
AUcnAU nnppCnCR
Note that Auger transitions depend only on carrier density, differentiating them from otherrecombination processes.
Reference Guide52
© 2003 - 2013 Lumerical Solutions, Inc
Recombination byelectron excitation
Recombination by holeexcitation
Generation byelectron relaxation
Generation byhole relaxation
pnCR AUcn
AUn
2 2npCR AUcp
AUp nCG AU
enAUn pCG AU
epAUp
DEVICE supports three models for the capture rate coefficients, includingthe universal temperature model proposed by Klaassen,an empirical model by White accounting for a reduction in the recombination rate at highcarrier concentrations, anda model by Clugston and Basore accounting for both high and low injection conditions.
The universal temperature model proposed by Klaassen takes the usual power-law form,
pnTCC pnpn
,
300)300(,
0,
and is suitable for devices where Auger recombination is moderate (low injectionconditions). The Auger rate coefficients are only weakly dependent on temperature, andconstant values may be used as well.
An alternate empirical model proposed by White can be used as a correction to theprevious model, taking that coefficient as an input. The White model accounts for thereduction in the Auger recombination rate observed at high carrier densities (due to strongscreening effects), and is expressed as
p
CC
n
CC
p
pn
n1
,1
00
where the coefficient α determines the transition density.
Material database 53
© 2003 - 2013 Lumerical Solutions, Inc
A related model proposed by Clugston and Basore is designed to account for the tworegimes related to minority carrier injection:
nN
nC
nN
NCC
pN
pC
pN
NCC
A
HIp
A
App
D
HIn
D
Dnn
2
2
0
0
DEVICE will use the Auger capture rate coefficient defined in the Klaassen model (or aconstant value) for the low injection conditions, and apply a second coefficient when strongminority carrier injection dominates according to the preceding formulations.
Radiative RecombinationIn a radiative transition, a conduction band electron will relax directly, emitting a photonwhose energy approximately equals that of the band gap, and then recombine with a holein the valence band. The opposite process occurs when a photon is absorbed by anelectron in the valence band, promoting it to the conduction band and leaving a hole in itsplace. Radiative recombination transitions are typically significant only in materials with anarrow bandgap, or a bandstructure that permits direct transitions in momentum (e.g.GaAs). Radiative recombination is typically negligible in bulk silicon.
The recombination rate is determined from the product of a capture rate coefficient and thecarrier density product,
npCR OPTcOPT
and the corresponding generation rate is simply the emission rate constant,OPTeOPT CG
Once again, the coefficients are related by the principle of detailed balance at thermalequilibrium, such that
2i
OPTcOPT nnpCR
The optical capture rate coefficient can be modeled in DEVICE either as a constant orusing the universal temperature power-law,
300)300()(
TCTC OPT
cOPTc
Surface RecombinationTrap-Assisted ModelLike bulk Shockley-Read-Hall (SRH) recombination, the presence of deep-level trap states
Reference Guide54
© 2003 - 2013 Lumerical Solutions, Inc
at the semiconductor surface catalyzes recombination. The surface recombination processis modeled by a formula similar to that of the bulk case,
s
n
s
p
isurf
pps
nns
nnpR
11
2
11
but differs slightly from the bulk process since it is occurs on a two-dimensional surface.The trap density N
ts is now given per unit area, such that the carrier lifetime of the bulk
case is replaced by a surface recombination velocity,
*,
,,
3
pn
Btspnpn
m
TkNs
The surface recombination velocity is treated as an input parameter in DEVICE, chosen toreflect the non-ideal nature of the material surface. The surface recombination velocity maybe temperature dependent. Like the bulk case, the constants n
1s and p
1s are calculated as
TkEies
TkEies
Bts
Bts
enp
enn/
1
/1
References1. Slotboom, J.W., Solid-State Electron., 20, 279 (1997)2. Caughey, D. M. and Thomas, R. E., Proc. IEEE, 52, 2192 (1967)3. Masetti, G., et al., IEEE Trans. Electron Devices, ED-30, 764 (1983)4. Klaassen, D. B. M., Solid State Electronics, 35, 953 (1992); Klaassen, D. B. M.,
Solid State Electronics, 35, 961 (1992)
4.3 Mesh orderThe mesh order property governs how overlapping objects are meshed in the simulation. Itserves no role for objects which do not overlap. The mesh order can be set at the materiallevel (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 materialproperties of the higher priority material (see the following figure).
Material database 55
© 2003 - 2013 Lumerical Solutions, Inc
In the figure to the left, there are twoobjects that partially overlap. Depending on their mesh orders, theobject that is actually beingsimulated will be different.
In the event that both overlapping materials have the same order, the mesh order will beinferred from the Object tree. Objects at the bottom of the tree will take priority over objectsat the top of the tree. To ensure your simulation is well defined, it is recommended thatyou avoid situations where two different overlapping structure have the same mesh order.
Tip: Plot the geometry after meshing to confirm that the structures was meshed asintended.
Reference Guide56
© 2003 - 2013 Lumerical Solutions, Inc
5 Simulation objects
There are several types of simulation objects inFDTD Solutions, MODE Solutions' propagator,MODE Solutions' Eigenmode Solver and DEVICE.
These objects are used to model the physicalstructure, define the solver region, any sources oflight or doping/generation regions as well asmonitors to collect data.
The following sections provide detailed descriptionsof each simulation object. Each simulation objectcan be added by clicking on the correspondingicon in the GUI.For example, in the screen shot on the right,
clicking on the button would add a circlephysical structure object.
Once the object is selected, pressing the EDIT button will bring up a window where itis possible to modify the properties of the simulation object. The corresponding window forthe circle object is shown below.
TIP: In-field equation interpreterThe fields for numeric parameters can be used as a simple calculator. For instance, if you
Simulation objects 57
© 2003 - 2013 Lumerical Solutions, Inc
wish to set a value to the square root of 3 divided by e, just enter sqrt(3)/exp(1) into thefield. For more information, see the Equation interpreter section.
Notes:Structure objects support Multi-object editing. If you select multiple objects then clickEDIT, you can edit properties that are common to all of the selected objects.Monitors and sources have some global properties that apply to many objects. Forexample, the global source frequency range can be applied to all sources. The global
properties can be edited with the GLOBAL PROPERTIES button.
GroupsSimulation objects can be organized into various types of groupings.
Container GroupA container group is the simplest type and can contain all object types as well as othergroups. This object acts like a simple folder allowing the user to collapse and expand itscontents in the object tree. Its only user setting is a position offset in x,y,z for allcontained objects.
Structure Group Structure groups are one step above container groups in that they allow scriptingcommands of structures properties. This group contains user-generated variables andscripts that can be utilized to edit and set up parts of the structure. For example, a scriptcan be set up to insert many circles to create a photonic crystal cavity of a certain shapeand size. See the Properties tab and Script tab sections for more information.Structure groups can contain other structure groups.
The purpose of this section of the Reference Guide is to describe all of the availablesimulation objects and their properties. This section is organized as follows. There are fivesubsections. The first four subsections correspond to the four types of object categories.Each of these sections begins with a brief overview of the simulation objects followed by adescription of their property settings. The properties are organized according to the tab thatthey are located in when the EDIT button is pressed. The last of the five subsectionsdescribes the syntax for the equation interpreter.
76
65 65
Reference Guide58
© 2003 - 2013 Lumerical Solutions, Inc
5.1 StructuresStructures in a simulation interact with light/electrical sources to produce interestingeffects. They are split into 3 groups:
Structures (Primitives)These are the primitive shapes that make up all structure setups.
ImportsThese options open windows that can be used to import structure data from other sourcessuch as pictures or text files.
5.1.1 Primitives
The button includes options to to add the following primitive structures:
TriangleTriangular objects denote physical objects that appear triangular from above. For 2Dsimulations, these objects represent triangles while in 3D these objects are extruded in thez direction to a specific height. They are actually polygon objects, with the number ofvertices set to 3.
RectangleRectangular regions denote physical objects that appear rectangular from above. For 2Dsimulations, these objects represent rectangles while in 3D these objects are extruded to aspecific height.
Polygon Polygons allow the user to define a custom object with a variable number of vertices. Thelocation of each vertex can be independently positioned within a plane, and the vertices areconnected with straight lines. For 3D simulations, the object is extruded in the zdimension. In DEVICE, the vertices have to be entered in a counter clock wise manner forthe structure to be defined and meshed properly.
Simulation objects 59
© 2003 - 2013 Lumerical Solutions, Inc
CircleCircles denote physical objects which appear circular or ellipsoid from above. They areeither circles/ellipses in 2D, or circular/ellipsoid cylinders in 3D.
RingRing regions represent physical objects that consist of full or partial rings when viewed fromabove. Rings in 3D simulations are extruded in the z direction to a specific height.
Sphere In 3D simulations, users can define spherical regions of constant refractive index throughthe 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 orexpand in the vertical z direction. Pyramids are only available for 3D simulations.
5.1.2 Geometry tab
The geometry tab contains options to change the size and location of the structure.
5.1.3 Material tab
The material options are as follows:
MATERIAL: This field can be set to any material included in the material database. It ispossible to include new materials in the database, or edit the materials already included.See the material database section for more information.
OVERRIDE MESH ORDER FROM MATERIAL DATABASE: Select to override the meshorder from the material database and manually set a mesh order. The mesh order is usedby the simulation engine to select which material to use when two materials overlap. Seethe mesh order section for more details.
MESH ORDER: Set the mesh order in this field if the OVERRIDE MESH ORDER FROMMATERIAL DATABASE option is selected. If the option is not selected, the field displaysthe material's default mesh order from the database. For example, a material of meshorder 1 will take precedence over a material of mesh order 2.
54
Reference Guide60
© 2003 - 2013 Lumerical Solutions, Inc
5.1.4 Rotations tab
Rotate objects by setting the following variables:
FIRST, SECOND, THIRD AXES: Select rotation axis. Up to three different rotations canbe applied. ROTATION 1,2,3: The rotation of the object in a clockwise direction about each axis,measured in degrees.
5.1.5 Graphical Rendering tab
The graphical rendering tab is used to change how objects are drawn in the layout editor.The options are:
RENDER TYPE: The options for drawing the objects are detailed or wireframe. Detailedobjects are shaded and their transparency can be set using OVERRIDE COLOROPACITY 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. Thissetting has no effect on the simulation.OVERRIDE COLOR OPACITY FROM MATERIAL DATABASE: When unselected theopacity is determined from the material database. When selected, you can specify avalue for ALPHA between 0 (transparent) and 1 (opaque) for the object, depending onhow transparent you want the object to be.
5.1.6 Import Data tab
The button includes options to import from a variety of formats:
GDSIIThis file format is commonly used to store 2-dimensional geometric data. For details, see GDSII Import .
5.1.6.1 GDSII Import
The GDSII import function allows you to import structures from a GDSII file into the layouteditor. The GDSII file format is commonly used to store 2-dimensional geometric data. Thisdata can be directly imported into a 2D layout environment, or it can be used to import 3Dobjects into a 3D layout environment by extruding the 2D data in the Z dimension.
Characteristics of the GDSII file
60
Simulation objects 61
© 2003 - 2013 Lumerical Solutions, Inc
Lumerical products support most, but not all features of the GDSII file format. Unsupportedfeatures should not prevent the file from being imported, however, the results may not be asexpected. The following table details the supported and unsupported features.
Features Supported
General
Multiple cells in GDSII library file Yes
Layer numbers for drawing objects Yes
Primitives/Objects
Box/Rectangle Yes
Polygon Yes
Path (see note below) Yes
Node No
Text No
Symbolic cell reference Yes
Array cell reference Yes
Advanced
Cell references in external library/file No
Magnifications in array and symbolicreferences
Yes
Rotations and mirroring in array andsymbolic references
Yes
Note: Path cornersPath objects in GDSII files are piecewise linear lines plus a width and optionally someinformation on how to handle corners and ends. In general, GDSII files support severaltypes of corner style options (squared, rounded, extended squared, etc). Our importfunction supports type 0 (squared ends flush to the end-point) and will default to type 2
Reference Guide62
© 2003 - 2013 Lumerical Solutions, Inc
(square ends with 1/2 the width added to the end-point) for all other types.
Note: Flattened GDSII filesWhile we do include scale, rotate, flip, and automatic flattening of references, not allfeatures of GDSII are currently supported. If you run into any problems, you may havebetter results by flattening the file first.
GDSII Import
Import using GUIGDSII import is initiated by accessing the IMPORT->GDSII option from the FILE menu, orby pressing the Import GDS button located on the main toolbar. This will bring up astandard file browser, which will allow you to select a file with the extension .gds or .db.Selecting a GDSII file will bring up the Single layer GDSII Import window as shown below.
The following 3 input parameters control how the GDSII data is imported:
Cell name: This selection menu contains the valid cells available in the GDSII library.Select the cell you wish to import.Layer number: This selection menu contains all of the layer number present in the GDSIIfile. 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 currentsimulation environment. This material will be assigned to the imported structures.
Selecting the Import layer button imports all the structures with the selected layer numberin the selected cell into the layout environment. These structures are automatically inserted
Simulation objects 63
© 2003 - 2013 Lumerical Solutions, Inc
into a structure group. The material is set as an input parameter for the structure code, andthe script in the structure group sets all the objects to the desired material. The name ofthe structure group includes the original number of layers. For 3D simulations, the structuregroup 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 theproperties of the structure group.
Import using script commandThe GDSII file can also be imported via script, the command gdsimport can be used. For
more information of the script commands, please visit Reference Guide - GDSII chapter .
See AlsoUserguide - GDSII - Import and export
5.1.6.2 Surface import window
Options in the surface import window include:
After surface data has been imported, the Import data tab allows the following properties tobe modified:
IMPORT: You can import new data into the object, or clear the imported data via asimple GUI. For properties of the import GUI, see bottom of page.X,Y FINE SCALE ADJUSTMENTS: Re-scale the object X,Y span. Modifying theseproperties will change the X,Y span properties. Z SCALE property not used for surfaceimport.DATA SIZE: These properties provide some information about the imported data. Theyare read-only.LOWER, UPPER REF HEIGHT: Set the vertical location of the reference plane (height=0in the imported data). Modifying these properties will change the Z, Z span properties.
Note: Related propertiesIt is important to notice that the 'x, y scale' and 'x, y span' properties are linearly related. Doubling the object 'x span' will automatically double the 'x scale' property. Similarly, the 'lower, upper ref height' properties are related to the 'z and z span' properties,although the relationship is slightly more complex. See the following figure for details. Thesurface's can be truncated by setting the 'z span' property to a small value.
281
Reference Guide64
© 2003 - 2013 Lumerical Solutions, Inc
Note: Overlapping surfacesIf the z span is small enough such that the upper and lower surfaces overlap (as shownbelow), no structure will be included in the simulation in that region.
For additional information and example files, see the Import object surfaces page in theUser Guide section of the Online help.
Import surface GUI settings:SELECT FILE: let the user specify the data file to be imported.X0, Y0, Z0: the data origin in the global coordinates of the Graphical Layout Editor.X,Y: This defines the span of surface that you are importing.INVERT X AND Y AXIS: It is often easy to invert the x and y axis when exporting the file.Selecting this checkbox means that the x and y axes are automatically reversed.UPPER SURFACE, LOWER SURFACE: Choose which surface is being imported.FILE UNITS: Select units for the data in your file.
Simulation objects 65
© 2003 - 2013 Lumerical Solutions, Inc
5.1.7 Properties tab
The properties tab is only available for structure groups. The properties tab is used to setthe origin of the group, and to create the custom properties of the group that are the inputsof 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 throughscript commands. For more information and examples, see the Structure groups page ofthe User Guide section of the Online Help.
5.1.8 Script tab
The script tab is only available for structure groups. The script tab can contain scriptcommands that are used to set up a structure or edit the properties of structures locatedwithin the structure group. The structure group has access to the user variables defined inthe PROPERTIES tab, and can change properties of any objects that are contained in thegroup. The script does not have access to objects which are not located in the group, anddoes 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 userproperties 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 scriptcommands, see the Scripting Language section of the Reference Guide.TEST/SCRIPT OUTPUT: Press the TEST button to run the script. If there are no syntaxerrors in the script the SCRIPT OUTPUT will read <script complete>.
For more information and examples, see the Structure groups page of the User Guidesection of the Online Help.
5.2 SimulationSimulation objects are used to define simulation parameters like boundary conditions andmesh size.
Simulation regionThe simulation region defines most simulation parameters including the size and meshsize.
Mesh ConstraintThe mesh constraint region is used to override the default mesh element area in some partof the simulation region. Normally the meshing parameters are set in the Simulation
108
Reference Guide66
© 2003 - 2013 Lumerical Solutions, Inc
region. However, if some specific meshing conditions are required in part of the simulationregion, a mesh constraint region can be specified. Note that only one simulation region per simulation is supported, but multiple meshconstraint regions may be used.
TIP: Objects which lie outside the simulation region.Any simulation objects contained or partly contained within the simulation region areincluded in the simulation, while any objects which fall completely outside of thesimulation region are not included in the simulation. Those physical structures (andportions thereof) lying within the simulation region are included in the simulation (i.e. thesimulation is performed on that portion of the physical structure lying within the simulationregion). Physical monitors and sources are treated in a similar fashion, such that anyportion of a monitor or source lying within a simulation region will be used. The user iswarned when at least one source or monitor falls completely outside the simulationregion.
5.2.1 General tab
The options in the general tab depend on whether the item being edited is a simulationregion or a mesh refinement region. Simulation regionThe simulation region contains several settings:
SIMULATION TEMPERATURE (K): The temperature in Kelvin at which the simulation willbe done.SOLVER GEOMETRY: This drop down menu gives the choice of a 2D simulation planeor a 3D simulation.NORM LENGTH: The length of the device in the direction perpendicular to the plane ofthe simulation; any normalizations length will be with respect to this value.SOLVER MODE: DC mode for dc simulations and transient mode for time dependantsimulations. The color of the simulation region will change depending on which option ispicked. Also, the available options in the contacts table will change accordingly.CONTINUE FROM PREVIOUS SOLUTION: If this option is checked, the user has thechoice to specify a file that has already been run with a solution. This solution will beused as the starting point for the Newton solver. In simulations where the starting pointisn't at zero volts, this can be very useful to save time.
.
Mesh Constraint region For the mesh constraint region, the maximum element area can be set.
Simulation objects 67
© 2003 - 2013 Lumerical Solutions, Inc
5.2.2 Mesh tab
Global Mesh ConstraintsThe global mesh settings section contains several settings:
MAXIMUM EDGE LENGTH: The maximum length of an edge of a triangle (in 2D) used inthe mesh. MAXIMUM EDGE LENGTH: The minimum length of an edge of a triangle (in 2D) used inthe mesh. TRIANGLE QUALITY: The quality of mesh triangle, defined the minimum angle used inthe triangular mesh cells. The higher the angle, the higher the quality of the triangle
Auto Refinement SettingsThe auto refinement settings section contains several settings:
MAX REFINE STEPS: The automatic refinement proceeds in multiple stages, creating aquality triangulation and refining the mesh according to the change in doping density and,if present, optical generation rate. This setting limits the number of refinements at eachstage, and corresponds to the number of vertexes that can be added to the mesh at eachstage. SENSITIVITY: This setting controls the threshold at which the mesh will be refined due tothe gradient in the doping density or optical generation rate. The default value will roughlycorrespond to a limit of a factor of 2 change in the doping density or generation rate overthe span of an element in the mesh.
5.2.3 Geometry tab
The geometry tab contains options to change the size and location of the simulation ormesh refinement region.
5.2.4 Transient tab
Transient Simulation ControlsThe transient simulation controls section contains several settings:
MIN TIME STEP: The smallest time step that will be used in the transient simulation(used as the initial time step)MAX TIME STEP: The largest time step that will be used in the transient simulation.
Downsampling
DOWN SAMPLE MODE: The type of downsampling to use, None, for no downsampling,count, for specifying the number of point to downsample at, and interval to specify thedownsample step size.
Global Optical Shutter
Reference Guide68
© 2003 - 2013 Lumerical Solutions, Inc
The global optical shutter will apply a shutter to all the optical generation objects in thesimulation. SHUTTER MODE: disabled, for no shutter, step on and step off for step functions, pulse onand pulse off for a pulse with on and off times. The time shutter function will be plotted asthe option is chosen for ease of use. The on and off times can then be specified.
5.2.5 Results
This tab contains a list of all the spatial results that can be recorded throughout thesimulation. One can pick to enable or disable one or more of the results to save memory asneeded.
5.2.6 Advanced options tab
WARNING: This tab includes options which should only be changed if you are quitefamiliar with the meshing algorithm and techniques used .
DEVICE:
DEVICE:
SOLVER TYPE can be set to gummel or newton. Please see this page to learn aboutthe function of each solver type. MULTITHREADING if enabled, the user can choose to divide up and run the simulation overmultiple threadsFERMI STATISTICS if enabled, fermi statistics will be used in the solvers. Please see thispage to learn more about the details of the fermi statistics model.
The following applies to both sections on Poisson Solver Controls and Drift-Diffusion SolverControls:
USE DEFAULTS: checked by default, will use an iteration limit of 40, absolute tolerance of1e-06 volts and a maximum update value of 5 volts.ITERATION LIMIT: Takes a value between 1 and 10000. This limits the number of iterationsof the Poisson or drift-diffusion solver that may be run.ABSOLUTE TOLERANCE: For a calculation to be considered converged, this determinesthe maximum absolute change between iterations that can exist. For the Poisson solver,the step converges when
kk VV 1
where δ is the tolerance and V is the electrostatic potential. For the drift-diffusion solver,both the electron and hole quasi-Fermi levels must converge:
69
70
Simulation objects 69
© 2003 - 2013 Lumerical Solutions, Inc
kFp
kFp
kFn
kFn
EE
EE
1
1
MAXIMUM UPDATE: To help the calculation converge, the maximum change that will beapplied to estimate the solution at the next step can be clamped. This value is in multiplesof the thermal voltage (kT/q).
Initialization:INITIALIZATION: disabled by default, but can be enabled if the start bias in a voltage sweepis far from the solver's initial guess. More steps will help bring the initial guess closer to thestart value but will cause the simulation to take longer.
5.2.7 Solver type
DEVICE simultaneously solves the equations for the electrostatic potential (Poisson’sequation) and charge (drift-diffusion equations). The solutions to these equations must beself-consistent, i.e. the charge calculated from the drift-diffusion equations satisfies thePoisson equation, and vice versa. Two common approaches are used to solve this systemof equations: Gummel’s method and Newton’s method.
Gummel’s method decouples the charge problem from the electrostatic potential problemat each step. As both of these equations are non-linear, they must in turn be solved usingan iterative or direct method. First, the electrostatic potential is solved holding the chargefixed. Next, this solution to the electrostatic potential is used as a fixed input to the chargeequations, and those are updated. This process continues until the solution is self-consistent. Gummel’s method is stable and efficient for devices where the currents aresmall and the variations in the charge distribution are not too extreme (meeting the criteriathat the charge and electrostatic potential are weakly coupled problems). Gummel’smethod should not be used for transient simulations or simulations involving high levels ofcharge injection.
Newton’s method is the classic approach to solving a system of non-linear equations. Inthis method, the electrostatic potential and charge are solved for simultaneously, and allare updated at each step. Newton’s method requires a good initial guess in order that it willconverge, and can be more difficult to converge than Gummel’s method. However, Newton’smethod can handle devices where the variations in charge density are large. Newton’smethod must be used for transient simulations.
Reference Guide70
© 2003 - 2013 Lumerical Solutions, Inc
5.2.8 Fermi statistics
Electrons and holes are fermions, and therefore obey Fermi-Dirac statistics. At a finitetemperature, the energy distribution of the electrons is described by the Fermi-Diracfunction,
where k is the Boltzmann constant, T is the temperature, and Ef is the Fermi energy.When E-Ef>>kT, the Fermi-Dirac distribution can be approximated by the Boltzmanndistribution,
Often in semiconductor devices, when the net doping density is sufficiently low (non-degenerate), the Fermi energy is located within the band gap (carriers are forbidden fromhaving energies within the range of the band gap), far from the band edges. When thecondition E-Ef>>kT is satisfied (typically for |E-Ef|> 3kT), the Fermi-Dirac distribution canbe replaced with the Boltzmann distribution.
The carrier density is calculated from the integrated product of the Fermi-Dirac distribution(probability of occupancy) and the density of states (available states to occupy). Forelectrons, the equation is
When the Fermi-Dirac distribution is used, this integral does not have an analytic solution,and must be approximated numerically. However, for non-degenerate conditions, the Fermi-Dirac distribution is approximated by the Boltzmann distribution, and the precedingequation reduces to
describing the electron density at equilibrium (Nc is the effective density of states and is aconstant related to the specific properties of the semiconductor).
5.3 MonitorsThe following types of monitors are available in DEVICE:
Simulation objects 71
© 2003 - 2013 Lumerical Solutions, Inc
Charge monitorsCharge monitor records electron and hole densities in the monitor space. It can alsointegrate the total charge within the monitor surface/volume.
Electric Field monitorsElectric field monitor records the electric field within the monitor region as well as theelectrostatic potential. Using this information, it can also calculate the total charge withinthe monitor surface/volume.
5.3.1 General tab
Charge monitorMONITOR TYPE: The monitor geometry can be chosen. It can be a point, a line in anydirection, a plane normal to any of the axis or a 3D monitor.RECORD ELECTRONS/HOLES: If this option is checked, the electron/hole densities willbe recorded. These will be in units of 1/cm 3 for both n and p.TRUNCATE MESH: Since the generated mesh is triangular and the monitors arerectangular, if this option is chosen, the mesh points will be interpolated onto the monitorboundaries.INTEGRATE TOTAL CHARGE: The total number of electrons/holes will be calculatedwithin the monitor surface/volume. This will be in unitless ( total number of chargedcarriers) in 3D and in units of 1/m ( number of carriers in a meter) in 2D for both n and p.
Electric field monitorMONITOR TYPE: The monitor geometry can be chosen. It can be a point, a line in anydirection, a plane normal to any of the axis or a 3D monitor.RECORD ELECTRIC FIELD: If this option is checked the electric field across the monitoris recorded.E will be in units of volts/m.RECORD ELECTROSTATIC POTENTIAL: If this option is checked, the electrostaticpotential across the monitor is recorded. V is in units of volts.CALCULATE NET CHARGE: If this option is checked, the net charge within the monitorsurface/volume is calculated using Gauss's law by integrating the electric field fluxthrough the box surface. The results are in units of Coulombs in 3D simulations andCoulombs/m in 2D simulations.
Reference Guide72
© 2003 - 2013 Lumerical Solutions, Inc
5.3.2 Geometry tab
The geometry tab contains options to change the size and location of the monitors.
5.4 GenerationThe following types of Optical generation objects are available to be superimposed on thestructure in DEVICE:
Bulk GenerationThe bulk generation object allows the user to define a region of bulk optical generation. Theregion geometry as well as the parameters below can be specified:
ILLUMINATION FACE: The direction of illumination can be chosen by picking one of the sixsides of the cubic region.SPECTRUM: The spectrum of the illumination can be chosen. For example, solar (AM1.5G) will import the spectrum of the sun.MATERIAL: The semiconductor onto which the generation is superimposed can be chosenfrom this drop down menu.INTERFACE REFLECTION: Either an air interface or an anti reflective coating interface canbe chosen as the boundary of the generation region. In the case of the ideal anti reflectivecoating, all light will be assumed to penetrate into the semiconductor, whereas in the airinterface case, reflections from the air-semiconductor interface could take place.
A plot of the generation rate versus position will be generated on the bottom right corner ofthe edit window.
Import GenerationThe Import generation object allows the import of a user defined optical generation region.The location of the object is specified via the edit window. IMPORT NEW DATA: opens file browser to select data file. The file must be in Matlabformat (.mat) and contain fields "x", "y", "z", and "G", where "x", "y", and "z" are 1D arraysspecifying the rectilinear grid, and "G" is a 3D array (with dimensions NX x NY x NZcorresponding to the rectilinear grid) whose entries are the optical generation rate in units of
m-3s-1.
5.5 DopingThe following types of Doping objects are available to be superimposed on the structure inDEVICE:
Simulation objects 73
© 2003 - 2013 Lumerical Solutions, Inc
Constant Doping RegionThe constant doping object allows the user to define a region with constant doping. Theregion geometry as well as parameters can be entered.DOPANT TYPE: The dopant type can be n-type (donors) or p-type (acceptors).CONCENTRATION: The concentration of the dopant can be entered.
Diffusion RegionThe diffusion region object allows the user to define a region with a dopant concentrationprofile. The region geometry as well as parameters can be entered.DOPANT TYPE: The dopant type can be n-type (donors) or p-type (acceptors).SURFACE CONCENTRATION: The concentration of the dopant at the surface (the peakconcentration) can be entered.FACE: The side of the region where the surface concentration is defined (i.e. where thediffusion source originates). For example, "upper y" refers to the face defined by "y max".JUNCTION WIDTH: The width of the doping profile from surface (peak) concentration toreference concentration at the edge of the diffusion region.DIFFUSION FUNCTION: The doping concentration profile, can be gaussian or thecomplementary error function (erfc).REFERENCE CONCENTRATION: The doping concentration on the exterior of the box(excluding the originating face).
Import Doping RegionThe Import doping object allows the import of a user defined spatial doping profile. Thelocation of the object is specified via the edit window. IMPORT NEW DATA: opens file browser to select data file. The file must be in Matlabformat (.mat) and contain fields "x", "y", "z", and "N", where "x", "y", and "z" are 1D arraysspecifying the rectilinear grid, and "N" is a 3D array (with dimensions NX x NY x NZcorresponding to the rectilinear grid) whose entries are the doping concentrations in units of
cm-3.DOPANT TYPE: The dopant type can be n-type (donors) or p-type (acceptors).
Reference Guide74
© 2003 - 2013 Lumerical Solutions, Inc
5.6 ContactsThe Contacts table allows the user to define electrical contacts in the simulation region andassign a bias to them.
The add/delete/edit buttons can be used to add a new contact, delete a contact or edit theproperties of a contact respectively. The name of the contact can be typed in the Name column, the geometry of the contactcan be picked from a drop down menu from the choices available according to thesimulation objects. The contact can be set to Ohmic, Schottky or None.
SOLVER MODE: The mode of the solver is consistent with the mode picked in thesimulation region and can be set to dc to transient.
DC MODE:
In the DC mode, the bias assigned to each contact can either be fixed at a value or sweptover a range of DC values. In the sweep case, the start and stop biases as well as intervaland the number of points in the sweep can be specified. Alternatively, the user canmanually enter a range of values for the voltage to sweep over. Series and shunt resistorscan also be added to the voltage source to model more complicated circuits.
Simulation objects 75
© 2003 - 2013 Lumerical Solutions, Inc
TRANSIENT MODE:
In the transient mode, the bias assigned to each contact can either be fixed at a value( this is the same as the fixed bias in DC mode) or transient, swept over a range of timedependant values. In the transient case, the values for each voltage point as well as thetime point can be entered in a table. Series and shunt resistors and capacitors can also beadded to the voltage source to model more complicated circuits. The resistance andcapacitance for these elements can also be specified as a function of time. If only one pointis specified in the table, then a constant value is assumed for that element. The values forthe voltage Rs and Cs will be linearly interpolated in time for consistency.
Reference Guide76
© 2003 - 2013 Lumerical Solutions, Inc
5.7 Equation interpreterThe fields for numeric parameters can be used as a simple calculator. For instance, if youwish to set a value to the square root of 3 divided by e, just enter sqrt(3)/exp(1) into thefield. The expression will be automatically evaluated when you press Enter or click on adifferent field. Equations which become undefined (i.e. 1/0) should be avoided.
The following table provides a list of available operators and constants.
Category Syntax
Algebraic operators +, -, *, /
Trigonometric operators sin, cos, tan, asin, acos, atan, atan2,sinh, cosh, tanh
Power operators or **, exp, log10, log, sqrt
Logical operators >, <, >=, <=, ==, !=
Other operators abs, mod
Constants c - Speed of light in m/spi - The value of Pi
Examples2 10sqrt(3)/exp(1)sin(45*pi/180)
Running simulations and analysis 77
© 2003 - 2013 Lumerical Solutions, Inc
6 Running simulations and analysis
This section describes the general operations of running a simulation and performing ananalysis. Information on how to set up optimization and parameter sweep projects is alsodescribed here. The contents are organization into the following chapters. For moreinformation on datasets, see Introduction to datasets in the Scripting chapter.
Resource ManagerRunning a simulationAnalysis toolsVisualizerResults ViewOptimization and parameter sweeps
6.1 Resource ManagerBefore running any simulations, the computing resources must be configured. This is donethrough the resource manager. It can be easily accessed by pressing the resources button
in the main toolbar. These settings are saved on a per user basis. For moreinformation, see the Parallel computing video.
In DEVICE, the "Processes" field is disabled since distributed simulations are notpermitted.
Resource Configuration
141
77
80
81
83
93
97
Reference Guide78
© 2003 - 2013 Lumerical Solutions, Inc
USERS WITH A SINGLE LICENSEResourcesThis section allows the number of processes for localhost to be changed as well as thename. For advanced configuration options, see Resources Advanced Options .
Configuration testRun tests to make sure MPI username and password are set correctly. It also performsother checks such as engine path verification. If the tests pass, then we can be sure thatthe current simulation will run.
USERS WITH EXTRA ENGINE LICENSESResourcesIf you have extra engine licenses and Lumerical software installed on other computers onthe network, they can be added as additional computation resources to perform multiplesimulations in parallel. This is especially useful for parameter sweeps and optimizationprojects where many iterations need to be performed. The resources can easily be turnedon and off depending on whether they are free to compute at the time.
Requirements of each additional resource:Must be the same operating system as localhostMust be the same system type as localhost (cannot mix 32-bit with 64-bit)Must have the same version of Lumerical software as localhostMust have the same version of MPI as localhostMust have a user account with the same login and password as localhostMust have access to the simulation files via a network drive
To add a new resource:1. Click the add button.2. Set 'active' if you plan to use the resource right away or 'inactive' if you plan to enable it
later3. Set a name for that resource4. Specify the IP address of the hostname that the computer uses on the network5. Set the number of cores that you would like it to use6. Set any advanced options.
If many resources have advanced options that need to be changed, the 'Duplicate' buttonwill be useful.
Configuration testThis section of the window is used to test the communication to the additional resources. It runs a series of tests and will report any warnings or errors that may prevent a distributedsimulation from running such as mismatched software versions, user credentials orcommunication problems.
79
Running simulations and analysis 79
© 2003 - 2013 Lumerical Solutions, Inc
6.1.1 Resources Advanced Options
Advanced OptionsEach resource canhave customizedsettings if required.
Resource advanced options
MPICH OPTIONSJOB LAUNCHING: Whether or not to tell mpiexec to spawn processes in local session orvia remote job launcher. The default setting is "Bypass mpich daemon on localhost", whichwill add the –localonly command line option and skip the –host command line options (onlyif the host name is localhost). The setting "Standard", adds the argument -host <IP/Hostname>. The last setting "Bypass mpich on localhost" will exclude mpich entirely. USE PROCESSOR BINDING: Tells mpiexec to specify which CPU each process will runon, when mpiexec supports it. On Windows, it adds the –binding option with the valuecomputed through the lumnuma class. This option is not supported on Linux and Mac. Customers interested in this functionality on Linux and Mac should consider using numactl.EXTRA MPIEXEC OPTIONS: Allows the user to specify advanced options to mpiexec. Ifset, the specified mpiexec path is used instead of the default mpiexec co-packaged withthe software.SUPPRESS ANY DEFAULT MPIEXEC OPTIONS: removes the default arguments in thempiexec commandSET MPIEXEC ENGINE PATH: Allows the user to specify the path to their mpi executable.
PRODUCT OPTIONSCREATE LOG FOR ALL PROCESSES: Each parallel process will create a log file. Adds
Reference Guide80
© 2003 - 2013 Lumerical Solutions, Inc
the –logall command line option.EXTRA COMMAND LINE OPTIONS: Allows the user to specify advanced options toengine. Appends the text immediately after the engine command.SET ENGINE PATH: Allows the user to specify path to product engine. If set, the specifiedpath is used instead of the default path which is relative to the executable binary.
The bottom window displays the final command which will be used to run the simulation.
6.2 Running a simulation
When the simulation setup is complete and the resource setup passes the configuration
tests, it is time to run the simulation. Clicking on the RUN button in the toolbar willlaunch the job monitor window with the simulation already running. If you have not alreadysaved your simulation, you will be prompted to do so. The simulation project file must besaved in order to run after which the data can then be analyzed.
The job monitor window allows you to see the status of your jobs, as well as allowing youto pause or quit the jobs. Errors that occur during the simulations are displayed here.
Job Manager
The elements of the job monitor window are as follows:ENGINE: Shows which computational resource is being used. The name is specified bythe user.STATUS: Shows the state of the job. e.g. running, paused, finishedPROJECT FILE: Shows the location of the file that is being simulated.
MESHING STATUS: Indicates the status of the meshing process; If the mesh hasalready been calculated, the status will be "Loaded". If not, the status will calculate themesh starting with "Applying global constraints", then "Refining mesh by doping", andthen "Finished". BIAS POINT: Shows the bias point step as the simulation loops through all the specifiedcontact bias values. For example 2/25 implies that the simulation is currently running forthe second bias point out of 25 specified points.PROGRESS: Shows the percentage of the time taken so far as compared to the
Running simulations and analysis 81
© 2003 - 2013 Lumerical Solutions, Inc
maximum time remaining.QUIT & SAVE: Stops the simulations and saves the data obtained up to that point. Theprogram will be in Analysis mode.QUIT & DON'T SAVE: Stops the simulations and does not save any data. The programwill be in Layout mode.FORCE QUIT: Closes the job monitor window and forcefully terminates all simulations.This option should ONLY be used when the other Quit options don't work properly. When simulations are stopped with Force Quit, they may not check-in their license,which means you may have to wait several minutes before another simulation can be run. No simulation data will be saved.TOTAL PROGRESS BAR: The progress bar indicates how much of ALL the simulationsare complete, with the length of the progress bar is determined by the sum of the“maximum simulation times”.
To access actions for each job, right-clicking anywhere on the row will bring up a contextmenu with the following options:
PAUSE: the engine is signaled to go into a wait mode (it will stay running, but notconsume CPU)CONTINUE: restarts a paused jobQUIT AND SAVE: The engine will stop the current simulation job and attempt to save thedata created so far. QUIT AND DON'T SAVE: The engine will stop the current simulation job and does notsave any data.FORCE QUIT: Forcefully terminates the current simulation job and does not save anydata. This options should ONLY be used when other Quit options don't work properly.When simulations are stopped with Force Quit, they may not check-in their license,which means you may have to wait several minutes before another simulation can berun. VIEW JOB DETAILS: Opens up a modal dialog that contains the standard outputmessages from the engine processes.
Note: More informationFor more information about running Lumerical simulations, including running on clusters,using a job scheduler, preparing batch files, and using extra engine licenses, see theOnline Help section User Guide - Running Simulations.
6.3 Analysis toolsThis section describes the way in which the integrated analysis routines are used tovisualize and analyze simulation data. The manner in which the analysis routine interactswith the overall simulation environment is described in the next section: Analysis tools and the simulation environment . This is followed by sections tofamiliarize the user with the operation of the analysis routines.
82
Reference Guide82
© 2003 - 2013 Lumerical Solutions, Inc
In the first section, the two general ways in which data can be visualized and analyzed isdetailed. The plotting functions, a central component to the overall analysis routines, aredescribed in Figure windows section. The section entitled Data export describesdata can be exported to plot in other software packages for further analysis or formalpresentation. More advanced analysis can be performed with the extensive scriptinglanguage, as described in the Scripting language section. Finally, visualization of theresults and data using the Visualizer feature is explained.
6.3.1 Analysis tools and the simulation environment
Before describing how the analysis routines are used for data visualization, it is importantto understand the way in which the integrated analysis tool interacts with the simulationenvironment. Following the completion of a simulation, the simulation data is written intothe simulation project file; even premature termination of a simulation results in a partialdataset being written to the file. When the simulation completes and the EXIT button ispressed, or the simulation is prematurely terminated by pressing the EXIT button, theproject file will be in Analysis mode, meaning that any modification of the data will requireswitching back to the layout mode.
In Analysis mode, simulation object properties can be viewed, but not edited. This ensuresthat at any given time, the simulation data results corresponds to the configuration of thesimulation project. Once in the analysis tool, the user continues to analyze the simulationdata until they either wish to close the application, or they decide they would like to alterthe simulation objects and re-perform the simulation. By exiting the analysis routines andreturning to the layout editor, existing simulation data will be erased.
6.3.2 Figure windows for plots and images
Simulation results can be visualized using 1D line, 2D surface and 3D vector field plots. These plots can be created from within the results visualizer, or from the scriptinglanguage.
The figure window controls are slightly different for each type of plot. For example, only the3D vector plot provides controls for 3D rotation of the view. All plots support operation suchas axis labels, zoom, export to JPG, etc.
82 83
108
83
Running simulations and analysis 83
© 2003 - 2013 Lumerical Solutions, Inc
6.3.3 Data export
In some cases, the user may wish to export the simulation data to take advantage of theadvanced plotting and data analysis tools not available in Lumerical's products. Data exportcan be done in a number of ways, but in general the use of the scripting language will berequired. The write script command can be used export data to a text file, or thematlabsave command can be used to save data to .mat files. Results stored in
datasets can also be export to Paraview (for sophisticated data visualization) with the vtksave command.
6.3.4 Visualizer
The Visualizer is a tool for analyzing data. Simulation data from a variety of objects(monitors, parameter sweeps... etc) can be sent to a Visualizer.
Data that gets added to the Visualizer is retained until it is removed (ie. with the "Remove"button or by pressing "X" on the top right corner of the window). This is useful forcomparing results across different data sets. The upper-left portion of the window is theplot area, which displays the current data defined by the settings in the upper-right of thewindow (plot settings). The following sections describe the many options available forcontrolling what data will be displayed in the plot area. These sections can be minimized ifmore area for plotting is required.Visualizer controlsVisualizer attributesVisualizer parameters
123
124
128
85
91
92
Reference Guide84
© 2003 - 2013 Lumerical Solutions, Inc
Visualizer
The surface plot option is also used to plot a number of 3D results. The plot will contain a3D outline of the structure and the results are shown on a planar cross section of thatoutline. To change the plane position and/or orientation, move the arrow perpendicular tothe plane, grabbing it with a mouse left click much like a drag action.
Running simulations and analysis 85
© 2003 - 2013 Lumerical Solutions, Inc
See the Visualizer video in the online User Guide for additional information on the visualizer.
6.3.4.1 Visualizer controls
The settings control the overall typeof plot and the labels applied to it.
Plot type: select Line, Surface orVector plotManual plot: Disable auto-refresh.Useful when visualizing largedatasets.Export to: export figure to JPEG,text file or clipboardView options: show/hide Attribute &Parameter panes
Line plot: Choose this option to plota 1D vector versus another 1Dvector. For matrices with more than1 dimension, a slice of the matrixwill be automatically chosen. Youcan use the parameters table on thebottom to choose which dimensionto slice and which to plot on the x ory axis.
Reference Guide86
© 2003 - 2013 Lumerical Solutions, Inc
Surface plot: Choose this option tocreate a 2D image plot of monitordata. For matrices with more than 2dimensions, slices of the matrix willautomatically be chosen. you canuse the parameters table on thebottom to choose which dimensionsto slice and which to plot on the x ory axis.
Vector plot: Choose this option tocreate a 2D/3D vector plot of monitordata. Choose the parameters tableto slice a frequency point. It ispossible to create a vector plot ofquantities such as the electric field,magnetic field, poynting vector, etc.
TIP: It is often more meaningful toplot the poynting vector rather thanthe fields. Plots of the electric fieldwill often contain vectors pointing indifferent directions representing theoscillation in the field direction. Themore interesting quantity to plot isthe poynting vector where thedirection of power flow can bevisualized.
TIP: It can be helpful to create anelectric field vector plot to studycircularly polarized or ellipticallypolarized beams. See the exampleon our knowledgebase.
The plot settings can be further edited by click on the pencil icon on the top left corner of
the plot window .
Running simulations and analysis 87
© 2003 - 2013 Lumerical Solutions, Inc
For line plots, the followingare available:
TITLE: The title of the plot canbe specifiedX/Y LABEL: The x and ylabels for the plot can bespecifiedSET AXIS LIMITS: The x andy limits for the axis can besetEDIT LEGENDS: The legendsfor the plots can be specifiedNUMBER OF TICKS: Thenumber of axis dividers on thex and y axis can be specified.The default is 10.
One can also choose toshow/hide the title andlegends, draw the x and yaxis at (0,0), plot multiplefigures using the same color,plot the x and/or y axis on alog scale, show/hide grids forthe axis and choose to showthe plots in grey scale.
Reference Guide88
© 2003 - 2013 Lumerical Solutions, Inc
For surface plots, thefollowing are available in 2Dsimulations:
PLOT TYPE: Can be a 2Dimage plot or a 3D surfaceplot. In the 2D image plot, thevalues are indicated using thecolor bar. In the surface plot,the values are also plotted inthe third dimension.
SHOW: Can be "surface"which will contain the valuesat each mesh point only, or"surface and mesh" which willsuperimpose in black, themesh grids on top of theplots, or "mesh only" whichwill only plot the mesh grid incolor.
AXIS SCALE OPTIONS: Canbe "square" which will makesure the two axis are plottedto the same size, or "equal"which will use the same scalefor both such that the plot willbe to scale.
LOG SCALE: Will plot theresult on a log scale.LABELS: the x/y/z labels canbe specified.COLOR BAR: The color barlimits can be specified.
Running simulations and analysis 89
© 2003 - 2013 Lumerical Solutions, Inc
For surface plots, thefollowing are available in 3Dsimulations:
SHOW: Can be "surface"which will contain the valuesat each mesh point only, or"surface and mesh" which willsuperimpose in black, themesh grids on top of theplots, or "mesh only" whichwill only plot the mesh grid incolor.
AXIS SCALE OPTIONS: Canbe "square" which will makesure the two axis are plottedto the same size, or "equal"which will use the same scalefor both such that the plot willbe to scale.
LOG SCALE: Will plot theresult on a log scale.LABELS: the x/y/z labels canbe specified.COLOR BAR: The color barlimits can be specified.
CLIP PLANE: The clip planecan be shown on top of a 3Dsurface plot. This plane can
Reference Guide90
© 2003 - 2013 Lumerical Solutions, Inc
be defined by defining 2 (x,y,z) vectors one of which is thenormal to the plane. Forconvenience, there are alsothe quick options of choose ax normal/y normal /z normalplane. This plane will be ableto cut through the the 3Dstructure and give insight intothe inside of the 3D plot. Theinside out option will flipwhich side of the plane isshown.
Running simulations and analysis 91
© 2003 - 2013 Lumerical Solutions, Inc
6.3.4.2 Visualizer attributes
An attribute is a quantity to plot (ie. Power transmission vs frequency). Multiple attributescan be sent to a single visualizer. When using line plots, each attribute will appear as aseparate line. When using image and vector plots, the selected attribute will be shown.
DATA SET: full data set name (can contain multiple attributes)ATTRIBUTE: attribute nameVECTOR OPERATION: selects a particular component of a vector attribute e.g. (Ex, Ey, |E| 2)SCALAR OPERATION: selects a particular component of a scalar attribute e.g. (real,imag, abs, angle)
Reference Guide92
© 2003 - 2013 Lumerical Solutions, Inc
SCALE: multiplier for the data being plottedLEGEND: this name will be shown in the legend of the plotNOTES: additional information added by the user about the attributeVIEW DATA: allows users to view the data in a table format as shown below
In this table format, users can select any portion of the data and "Copy" or "Export" it into atext file. Alternatively, users can also send any portion of the data into the ScriptWorkspace .
6.3.4.3 Visualizer parameters
In addition to the attributes, data sets also contain the associated position vectors (eg:position, frequency).
95
Running simulations and analysis 93
© 2003 - 2013 Lumerical Solutions, Inc
ATTRIBUTES: Name of the associated attributePARAMETERS: Name of the parameterACTION: Control how the parameter is treated in the plot. For example, select which axisto plot the parameter on.VALUE: displays the value if it is a singular value or is blank if there is a vector of values
Plotting multi-dimensional attributesLine plotsOne parameter must be selected to plot on the X axis. All other non-singleton parametersmust be set to Slice. A specific slice can then be selected for those parameters.
Surface plotsTwo parameters must be selected to plot on the X and Y axis. All other non-singletonparameters must be set to Slice. A specific slice can then be selected for thoseparameters.
Vector plotsThe spatial dimensions (x,y,z) are always selected to plot on the X, Y, Z axes. All non-spatial parameters must be set to Slice. A specific slice can then be selected for thoseparameters.
6.3.5 Results Manager
The Results Manager is a tool for analyzing simulation data. The Results View windowshows all the results for the simulation object that is currently selected in the Object Tree.The Script Workspace and Script Favorites windows work in conjunction with thescripting environment to provide additional GUI-based functionalities.
When used in conjunction with the Visualizer , the Results Manager provides a veryuseful and intuitive way of analyzing and visualizing variables and results through the GUI.
6.3.5.1 Results View
The Results View window shows all the results for the simulation object that is currentlyselected in the Object Tree. Any simulation object that have results will be displayed witha symbol on the bottom-right corner. The name of the available results, and thecorresponding dimensions or are displayed. One can right click on any of the results todisplay them in the Visualizer , or to send the to the Script Workspace for furtherpost-processing.
93
95
83
93
83 95
Reference Guide94
© 2003 - 2013 Lumerical Solutions, Inc
With the use of datasets, allowing one to package raw data into meaningful results that canbe easily parameterized and visualized. The results for all the standard monitors can beretrieved in the original raw, un-parameterized matrix form (using getdata), or in datasetform (using getresult). For example, in the Results View figure above, the results listedunder “rawdata” can be obtained using the “getdata” command. The results listed under"results" are datasets, and can be obtained using the “getresult” command (thesecalculations will only be carried out when they are visualized). The icons associated witheach result reflect the type of result:
Matrix: this is a simple matrix result, with no associated parameters
Matrix dataset: this is a parameterized matrix results that contains at least anattribute (result), and a associated parameter
Rectilinear dataset: this is a parameterized matrix result that is associated with arectilinear grid
Unstructured data: This is a set of data that is not structured in form of a dataset ora matrix and rather consists of several different types of results
String
For more detail on how to work with datasets in the scripting environment, please see Accessing simulation data in the User Guide. Analysis group objects from the Objectlibrary have been updated to return datasets. For an example of how to define dataset
Running simulations and analysis 95
© 2003 - 2013 Lumerical Solutions, Inc
results in an analysis group, please see Using analysis groups.
The raw data results are all un-parameterized, simple matrix results. To createparameterized matrix datasets from matrices, use the "Send to script" option to copy thevariable into the Script Workspace, and follow the instructions here .
6.3.5.2 Script Workspace and Script Favorites
The Script Workspace shows all the variables in the current scripting environment. Thevariables' current values as well as the corresponding dimensions are shown in a listformat. Users can use the Visualizer to visualize any variable listed in the ScriptWorkspace by right-clicking on the variable and selecting "Visualize".
The icons in the script workspace above shows that while "sigmaabs" and "sigmascat" areparameterized matrix datasets (since they were the results returned directly by the crosssection analysis groups), "sigmaext" is a result that we defined in the script, and istherefore a simple un-parameterized matrix. For example, simply right-clicking onsigmaext and selecting "Visualize" will generate the following plot in the Visualizer:
95
83
Reference Guide96
© 2003 - 2013 Lumerical Solutions, Inc
Here, the extinction cross section is plotted as a function of the index value. To associate itwith the corresponding frequency array, select the "Create visualization" option, which willopen the "Visualization Creator" dialog window:
This window allows users to set the name of the parameterized variable (sigmaext_vs_f)and its parameters (f). Once this is defined, the visualization creator will generate thecommands necessary for creating the parameterized dataset in the Script Favoriteswindow. When this command is ran, it will send the new parameterized variable to theVisualizer, which will plot the variable as a function of the user specified parameter.
Generated Command Generated Figure
Running simulations and analysis 97
© 2003 - 2013 Lumerical Solutions, Inc
In addition to the commands generated by the visualization creator, the Script Favoriteswindow also allows users to define their own favorite commands by selecting "Newcommand" and "Edit".
6.4 Optimization and parameter sweepsThis section describes the way in which the optimization and parameter sweeping projectsare set up. This feature allows users to automate the process of finding desirableparameter values by running a large number of simulations. For additional information, seethe Optimization and sweeps video. An example Optimization and Sweeps tab is shown in the screenshot below:
At the top of the window is a toolbar containing the following buttons:
Creates a parameter sweeping task.
Reference Guide98
© 2003 - 2013 Lumerical Solutions, Inc
Creates an optimization task.
Creates a yield analysis task.
Opens an edit window for the selected project where one can modify its properties.
Deletes the selected project.
Runs the selected sweep or optimization with the resources currently set in theresource manager.
The Animate function allows you to view the structures that will be simulated in a parametersweep or optimization in the CAD before you run the project:
Running simulations and analysis 99
© 2003 - 2013 Lumerical Solutions, Inc
6.4.1 Optimization
An example Edit Optimization window is shown in the screen shot below:
The optimization project allows users to use built-in algorithms as well as define their ownoptimization algorithms. For examples on how to set up and run an optimization project,please see Optimize a design. As can be seen from the screenshot above, there is a SETUP tab as well as anADVANCED tab.
Setup Tab
There are three sections in the setup tab:
OPTIMIZATION CONFIGURATION:This section contains the choice of algorithm as well as all the input parameters that areneeded to set up an optimization project using a built-in algorithm:ALGORITHM: The optimization algorithm used for this project
PARTICLE SWARM: The built-in particle swarm algorithm (see Particle SwarmOptimization for more details on the algorithm).
USER DEFINED: The user-defined algorithm specified in the ADVANCED TAB.TYPE: Choice of maximizing or minimizing the figure of meritMAXIMUM GENERATIONS: The maximum number of generations for this optimizationproject.GENERATION SIZE: The generation size (number of child per generation) for this
101
Reference Guide100
© 2003 - 2013 Lumerical Solutions, Inc
optimization project.RESET RANDOM GENERATOR: If this option is selected, the random number seed to thesame value before starting the optimization. Otherwise a new initial condition is chosenevery time this optimization project is run. TOLERANCE: The convergence criteria for the optimization to terminate. If set to 0, theoptimization will run until the maximum number of generations has been reached.
PARAMETERS:This section contains the optimization parameters and the range of values used for thisproject. One can ADD/REMOVE parameters via the buttons on the right. The parameterscan be chosen from the simulation model by double-clicking on the selected parameterfield. The types, min/max values and units of the selected parameters can also be set in asimilar fashion.
FIGURE OF MERIT:This section contains the figure(s) of merit (FOM) used for this project. One can ADD/REMOVE FOMs via the respective buttons. FOMs are typically defined as output variablesof monitors or analysis groups, which can be selected from the simulation model bydouble-clicking on the selected FOM field. Once the FOMs have been defined, one canselect the FOM to be used in this project by clicking SELECT TO OPTIMIZE (note that allother FOMs will be ignored in this optimization).
Advanced Tab
The ADVANCED tab is shown in the screen shot below:
Running simulations and analysis 101
© 2003 - 2013 Lumerical Solutions, Inc
This tab allows users to define their own optimization algorithm, and is only editable if theUSER DEFINED option is selected in the SETUP tab. The Advanced tab is divided intotwo sub-tabs:
USER DEFINED ALGORITHM:This tab contains the scripts which define the customized optimization algorithm (byspecifying the first and next generation scripts). The SCRIPT OUTPUT shows the output of a test which runs the user defined algorithm with ananalytical function. If there are no syntax errors in the script, you will see the line <scriptcomplete> in the script output, otherwise the location of the error will be given. This test isconducted every time the TEST button is pressed, and a window showing the OptimizationStatus is displayed. FIGURE OF MERIT SCRIPT:This tab contains the script which defines the custom FOM. To enable this window, selectthe USER FIGURE OF MERIT SCRIPT checkbox. The only variables that can be used inthis script are the ones that are defined in the FOM section of the SETUP tab. For anexample that uses a user-defined optimization algorithm, see User Guide.
6.4.2 Particle Swarm Optimization
Particle Swarm Optimization (PSO) is a population based stochastic optimizationtechnique, inspired by the social behavior of flocks of birds or schools of fish [1,2], and haswidely been used for various kinds of design optimization problems [2] includingnanophotonic design [3-7]. In PSO, the potential solutions, called particles, are initializedat random positions, and then move within the parameter search space. The particles aresubject to three forces as they move:1. Spring force towards the personal best position, p, ever achieved by that individual
particle2. Spring force towards the global best position, g, ever achieved by any particle.3. A frictional force, proportional to the velocity.
The algorithm then follows these steps1. Set the number of particles N and initialize the positions x 2. Evaluate figures of merit (FOM) and find p and g 3. Calculate the new velocities v for each particle based on the forces applied to the
particle
1112211111 1 ttttttt vxgcxpcvv (1)
4. Update the positions x of each particle based on the velocity
ttt vxx 1 (2)
5. Repeat from step 2 until convergence is achieved
Reference Guide102
© 2003 - 2013 Lumerical Solutions, Inc
In Eq. (1), t is the iteration counter; c1 and c
2 are the cognitive and social factors,
respectively; ω is called the inertial weight; and η1 and η
2 are random number between 0
and 1. Lumerical's PSO implementation uses default values of c1, c
2 and ω that have
shown to converge well in many test optimization problems for photonic design problems. Adetailed description of the algorithm and the difference coefficients can be found in Refs. [1]or [2].J. Robinson and Y. Rahmat-Samii, "Particle swarm optimization in Electromagnetics,"IEEE Trans. Antennas and Propagat. 52, pp.397 - 407 (2004).1. K. E. Parsopoulo and M N. Vrahatis, Particle swarm optimization and intelligence :
advances and applications, Information Science Reference, 2010.2. J. Pond and M. Kawano, “Virtual prototyping and optimization of novel solar cell
designs”, Proc. SPIE 7750, 775028 (2010), DOI:10.1117/12.8731143. M. Kawano and J. Pond, "Design Optimization of Photonic Crystal Organic Solar Cells
using the FDTD method in Combination with Particle Swarm Optimization," 7thInternational Conference on Optics-photonics Design & Fabrication, Yokohama, Japan,19S1-14, 2010.
4. J. G. Mutitu, S. Shi, C. Chen, T. Creazzo, A. Barnett, C. Honsberg and D. W. Prather,"Thin film silicon solar cell design based on photonic crystal and diffractive gratingstructures", Opt. Express 16, 5238, 2008
5. M.Shokooh-Saremi and R. Magnusson, "Leaky-mode resonant reflectors with extremebandwidths," Opt. Lett. 35, 1121, 2010.
6. R. Magnusson, M. Shokooh-Saremi,and E. G. Johnson, “Guided-mode resonant waveplates,” Opt. Lett. 35, 2472, 2010.
Running simulations and analysis 103
© 2003 - 2013 Lumerical Solutions, Inc
6.4.3 Parameter Sweeps
An example Edit Parameter Sweep window is shown in the screen shot below:
For examples on how to set up and run a parameter sweep project, please see Run aparameter sweep.
There are two sections in the Edit Parameter Sweep window:
PARAMETERS:This section contains all the input parameters that are needed to set up a parameter sweepproject. There are two ways to specify the inputs to the parameter sweep. If RANGES isselected, the table above is shown. One can ADD/REMOVE parameters via the respectivebutton on the right. The parameters can be chosen from the simulation model by double-clicking on the selected parameter field, and the types, min/max values and units of theselected parameters can be set in a similar fashion. If VALUES is selected, the followingtable is shown:
Reference Guide104
© 2003 - 2013 Lumerical Solutions, Inc
The behaviour is similar to the description for the RANGES option above, except here everyvalue of the parameter is shown explicitly and can be edited one-by-one. Pressing the SETIN MODEL button automatically sets the parameters in the simulation model to have thesame value as the selected one.
NOTE: If two or more parameters are specified, they must have the same dimensions. Each sweep step will update all parameters values one column at a time (ie. this is not thesame as nested parameter sweeps). For information on how to set up nested parametersweeps, please see Nested Sweeps .
RESULTS:This section contains all the outputs from the parameter sweep.
6.4.4 Nested Sweeps
It is alsopossibleto usenestedparametersweeping. To add,simplyright clickon thecurrentoptimization orsweepandselect"Insert
104
Running simulations and analysis 105
© 2003 - 2013 Lumerical Solutions, Inc
parameter sweep".Examples can befound inthe UserGuide aswell as intheapplicationexamples.
6.4.5 Yield Analysis
An example Edit Yield Analysis window is shown in the screenshot below:
For a tutorial on how to set up and run a yield analysis task, see Run a Yield Analysis.
There are three sections in this edit window:
CONFIGURATION:
Reference Guide106
© 2003 - 2013 Lumerical Solutions, Inc
This section allows users to set the number of trials to use.NUMBER OF TRIALS: The number of trials to run.
PROPERTIES:This section allows the user to set the analysis parameters and the distributions. You canADD/REMOVE parameters via the buttons on the right. The parameters can then bechosen from the simulation model by double-clicking on the selected Parameter field. TheEdit Distribution window can be opened by double-clicking on the selected Descriptionfield.
Edit Distribution window:DISTRIBUTION TYPE:The following distributionsare available: Uniform,Gaussian, Lognormal,Truncated Gaussian,Truncated Lognormal,Discrete (uniform distributionwhere variables can onlytake discrete valuesspecified by the STEP).MEAN: Mean value of thedistribution for Gaussian,Lognormal, TruncatedGaussian, and TruncatedLognormal distributions.STD DEVIATION: Standarddeviation of the distributionfor Gaussian, Lognormal,Truncated Gaussian, andTruncated Lognormaldistributions.MIN: Minimum value or cut-off value for Uniform,Truncated Gaussian,Truncated Lognormal, andDiscrete distributions.MAX: Minimum value or cut-off value for Uniform,Truncated Gaussian,Truncated Lognormal, andDiscrete distributions.STEP: The discrete step
Running simulations and analysis 107
© 2003 - 2013 Lumerical Solutions, Inc
size of allowed values for Discrete distribution.SEED: The seed value usedto generate parametervalues. The seed used caneither be an automaticallygenerated random seed, orthe user can specify a valuefor the seed so that thesame results can beachieved each time the yieldanalysis is run.
RESULTS:This section contains the outputs of the yield analysis. Similarly to the parameters, userscan ADD/REMOVE results via the buttons on the right. The results can then be chosenfrom the simulation model by double-clicking on the selected result field.
The user can specify whether they want the yield analysis estimate for the result to bebased on the user specified min and max values. If "yes" is selected in the Estimationfield, the trial will be considered a pass if the result falls into this range. If there is morethan one result with a yield estimate, the final yield percentage will be the percent of trialswhere all of the results fall within the specified ranges.
Reference Guide108
© 2003 - 2013 Lumerical Solutions, Inc
7 Scripting Language
Lumerical provides a powerful scripting language to manipulate simulation objects, launchsimulations and analyze results. Script commands can be entered directly into the scriptprompt, be run from a saved script file (.lsf), or entered into structure and analysis objects.
This section of the Reference Guide contains the syntax for each script command.
In addition to this chapter, the Scripting section of the online User Guide provides anintroduction to the scripting language, including examples that show how to export data toother file formats and tips for plotting in MATLAB.
The script functions have been organized into the following sections. You can also viewthe alphabetical list of commands, or watch a recorded video.
Section
System
Manipulating variables
Operators
Functions
Loop and conditional statements
Plotting commands
Adding Objects
Manipulating objects
Running simulations
Measurement and optimization data
Material database functions
GDSII
User defined GUIs
Creating your own script commands
The online version of this chapter includes examples for many commands.
109
130
148
157
196
197
205
223
265
267
276
281
288
293
Scripting Language 109
© 2003 - 2013 Lumerical Solutions, Inc
7.1 SystemSystem commands for interacting with the OS file system, running script files, etc.
System commands
Command Description
newproject Creates a new layout environment.
newmode Creates a new MODE layout environment.
new Creates a new simulation project file.
save Saves an fsp file or lms file.
load Loads an fsp file or lms file.
delrm
Deletes a file.
ls dir
Lists the files in a directory.
cd Changes the working directory.
pwd Returns the current working directory.
cp Copy a file.
mv Move a file.
exit Exit the application.
system Run command prompts.
fileexists Check if a file exists.
currentfilename Get the current filename.
filebasename Get the file base name from a string.
filedirectory Get the file directory from a string.
fileextension Get the file extension from a string.
copytoclipboard Copy to system clipboard.
pastefromclipboard Paste from system clipboard.
hide Hides the GUI.
show Shows the GUI.
clearlogwindow Clears output log window.
112
112
113
113
113
114
114
114
115
115
115
116
116
116
117
117
117
118
118
127
128
Reference Guide110
© 2003 - 2013 Lumerical Solutions, Inc
version Returns the current version of the application.
versionfile Returns the current version of the file loaded by theapplication.
List of script commands
Command Description
getcommands Returns a list of available script commands.
Starting and stopping scripts
Command Description
running a script Type the script name to run it.
getpath Get the current path.
addpath Add a directory to the path.
which Where in the path is a file.
pause Pauses program for a time.
break Will stop a script file from executing at that line.
ESCAPE key To interrupt a script file from running or a long blockof commands from executing
File input and output
Command Description
format Set the precision of the script interpreter.
STD OUT
write Writes strings to text files or to standard output.
LDF files
loaddata Load variables or d-card data from ldf file.
savedata Save variables to ldf file.
savedcard Saves d-card data to an ldf file.
Text files
readdata Read text files.
118
118
119
119
119
120
120
120
121
123
121
121
122
122
Scripting Language 111
© 2003 - 2013 Lumerical Solutions, Inc
write Writes strings to text files or to standard output.
fld (field) files
asapexport Export monitor data to fld file.
asapload Load data from fld file.
asapimport Import data from fld file to Import source.
VTK files
vtksave Save in .vtk format
Touchstone files
touchstoneload Loads passive network data from a file containingTouchstone file formatted s-parameters.
Lookup tables
lookupclose Closes a file previously created with a lookupopencommand.
lookupopen Opens a file to write a lookup table.
lookupread Finds the nearest extracted value from a filecontaining a lookup table of design and extractedparameters.
lookupwrite Writes to a lookup table a design and an extractedparameter pair.
SPICE Netlist
importnetlist Imports an optical SPICE netlist
Comma separated value (csv)
exportcsvresults Exports simulation results to comma separated valueformatted files.
Debugging
Command Description
debug Opens the debug utility window.
See Also exportfigure , load , save
MATLAB functions
123
123
124
124
128
129
129
129
130
128
204 113 113
Reference Guide112
© 2003 - 2013 Lumerical Solutions, Inc
Command Description
matlabsave Save workspace data to a Matlab .mat file.
matlabsavelegacy Save workspace data to a legacy Matlab .mat fileformat.
matlab Execute a MATLAB command
matlabget Get a variable from the MATLAB workspace
matlabput Send a variable to the MATLAB workspace
matlabload Load from MATLAB .mat file into workspace.
7.1.1 newproject
Create a new simulation project file. This command is NOT available in INTERCONNECT,please use new instead.
Syntax Description
newproject; Creates a new layout environment.This function does not return any data.
newproject(option); The options are 1: use default file and material database as template 2: use current file and material database as template 3: open a file browser to select and existing file as atemplate
The default option is 1.
See Also System level , new
7.1.2 newmode
Creates a new MODE layout environment.
Function has been deprecated. Use newproject instead.
Syntax Description
newmode; Creates a new layout environment.This function does not return any data.
newmode(option); The options are 1: use default lms file and material database as
124
125
125
127
127
125
109
Scripting Language 113
© 2003 - 2013 Lumerical Solutions, Inc
template 2: use current lms file and material database astemplate 3: open a file browser to select and existing lms file as atemplate
The default option is 1.
See AlsoSystem level
7.1.3 save
Saves an simulation project file. If the simulation has been run, the file will also contain thesimulation results.
Syntax Description
save; Open a file browser to save the file.This function does not return any data.
save(filename); Save with the specified name
See Also System level , load , loaddata , savedata , savedcard
7.1.4 load
Loads an simulation project file. If the simulation has been run, the file will also contain thesimulation results.
Syntax Description
load(filename); Loads the simulation file.This function does not return any data.
See Also System level , loaddata , save , savedata , savedcard , fileexists , dir
7.1.5 del
Delete a file.
Syntax Description
109
109 113 121 121 122
109 121 113 121 122 117 114
Reference Guide114
© 2003 - 2013 Lumerical Solutions, Inc
del("filename"); rm("filename");
Deletes the file "filename".This function does not return any data.
See AlsoSystem level , delete
7.1.6 rm
Delete a file.
Syntax Description
del("filename"); rm("filename");
Deletes the file "filename".This function does not return any data.
See AlsoSystem level , delete
7.1.7 dir
List files in a directory.
Syntax Description
out = dir; out = ls;
The output is a string.Use ?dir; to write the value to the screen.
out = dir("directory"); out = ls("directory");
Lists the files in the specified directory.
See AlsoSystem level , load , splitstring
7.1.8 ls
List files in a directory.
Syntax Description
out = dir; out = ls;
The output is a string.Use ?dir; to write the value to the screen.
out = dir("directory"); out = ls("directory");
Lists the files in the specified directory.
109 227
109 227
109 113 178
Scripting Language 115
© 2003 - 2013 Lumerical Solutions, Inc
See AlsoSystem level , load , splitstring
7.1.9 cd
Change directory.
Syntax Description
cd; Opens a window to browse to a directory.This function does not return any data.
cd("directory"); Changes the working directory to "directory". Wheneveryou open an fsp file or run a script file, it will set theworking directory to the directory of the file opened.
See AlsoSystem level
7.1.10 pwd
Returns the current working directory.
Syntax Description
out = pwd; Returns the current working directory as a string.
See AlsoSystem level , currentfilename
7.1.11 cp
Copy a file.
Syntax Description
cp("file1","file2"); Makes a copy of file1 called file2. This function does not return any data.
cp("path1\file1","path2\file2");
Copies file1 in path1 to file2 in path2.
See AlsoSystem level , mv , pwd , copy (objects)
109 113 178
109
109 117
109 116 115 230
Reference Guide116
© 2003 - 2013 Lumerical Solutions, Inc
7.1.12 mv
Move a file.
Syntax Description
mv("file1","file2"); Moves file1 to file2. This function does not return any data.
cp("path1\file1","path2\file2");
Moves file1 in path1 to file2 in path2.
See AlsoSystem level , cp , pwd
7.1.13 exit
Exit the application.
Syntax Description
exit; Exits the application. Same as exit(1);This function does not return any data.
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 theuser.
The default option is 1.
See AlsoSystem level
7.1.14 system
The system command allows you to have the operating system (OS) execute a command,rather than the Lumerical script interpreter.
The system command does not return any data.
Syntax Description
system("command"); Run "command" at the OS command prompt.
See Also
109 115 115
109
Scripting Language 117
© 2003 - 2013 Lumerical Solutions, Inc
System level , readdata , exit
7.1.15 fileexists
Check if a file exists. The file extension must be specified. By default, the entire path willbe searched.
Syntax Description
out = fileexists("filename"); Returns 1 if the file existsReturns 0 if the file does not exist.
out = fileexists("c:\temp\file.txt");
Search for a file not in the path
See AlsoSystem level , getpath , which , pwd , load , loaddata , write , readdata
, currentfilename , rm ,
7.1.16 currentfilename
Get the current filename and directory.
Syntax Description
out = currentfilename; Returns the current filename as a string. If the current filename is not defined, this function returnsan empty string "".
See AlsoSystem level , fileexists , getpath , which , pwd , fileextension ,filebasename , filedirectory
7.1.17 filebasename
Get the file basename from a string.
Syntax Description
out = filebasename( "location/filename.ext" );
Returns the file basename as a string.
See AlsoSystem level , currentfilename , getpath , which , pwd
109 122 116
109 119 119 115 113 121 123
122 117 114
109 117 119 119 115 118
117 118
109 117 119 119 115
Reference Guide118
© 2003 - 2013 Lumerical Solutions, Inc
7.1.18 fileextension
Get the file extension from a string.
Syntax Description
out = fileextension( "name.ext");
Returns the file extension as a string.
See AlsoSystem level , currentfilename , getpath , which , pwd
7.1.19 filedirectory
Get the file directory from a string.
Syntax Description
out = filedirectory( "location/filename.ext" );
Returns the file directory as a string.
See AlsoSystem level , currentfilename , getpath , which , pwd
7.1.20 getcommands
Returns the list of available script commands in the current script workspace.
Syntax Description
?getcommands; Returns a list of available script commands
See AlsoSystem level
7.1.21 Run script
Run a script by typing its name. The file must be in the current path. The path alwayssearches the current directory first. A script file is not passed variables, and does notreturn variables. All scripts have access to all of the variables defined in the currentworkspace.
It's best to avoid using the names of Lumerical script functions (i.e. plot) for the names ofyour script files. If a script file has the same name as a function, the script will be run (notthe function). This allows you to effectively re-define the behavior of a function, but it can
109 117 119 119 115
109 117 119 119 115
109
Scripting Language 119
© 2003 - 2013 Lumerical Solutions, Inc
cause confusion when done unintentionally.
Syntax Description
filename; Run the script file filename.lsf, if it exists in the currentpath.A script does not have a return type.
See AlsoSystem level , getpath , addpath , which , feval
7.1.22 getpath
Get the current path. By default, the current working directory and the script sub-directoryof the installation (eg. C:\Program Files\Lumerical\FDTD\scripts) are in the path.
Syntax Description
out = getpath; Returns the current path as a string. Use ?getpath; to print it to the screen.
See AlsoSystem level , addpath , which , pwd
7.1.23 addpath
Add a directory to the path.
Syntax Description
addpath("directory"); Adds a directory to the path. This function does not return any data.
See AlsoSystem level , getpath , which , pwd
7.1.24 which
Returns the full file pathname for the specified file.
This function can be helpful when you have added several directories to the Lumerical pathvariable and you want to check which files are being accessed.
Syntax Description
109 119 119 119 176
109 119 119 115
109 119 119 115
Reference Guide120
© 2003 - 2013 Lumerical Solutions, Inc
out = which("filename"); Returns the pathname of the file "filename" as a string. Use ?which("filename"); to display the result to thescreen.
See AlsoSystem level , getpath , addpath , pwd , currentfilename , fileexists
7.1.25 pause
Pause program for a time.
Hit the space bar to force the script to continue. Hit the ESCAPE key to break the scriptat this point.
Syntax Description
pause(time); Pauses script for time, measured in seconds.This function does not return any data.
See AlsoSystem level , break , ESCAPE key
7.1.26 break
Stops a script from executing.
Syntax Description
break; Will stop a script file from executing at that line. A warningwill be generated.This function does not return any data.
See AlsoSystem level , ESCAPE key , pause
7.1.27 Excape key
Interrupts a script or long block of commands.
Syntax Description
ESCAPE key To interrupt a script file from running or a long block ofcommands from executing. A warning will be generated. Sometimes you may need to press escape several times,
109 119 119 115 117 117
109 120 120
109 120 120
Scripting Language 121
© 2003 - 2013 Lumerical Solutions, Inc
or hold it down to interrupt the script.
See AlsoSystem level , break , pause
7.1.28 format
The two format commands toggle the script interpreter between 2 output precision states.The commands print (?) and num2str() use this state to determine how many digits ofprecision 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 AlsoSystem level , num2str , ?
7.1.29 loaddata
Loads workspace variables or d-card data from a Lumerical data file (ldf) file. If any currentvariables exist with the same names as those in the file, the current values will beoverwritten.
Syntax Description
loaddata("filename"); Reads data script variables or d-card data from thespecified file. This function does not return any data.
See AlsoSystem level , savedata , savedcard , workspace , load , fileexists
7.1.30 savedata
Saves workspace variables to a Lumerical data file (ldf) file. To save monitor (D-card) datato an ldf file, see the savedcard function.
Syntax Description
savedata("filename"); Saves all current variables to the specified file. This function does not return any data.
109 120 120
109 175 157
109 121 122 136 113 117
Reference Guide122
© 2003 - 2013 Lumerical Solutions, Inc
savedata("filename", var1,var2,...);
Saves only variables with the specified names to file.
See AlsoSystem level , savedcard , loaddata , workspace , matlabsave
7.1.31 savedcard
Saves d-card data to a Lumerical data file (ldf) file. D-cards are generally used to storemonitor data.
Data is saved in the no norm state. See the units and normalization section of thereference guide for more information.
Syntax Description
savedcard("filename"); Saves all current d-cards (local and global) to the specifiedldf file.This function does not return any data.
savedcard("filename","name1", "name2",...);
Saves only the d-cards with the specified names, "name1","name2", etc.
See AlsoSystem level , savedata , loaddata , matlabsave
7.1.32 readdata
You can import numerical values stored in text files with the readdata command. Thiscommand will read a file with data in a row/column format. The data must be correctlyformatted so each row has the same number of columns. Readdata will ignore any linethat begins with a letter.
Syntax Description
M=readdata("filename.txt"); Will load the text file filename into matrix variable M. Anylines starting with a letter are ignored.
See AlsoSystem level , rm , write , str2num , findstring , replace , replacestring ,substring , fileexists
109 122 121 136 124
109 121 121 124
109 114 123 176 177 177 178
176 117
Scripting Language 123
© 2003 - 2013 Lumerical Solutions, Inc
7.1.33 write
Writes string variables to text files or to standard output.
Typically the write command is used to output data to a text file. If the specified file doesnot exist, it will be created. If it does exist, then the output string will be appended to theend of the file. The write command will automatically add a new line character at the end ofthe string.
On Linux systems only, the write command will output to the standard output (stdout) if afilename is not specified.
Syntax Description
write(my_string); Write my_string to the standard output (linux only).
write("testfile.txt",my_string);
Will write the contents of the string variable my_string totestfile.txt.This function does not return any data.
See AlsoSystem level , readdata , rm , num2str , ? , endl , format , fileexists
7.1.34 asapexport
Exports the desired monitor to a file for interfacing with BRO's ASAP. These files are calledfld files. The monitor must be a frequency power or a frequency profile monitor.
This command is available in FDTD and MODE.
Syntax Description
asapexport( "monitorname"); Export data from monitorname. By default, the firstfrequency point is exported. This function does not return any data.
asapexport( "monitorname",f);
Exports the frequency point specified by the index f.
asapexport( "monitorname",f, "filename");
Exports to the specified "filename" without opening a filebrowser window.
See AlsoSystem level , asapload , asapimport , addimportedsource
109 122 114 175 157 157 121 117
109 124 124 217
Reference Guide124
© 2003 - 2013 Lumerical Solutions, Inc
7.1.35 asapload
Load data from an fld file from BRO's ASAP. asapload creates a d-card structure called"fld_data" which contains all the data in the file. If "fld_data" exists, it will be called"fld_data_2". After loading an asapfile with asapload, you can extract any desired data.,which can be
Ex, Ey, Ez, Hx, Hy, Hz, x, y, z power, frequency, wavelength, index
This command is available in FDTD and MODE.
Syntax Description
asapload; Select the file to load with the file browser.This function does not return any data.
asapload( "filename"); Loads data from an fld file called "filename" without a filebrowser.
See AlsoSystem level , asapexport , asapimport , addimportedsource , fileexists
7.1.36 asapimport
Import an ASAP fld file into an ASAP source. This is equivalent to editing the properties ofthe Import source, and clicking on the Import Source button.
This command is available in FDTD only.
Syntax Description
asapimport( "sourcename"); Imports the fld file into the sourcename source. A filebrowser will open to select the file.This function does not return any data.
asapimport( "sourcename","filename");
Specify the file to open.
See AlsoSystem level , asapexport , asapload , addimportedsource , fileexists
7.1.37 matlabsave
Save workspace data to Matlab .mat data files.
Note: On some Windows computers with a newer version of MATLAB installed, the
109 123 124 217 117
109 123 124 217 117
Scripting Language 125
© 2003 - 2013 Lumerical Solutions, Inc
matlabsave script command will cause the GUI to crash. We are working to resolve theproblem. Until this issue is resolved, there are two potential solutions: - downgrade to MATLAB 2010B-use the matlabsavelegacy script command.
Syntax Description
matlabsave(""); Save all workspace variables to a .mat file that has thesame name as the simulation file.This function does not return any data.
matlabsave("filename"); Saves all workspace variables to the specified .mat file.
matlabsave("filename",var1, ..., varN);
Saves the specified workspace variables to the .mat file.
See Also System level , matlabput , matlabsavelegacy , matlabload , vtksave
7.1.38 matlabsavelegacy
Save workspace data to Matlab .mat data using a legacy Matlab file format required forMatlab version 7.2 and earlier. This file format does not support matrices larger than 2GB. The command syntax is the same as the standard matlabsave command. See matlabsave
for details.
See Also System level , matlabsave
7.1.39 matlabload
Load Matlab .mat data into workspace
Syntax Description
matlabload("filename"); Load to the workspace the data of the specified .mat file.
See Also System level , matlabput , matlabsavelegacy , matlabsave ,
7.1.40 matlab
Runs a MATLAB command from the Lumerical script prompt. This gives access toextended mathematical and visualization functionality from the Lumerical scriptenvironment. If the MATLAB script integration is not enabled, this function will return anerror.
109 127 125 125 128
124
109 124
109 127 125 124
Reference Guide126
© 2003 - 2013 Lumerical Solutions, Inc
The first time a MATLAB function (matlab, matlabget or matlabput) is called, a MATLABsession will be started and a connection will be established with the Lumerical scriptingenvironment. Once this connection is established, MATLAB commands can be run usingthe matlab function. It is important to understand that the MATLAB and the Lumericalscript variable workspaces are completely separate and independent. A MATLABcommand cannot act on a variable defined in the Lumerical workspace, and vice-versa. Variables must be passed between the workspaces using the matlabget and matlabputfunctions. At any time you may examine the MATLAB workspace or interact with theMATLAB environment by typing commands at the MATLAB script prompt.
The output from the MATLAB commands will be printed at the Lumerical script prompt.One limitation of the matlab function is that no error reporting is provided to either theLumerical script prompt or the MATLAB prompt. MATLAB commands should be tested bytyping them directly into the MATLAB prompt before they are called from a Lumericalscript. The output buffer length is roughly 1e5 characters. Additional output will betruncated.
When you have a long sequence of MATLAB commands, you may find it more convenientto save them in a MATLAB m-file. Then, you can simply call the m-file by running a singlecommand.
Setup instructions and system requirements for the MATLAB script integration featurecan be found in the online Knowledge Base. See the Setup and Configuration section ofthe Installation Guide. Additional tips (particularly for plotting data in Matlab) can befound in the MATLAB section of the online User Guide.
Syntax Description
matlab("command"); command: a string containing one or more valid MATLABcommands.
matlab(" command_1 command_2");
Multi-line strings can be used in script files to contain ablock of MATLAB commands. Multi-line strings are notsupported at the script command prompt.
See AlsoSystem level , matlabget , matlabput109 127 127
Scripting Language 127
© 2003 - 2013 Lumerical Solutions, Inc
7.1.41 matlabget
Copies a variable from the MATLAB workspace to the script variable workspace. Theresulting variable will have the same name as the MATLAB variable, and will overwrite anyexisting variable with the same name. If the variable does not exist in MATLAB, thecommand will return an error. For more information, please see the matlab commanddescription.
Note: Matlab script integration must be enabled in order to use this command. For moreinformation on how to set this up see the Matlab script integration page.
Syntax Description
matlabget(var1, var2,...varN); The arguments to this command are one or more variablenames that refer to variables in the MATLAB workspace.This function does not return any data.
See AlsoSystem level , matlab , matlabput
7.1.42 matlabput
Copies a variable from the FDTD/MODE Solutions workspace to the MATLAB workspace.The resulting variable in the MATLAB workspace will have the same name as in FDTD/MODE Solutions, and will overwrite any existing variable with the same name. If the variabledoes not exist in the Lumerical workspace, the command will return an error.
For more information, please see the matlab command description.
Syntax Description
matlabput(var1, var2,...varN); The arguments to this command are one or more variablenames that exist in the Lumerical variable workspace.This function does not return any data.
See AlsoSystem level , matlab , matlabget
7.1.43 copytoclipboard
Copies the selected objects into the system clipboard. Equivalent to 'Ctrl-C'.
Syntax Description
109 125 127
109 125 127
Reference Guide128
© 2003 - 2013 Lumerical Solutions, Inc
copytoclipboard Copies selected objects to the system clipboard
See AlsoSystem level , pastefromclipboard , copy
7.1.44 pastefromclipboard
Paste the contents of the system clipboard into the layout environment. Equivalent to 'Ctrl-V'.
Syntax Description
pastefromclipboard Paste contents of system clipboard
See AlsoSystem level , copytoclipboard , copy
7.1.45 debug
Opens the debug utility window.
This command is available in FDTD only.
Syntax Description
debug; Opens the debug utility window.
See AlsoSystem level
7.1.46 vtksave
The script command vtksave saves a Lumerical dataset into the VTK format. The commandonly saves rectilinear and unstructured datasets. The “filename” will have .vtr appended forrectilinear dataset, .vtu appended for unstructured dataset. The freely available datavisualization program Paraview can then be used to create sophisticated plots of your data.
Syntax Description
vtksave(“filename”, dataset); Save the dataset in vtk file of the name specified.
See Also System level , datasets , rectilineardataset , matlabsave , data visualization withParaView (User Guide)
109 128 230
109 127 230
109
109 141 139 124
Scripting Language 129
© 2003 - 2013 Lumerical Solutions, Inc
7.1.47 lookupread
Finds the nearest extracted value from a file containing a lookup table of design andextracted parameters.
Syntax Description
out = lookupread (filename,table,design,extracted);
Finds the nearest extracted value from a file containing alookup table of design and extracted parameters.Parameter table is the name of the lookup table locatedinside the file, design is a cell containing multiplestructures that define the design parameters to search,and extracted is the name of the parameter to beextracted. It will return the value located at the nearestdesign parameters.
See AlsoSystem level , lookupclose , lookupopen , lookupwrite
7.1.48 lookupopen
Opens a file to write a lookup table.
Syntax Description
lookupopen (filename,table); Opens a file to write a lookup table. This command isrequired before any calls to lookupwrite can be made.
See AlsoSystem level , lookupclose , lookupread , lookupwrite
7.1.49 lookupclose
Closes a file previously created with a lookupopen command.
Syntax Description
lookupclose (filename); Closes a file previously created with a lookupopencommand. This command is required in order to close anyfile open by lookupopen.
See AlsoSystem level , lookupopen , lookupread , lookupwrite
109 129 129 130
109 129 129 130
109 129 129 130
Reference Guide130
© 2003 - 2013 Lumerical Solutions, Inc
7.1.50 lookupwrite
Writes to a lookup table a design and an extracted parameter pair.
Syntax Description
out = lookupwrite (filename, ,design, extracted);
Writes to a lookup table a design and an extractedparameter pair. The design and extracted parameters arecells that contain multiple structures, allowing for mappingbetween multiple design and extracted parameters. Thisfunction can be called multiple times, for each call thedesign and extracted parameters will be appended to thecurrent file. This function must be called after lookupopenand before lookupclose.
See AlsoSystem level , lookupclose , lookupopen , lookupread
7.2 Manipulating variablesThe following commands are used to create and access variables.
Command Description
= Assignment operator.
: Array operator.
[] Create matrix.
% Create variable with space in the name
linspace Creates a linear spaced array.
matrix Creates a matrix filled with zeros.
randmatrix Creates a matrix with all elements randomly setbetween 0 and 1
randnmatrix Creates a matrix with all elements randomlydistributed with mean 0 and standard distribution 1.
histogram Create a matrix containing the histogram count of ayield analysis result.
meshgridx Create a 2D meshgrid in x direction.
meshgridy Create a 2D meshgrid in y direction.
meshgrid3dx Create a 3D meshgrid in x direction.
109 129 129 129
132
132
132
133
133
133
133
134
134
134
135
135
Scripting Language 131
© 2003 - 2013 Lumerical Solutions, Inc
meshgrid3dy Create a 3D meshgrid in y direction.
meshgrid3dz Create a 3D meshgrid in z direction.
meshgrid4d Create a 4D meshgrid in any direction
clear Clears all stored script variables from memory.
workspace Returns a string of all the currently defined scriptingvariables.
Matrix elements How to assign and access matrix elements.
Matrix operations Describes how operators and functions act onmatrices.
Pre-defined constants List of pre-defined constants.
eye Creates identity matrix
struct Creates unstructured dataset
cell Creates cell array variable
The following commands are used to create, access and manipulate datasets. For anintroduction to datasets, see the dataset introduction page.
Command Description
rectilineardataset Creates an empty rectilinear dataset associated withthe coordinates x/y/z.
matrixdataset Creates an empty matrix dataset.
unstructureddataset Creates an empty unstructured dataset associatedwith the coordinates x/y/z and the connectivity matrix
addparameter Adds a parameter to an existing dataset.
addattribute Adds an attribute to an existing dataset.
getresult Gets the dataset results from a monitor or analyzer.
getparameter Get a parameter from an existing dataset.
getattribute Get an attribute from an existing dataset.
135
136
136
136
136
137
138
138
141
146
147
141
139
139
147
140
140
270
140
141
Reference Guide132
© 2003 - 2013 Lumerical Solutions, Inc
7.2.1 =
Assignment operators.
Syntax Description
x = 5+2i; Assign a value to a variable.
See AlsoManipulating variables , ==
7.2.2 :
Array operator.
Syntax Description
x = 2 : 10; x will be an array of numbers that start at 2 and increaseby 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, andconsecutive elements decrease by 1.5. All elements willbe >=2. In this example, the array will be [6, 4.5, 3].
See AlsoManipulating variables , linspace
7.2.3 []
Specify matrix element by element.
Command Description
x = [u11,...,u1N; u21,...,u2N;uM1,...,uMN]
Create an N by M matrix. Columns are separatedwith semicolons. Elements in a row are separatedwith commas. The entries can either be scalars ormatrices of compatible dimension.
See AlsoManipulating variables , linspace , matrix , Accessing and assigning matrixelements
130 151
130 133
130 133 133
137
Scripting Language 133
© 2003 - 2013 Lumerical Solutions, Inc
7.2.4 %
Used to create variables with spaced in the names.
Command Description
%variable with space% To create a variable name that contains spaces,such as "variable with space", put a percentage signbefore and after the variable name.
See AlsoManipulating variables
7.2.5 linspace
Creates a linearly spaced array.
Syntax Description
x = linspace(min,max,num); x will be an array with num elements, linearly spacedbetween min and max. If num is set to 1, then x will be theaverage of min and max.
See AlsoManipulating variables , : , []
7.2.6 matrix
Initialize a matrix. All elements are set to zero.
Syntax Description
x = matrix(i,j,k,....); Initializes an i x j x k x .... matrix.
See AlsoManipulating variables , linspace , []
7.2.7 randmatrix
Initialize a matrix. All elements are random numbers between 0 and 1.
Syntax Description
x = randmatrix(i,j,k,....); Initializes an i x j x k x .... matrix. The elements are all
130
130 132 132
130 133 132
Reference Guide134
© 2003 - 2013 Lumerical Solutions, Inc
random numbers between 0 and 1.
See AlsoManipulating variables , matrix , rand , randreset
7.2.8 randnmatrix
Initialize a matrix. All elements are normally distributed random numbers with mean 0 andstandard distribution 1.
Syntax Description
x = randnmatrix(i,j,k,....); Initializes an i x j x k x .... matrix. The elements are allrandom normally distributed numbers with mean 0 andstandard deviation 1.
See AlsoManipulating variables , matrix , randn , randreset
7.2.9 histogram
Create a matrix containing the histogram count of a yield analysis result.
Syntax Description
out = histogram(y); Returns a matrix containing the histogram count of y.
out = histogram(y,n); Returns a matrix containing the histogram count of y,using n bins.
out = histogram(y,n,barplot);
Returns a matrix containing the histogram count of y,using n bins. If barplot is true (1), the histogram count isformatted for a bar plot.
See AlsoManipulating variables , histc
7.2.10 meshgridx
Create a 2D meshgrid in the x direction
Syntax Description
out = meshgridx(x,y); If x and y are single column (or single row vectors), ofdimension nX1 and mX1 respectively, the command
X = meshgridx(x,y);
130 133 190 191
130 133 190 191
130 202
Scripting Language 135
© 2003 - 2013 Lumerical Solutions, Inc
Will create a 2D matrix of dimension nXm where X(i,j)=x(i).
See AlsoManipulating variables , image , meshgridy , meshgrid3dx
7.2.11 meshgridy
Create a 2D meshgrid in the y direction
Syntax Description
out = meshgridy(x,y); If x and y are single column (or single row vectors), ofdimension 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 AlsoManipulating variables , image , meshgridx , meshgrid3dx
7.2.12 meshgrid3dx
Create a 3D meshgrid in the x direction
Syntax Description
out = meshgrid3dx(x,y,z); The 3D version of meshgridx and meshgridy.
See AlsoManipulating variables , meshgridx , meshgridy , meshgrid3dy , meshgrid3dz
7.2.13 meshgrid3dy
Create a 3D meshgrid in the y direction
Syntax Description
out = meshgrid3dy(x,y,z); The 3D version of meshgridx and meshgridy.
See AlsoManipulating variables , meshgridx , meshgridy , meshgrid3dx , meshgrid3dz
130 202 135 135
130 202 134 135
130 134 135 135 136
130 134 135 135 136
Reference Guide136
© 2003 - 2013 Lumerical Solutions, Inc
7.2.14 meshgrid3dz
Create a 3D meshgrid in the z direction
Syntax Description
out = meshgrid3dz(x,y,z); The 3D version of meshgridx and meshgridy.
See AlsoManipulating variables , meshgridx , meshgridy , meshgrid3dx , meshgrid3dy
7.2.15 meshgrid4d
Create a 4D meshgrid in any direction.
Syntax Description
out = meshgrid4d(dim, x1,x2, x3, x4);
The 4D meshgrid function. dim specifies the dimension along which to create the gridx1,x2,x3,x4 are the position vectors in each direction
See AlsoManipulating variables , meshgridx , meshgridy , meshgrid3dy , meshgrid3dz
7.2.16 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.This function does not return any data.
See AlsoManipulating variables , cleardcard
7.2.17 workspace
Returns a list of all the currently defined variables in the scripting workspace.
Syntax Description
out = workspace; Returns a string that lists all currently defined variables inthe workspace.
130 134 135 135 135
130 134 135 135 136
130 274
Scripting Language 137
© 2003 - 2013 Lumerical Solutions, Inc
Use ?workspace; to print this to the screen.
See AlsoManipulating variables
7.2.18 Accessing and assigning matrix elements
Accessing and assigning matrix elements.
Command Description
x = [u; v; w] Create a column vector. u,v,w can either be scalarsor matrices of compatible dimension.
x = [u, v, w] Create a row vector. u,v,w can either be scalars ormatrices 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 theassignment A(I,...) = B, if B is not a scalar, the sub-matrix A(I,...) must be the same same size as B. If Bis a scalar, then all the values of the sub-matrix areset 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 asingle index.
x=y(z); Indices stored in matrix (z) used to select elementsof matrix y. length(x) will equal length(z).
See AlsoManipulating variables
130
130
Reference Guide138
© 2003 - 2013 Lumerical Solutions, Inc
7.2.19 Matrix operators
Almost all the scripting functions will act element by element on matrices. Single numbersare treated as matrices of dimension 1x1. The following table provides some examples.
Dimension ofx
Dimension ofy
Operation Dimension ofz
Value of 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 = x
ij * y
11
10x10 10x10 z = x * y 10x10 Zij = x
ij * y
ij
10x10 11x11 z = x * y Error Error
See AlsoManipulating variables
7.2.20 Pre-defined constants
Name Description
pi The number .
c 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.
h The Planck constant.
hbar The reduced Planck constant.
true Logical TRUE (1).
false Logical FALSE (0);
e The electron volt.
See AlsoManipulating variables
130
130
Scripting Language 139
© 2003 - 2013 Lumerical Solutions, Inc
7.2.21 matrixdataset
Creates an empty matrix dataset. Matrix datasets are used for data (attributes andparameters) that don't have any spatial dependence (i.e. Reflection vs frequency). Fordatasets that do have x/y/z spatial coordinates (i.e. electric fields), use rectilineardataset
.
Matrix datasets can be parameterized, and can contain an arbitrary number of attributes(see addattribute) and parameters (see addparameter) .
See Dataset introduction for more information.
Syntax Description
matrixdataset; Creates an empty dataset.
matrixdataset("name"); Creates an empty dataset with the name "name".
See Alsorectilineardataset , addattribute , addparameter , visualize , datasets ,getparameter , getattribute , matrixdataset , struct
7.2.22 rectilineardataset
Creates an empty rectilinear dataset that is associate with the x/y/z coordinates (ex. E andH fields). Like matrix datasets, rectilinear datasets can be parameterized, and can containan arbitrary number of attributes (see addattribute) and parameters (see addparameter)
.
See Dataset introduction for more information.For datasets that are not associated with the x/y/z coordinates (ex. transmission as afunction of frequency), see matrixdataset .
Syntax Description
rectilineardataset(x,y,z); Creates a empty rectilinear dataset associated with thecoordinates x/y/z.
rectilineardataset("dataset_name",x,y,z);
Creates a empty rectilinear dataset named"dataset_name" associated with the coordinates x/y/z.
See Alsorectilineardataset , addattribute , addparameter , visualize , datasets ,
139
140 140
141
139 140 140 203 141
140 141 139 146
140
140
141
139
139 140 140 203 141
Reference Guide140
© 2003 - 2013 Lumerical Solutions, Inc
getparameter , getattribute , matrixdataset , struct
7.2.23 addparameter
Adds a parameter to an existing dataset.
Syntax Description
R.addparameter("p_name",p);
Adds the parameter p to the existing dataset R.
R.addparameter("p1_name",p1, "p2_name", p2);
Adds the interdependent parameter p1_name, p2_name tothe R dataset. The most common interdependent parameter is frequencyand wavelength. Parameters that are not interdependentmust be added separately.
See Alsorectilineardataset , addattribute , addparameter , visualize , datasets ,getparameter , getattribute , matrixdataset
7.2.24 addattribute
Adds an attribute to an existing dataset.
Syntax Description
R.addattribute("a_name", a); Adds the scalar attribute a to the dataset R.
R.addattribute("a_vector",a_1, a_2, a_3);
Adds the vector attribute a_vector to the existing datasetR. The components of the vector are a_1, a_2 and a_3
See Alsorectilineardataset , addattribute , addparameter , visualize , datasets ,getparameter , getattribute , matrixdataset
7.2.25 getparameter
Get a parameter from an existing dataset.
Syntax Description
?getparameter(R); Returns the names of all the parameters in the dataset R.
Parameter = R.getparameter("p");
Retrieves the parameter p from the existing dataset R. Theresult "Parameter" is a scalar matrix.
140 141 139 146
139 140 140 203 141
140 141 139
139 140 140 203 141
140 141 139
Scripting Language 141
© 2003 - 2013 Lumerical Solutions, Inc
Parameter = getparameter(R,"p");
Retrieves the parameter p from the existing dataset R. Theresult "Parameter" is a scalar matrix.
See Alsomatrixdataset , rectilineardataset , "." operator , getresult , getattribute ,visualize , datasets
7.2.26 getattribute
Get an attribute from an existing dataset.
Syntax Description
?getattribute(R); Returns the names of all the attributes in the dataset R.
Attribute = R.getattribute("a");
Retrieves the attribute a from the existing dataset R. Theresult "Attribute" is a scalar matrix.
Attribute = getparameter(R,"a");
Retrieves the attribute a from the existing dataset R. Theresult "Attribute" is a scalar matrix.
See AlsoDataset introduction , matrixdataset , rectilineardataset , "." operator , getresult
, getparameter , visualize , datasets
7.2.27 eye
The script command eye creates a 2D identity matrix.
Syntax Description
I = eye; Returns a 1x1 matrix, value 1.0.
I = eye(n); Returns nxn identity matrix.
I = eye(n,m); Returns nxm matrix with ones on main diagonal
See AlsoDatasets , matrixdataset , rectilineardataset , matlab , matrix
7.2.28 Datasets
Introduction to Lumerical datasetsLumerical datasets are structured data objects that collect a set of related matrices into asingle convenient object. To introduce this concept, we'll start by providing two examples. Additional information follows.
139 139 168 270 141
203 141
141 139 139 168
270 140 203 141
141 139 139 125 133
Reference Guide142
© 2003 - 2013 Lumerical Solutions, Inc
Page contentsExample 1) – Reflection vs radius and heightExample 2) – Electric field data from a monitorAttributes and parametersWhat is in a dataset? Icons and the '?' operatorAccessing data in a dataset: the dot '.' operatorDataset types: matrixdataset and rectilineardatasetOperations on datasetsScalar and vector attributes
Example 1) – Reflection vs radius and height (matrix dataset)
Suppose you have a parameter sweep thatmeasures the reflection from a particle as afunction of particle radius and height.Saving this information generally requires 3matrix variables. The 2D matrix R containsthe reflection value from each simulation,while the 1D vectors radius and heightcontain the associated position values.
A dataset object can be used to collect allthree matrices into a single datasetvariable.
The following script code generates some example data, creates a R(radius,height)dataset, and finally creates several plots of the data.
# create example resultsradius = 0:10; height = 1:0.1:3;reflection = randmatrix(length(radius),length(height));
# create Reflection datasetR = matrixdataset("R"); # initialize datasetR.addparameter("radius",radius); # add radius parameterR.addparameter("height",height); # add height parameterR.addattribute("R",reflection); # add reflection attribute
142
143
144
145
145
145
146
146
Scripting Language 143
© 2003 - 2013 Lumerical Solutions, Inc
# plot dataimage(radius,height,reflection); # use original matricesimage(R.radius,R.height,R.R); # use dataset
# send dataset to visualizervisualize(R);
Example 2) – Electric field data from a monitor (rectilinear dataset)
Field monitors in FDTD and MODESolutions are used to calculate and savespatial electric field data. The raw electricfield data within the monitor is distributedbetween several matrices: Each vector fieldcomponent is stored in a matrix (Ex, Ey,Ez), and the four associated positionvectors (x,y,z,f) are also stored as separatematrices.
A dataset can be used used to collect all ofthis information into a single datasetvariable. The figure to the right shows thethree matrices Ex, Ey, Ez that store eachcomponent of the electric field. It alsoshows the associated position vectors x, y,z. All of this information can be storedwithin a single dataset variable.
Note: The electric field matrices usuallyhave a 4th dimension (time or frequency),but this dimension is not included in thefigure due to the difficulty of graphicallyrepresenting a 4th dimension!
The following script code shows how to get the raw data from a frequency monitor inFDTD Solutions (using getdata), and how to manually create a dataset from that data. Italso shows how to directly get the electric field dataset from the monitor in a singlecommand (using getresult). The final section shows how to create a few plots of the data
# monitor namem="monitor";
# get individual data elements with getdata
Reference Guide144
© 2003 - 2013 Lumerical Solutions, Inc
x=getdata(m,"x");y=getdata(m,"y");z=getdata(m,"z");f=getdata(m,"f");Ex=getdata(m,"Ex");Ey=getdata(m,"Ey");Ez=getdata(m,"Ez");
# manually create the electric field dataset from the raw data# initialize dataset and provide spatial position vectorsE_manual = rectilineardataset("E_manual",x,y,z);
# add additional parameter: frequencyE_manual.addparameter("lambda",c/f,"f",f);
# add vector electric field attributeE_manual.addattribute("E",Ex,Ey,Ez);
# all of the above commands can be avoided with a singlegetresult commandE_fromMonitor = getresult(m,"E");
# plot Ex(x,y) at the first z value and first frequency pointto_plot = pinch(pinch(Ex,4,1),3,1); # use original matricesimage(x,y,to_plot); # use original matrices to_plot = pinch(pinch(E_manual.Ex,4,1),3,1); # use datasetimage(E_manual.x,E_manual.y,to_plot); # use dataset
# Plot the entire dataset with the Visualizervisualize(E_manual);
Attributes and parametersAttribute: The actual data of a dataset. In the examples above, the reflection R and electricfield Ex, Ey, Ez were the Attributes of the dataset.Parameter: The associated position vectors of a dataset. In the above examples, radius,height, x, y, z, and f were the parameters.
When creating datasets, the size of the attribute matrices must be consistent with thelengths of the associated parameters matrices.
Scripting Language 145
© 2003 - 2013 Lumerical Solutions, Inc
What is in a dataset? Icons and the '?' operatorThe Results view and Script workspace windows provide a list of current monitor resultsand script variables. Different icons are used for each type of variable (dataset, matrix,string, unstructured data). For datasets, the preview column provides a list of theattributes and parameters in the dataset. In the screenshot below, the 'E' dataset containsone attribute (E) that is a function of 4 parameters (x,y,z, lambda/f).
The '?' operator can be used to output the same information to the script prompt. ?E_field = getresult("monitor","E");> E vs x, y, z, lambda/f
To output the actual attribute or parameter values, do something like:?E_field.x; # output the 'x' position vector> result: > -6.58393e-006 > -6.5442e-006 > -6.50447e-006 > .....
Accessing data in a dataset: the dot '.' operatorIndividual matrices stored in the dataset can be accessed with the dot '.' operator. Forexample, to get the raw x, y, and Ex data from an Electric field dataset, do something like: x = E_field.x;y = E_field.y;Ex = E_field.Ex;
Dataset types: matrixdataset and rectilineardataset
Reference Guide146
© 2003 - 2013 Lumerical Solutions, Inc
Data without spatial parameters (such as example 1) will use matrix datasets.Data with spatial information from a rectilinear grid (such as the FDTD mesh) will use rectilinear datasets.
Operations on datasetsDatasets are primarily intended to be a convenient way to manage and store a collection ofrelated data. It is not possible to apply mathematical operations, such as addition, directlyto dataset objects. Instead, the dot operator must be used to get the desired data into amatrix. The operation can then be applied to the matrix. You may choose to create a newdataset to store the result, or you may simply keep the result as a standard matrix.
Scalar and vector attributesIt is possible to add both scalar and vector attributes to datasets.
ScalarThe command R.addattribute("R",reflection); # add reflection attribute
adds a scalar quantity 'R' to a dataset with the same name. To access the 'R' raw data,use:R.R;
VectorThe command E.addattribute("E",Ex_raw,Ey_raw,Ez_raw); # add vector E fieldattribute
adds a vector quantity 'E' to a dataset with the same name. In this case, we can accessthe raw 'E' data in the following ways:E.Ex; # get Ex componentE.Ey; # get Ey componentE.Ez; # get Ez componentE.E2; # get |E|^2E.E; # get all components in a single matrix. An extradimension of length 3 will be added to the matrix, for eachvector component.
See Alsorectilineardataset , addattribute , addparameter , visualize , datasets ,getparameter , getattribute , matrixdataset , struct
7.2.29 struct
The script command struct adds an unstructured dataset. Any data type (such as matrix,string, dataset) can be added to struct objects.
139 140 140 203 141
140 141 139 146
Scripting Language 147
© 2003 - 2013 Lumerical Solutions, Inc
Syntax Description
a = struct; Creates an unstructured dataset.
a.a = "string"; Adds a string field to the structure.
a.b = matrix(5,5); Adds a field of matrix of 5x5 to the structure.
See AlsoDatasets , matrixdataset , rectilineardataset , cell
7.2.30 cell
The script command cell creates a cell array variable with specified number of elements.The cell array element can be any data type, such as matrix, string, and dataset.
Syntax Description
a = cell(n); Creates a cell array with n elements.
a{n} = "string"; Adds a string to the specified element of the cell array.
a{n} = matrix(5,5); Adds a field of matrix of 5x5 to the specified element of thecell array.
See AlsoDatasets , matrixdataset , rectilineardataset , struct , splitstring
7.2.31 unstructureddataset
Unstructureddataset script command creates an empty dataset that is associated witharbitrary x/y/z coordinate in space, and with additional matrix, a connectivity matrix toconnect them. The connectivity matrix comes after x, y, and z. Like rectilinear datasets,unstructured datasets can be parameterized, and can contain an arbitrary number ofattributes (see addattribute) and parameters (see addparameter) .
See Dataset introduction for more information.For datasets that are not associated with the x/y/z coordinates (ex. transmission as afunction of frequency), see matrixdataset .
Syntax Description
unstructureddataset(x,y,z,C);
Creates a empty rectilinear dataset associated with thecoordinates x/y/z and a connectivity matrix to connect
141 139 139 147
141 139 139 146 178
140 140
141
139
Reference Guide148
© 2003 - 2013 Lumerical Solutions, Inc
them.
See Alsorectilineardataset , addattribute , addparameter , visualize , datasets ,getparameter , getattribute , matrixdataset , struct
7.3 OperatorsStandard mathematical and string operators.
Algebraic operators
Command Description
* Multiplication. Ex: y = x * z;
/ Division. Ex: y = x / z;
+ Addition. Ex: y = x + z;
- Subtraction. Ex: y = x – z;
- Negative. Ex: y = -x;
^ Power. Ex: y = x 3;In expression A^B, if B is complex, the phase of A isevaluated from - to .
Logical and relational operators
Command Description
== Comparison.
almostequal Almost equal comparison operator.
!= Not equal.
<= Less than or equal to.
>= Greater than or equal to.
< Less than.
> Greater than.
& AND.
and AND.
| OR.
139 140 140 203 141
140 141 139 146
150
150
150
150
150
151
151
151
152
152
152
153
153
153
153
154
Scripting Language 149
© 2003 - 2013 Lumerical Solutions, Inc
or OR.
! NOT.
~ NOT.
Dataset operators
Command Description
. Retrieve the parameters and attributes of datasets.
String operators
Command Description
" Create a string variable.
' Create a string variable.
+ Add strings
endl end of line character.
Output to screen
Command Description
? Display output on screen.
# script file comments Comment script files with #
7.3.1 .
The dot operator can be used to retrieve the parameters and attributes of datasets.
Syntax Description
result = A.result; Retrieves the parameter or attribute "result" from theexisting dataset A. The result is a scalar matrix.
See Alsomatrixdataset , rectilineardataset , getparameter , getattribute , visualize
154
154
155
149
155
156
150
157
157
157
139 139 140 141 203
Reference Guide150
© 2003 - 2013 Lumerical Solutions, Inc
7.3.2 *
Multiplication. When applied to matrices, this operator does simple element by elementmultiplication, not matrix multiplication.
Syntax Description
y = x * z; Multiply x and z.
See AlsoOperators , * , / , + , - , ^ , mult
7.3.3 /
Division.
Syntax Description
y = x / z; Divide x by z.
See AlsoOperators , * , / , + , - , ^
7.3.4 +
Addition.
Syntax Description
y = x + z; Add x and z.
y = string1 + string2; Concatenate strings together.
See AlsoOperators , * , / , + , - , ^
7.3.5 -
Subtraction, or negative.
Syntax Description
y = x - z; Subtract z from x.
y = -x; Negative
148 150 150 150 150 151 169
148 150 150 150 150 151
148 150 150 150 150 151
Scripting Language 151
© 2003 - 2013 Lumerical Solutions, Inc
See AlsoOperators , * , / , + , - , ^
7.3.6 ^
Power. In expression A^B, if B is complex, the phase of A is evaluated from - to .
Syntax Description
y = x 3; x cubed.
See Also Operators , * , / , + , - , ^
7.3.7 ==
Logical comparison. This operators can be used with complex numbers and strings.
Syntax Description
out = y == x; Returns 1 if x and y are equal. Returns 0 otherwise.
See AlsoOperators , = , almostequal , != , <= , >= , < , > , & , and , |, or , ! , ~
7.3.8 almostequal
Almost equal comparison operator. When using floating point numbers (rather thanintegers), two values that are meant to be equal may not be exactly equal due to roundingerrors that are always present in floating point calculations. In such cases, the almostequal 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 /2times 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 /2times relative diff or if A - B is less than or equal toabsolute diff. Returns 0 otherwise.
148 150 150 150 150 151
148 150 150 150 150 151
148 132 151 152 152 152 153 153 153 153 154
154 154 155
Reference Guide152
© 2003 - 2013 Lumerical Solutions, Inc
See AlsoOperators , = , == , != , <= , >= , < , > , & , and , | , or , !
, ~
7.3.9 !=
Not equal to comparison operator. Returns 1 if values are not equal. Returns 0 if valuesare equal. This operator can be used in matrix operations. This operators can be usedwith complex numbers.
Syntax Description
out = a!=b; If a is not equal to b, then out equals 1. Otherwise outequals 0.
See AlsoOperators , == , almostequal , <= , >= , < , > , & , and , | , or
, ! , ~
7.3.10 <=
Logical less than or equal to. Imaginary components of x and y are ignored.
Syntax Description
out = y <= x; Less than or equal to.
See AlsoOperators , == , != , almostequal , >= , < , > , & , and , | , or
, ! , ~
7.3.11 >=
Logical greater than or equal to. Imaginary components of x and y are ignored.
Syntax Description
out = y >= x; Greater than or equal to.
See AlsoOperators , == , != , <= , almostequal , < , > , & , and , | , or
, ! , ~
148 132 151 152 152 152 153 153 153 153 154 154
154 155
148 151 151 152 152 153 153 153 153 154
154 154 155
148 151 152 151 152 153 153 153 153 154
154 154 155
148 151 152 152 151 153 153 153 153 154
154 154 155
Scripting Language 153
© 2003 - 2013 Lumerical Solutions, Inc
7.3.12 <
Logical less than. Imaginary components of x and y are ignored.
Syntax Description
out = y < x; Less than.
See AlsoOperators , == , != , <= , >= , almostequal , > , & , and , | , or
, ! , ~
7.3.13 >
Logical greater than. Imaginary components of x and y are ignored.
Syntax Description
out = y > x; Greater than.
See AlsoOperators , == , != , <= , >= , < , almostequal , & , and , | , or
, ! , ~
7.3.14 &
Logical AND. Imaginary components of x and y are ignored.
Syntax Description
out = y & x; If the real part of either or both of x,y are zero, then return0. Otherwise return 1.
y and x; Same as &.
See AlsoOperators , == , != , <= , >= , < , > , & , and , | , or , ! , ~
7.3.15 and
Logical AND. Imaginary components of x and y are ignored.
Syntax Description
148 151 152 152 152 151 153 153 153 154
154 154 155
148 151 152 152 152 153 151 153 153 154
154 154 155
148 151 152 152 152 153 153 153 153 154 154 154
155
Reference Guide154
© 2003 - 2013 Lumerical Solutions, Inc
out = y & x; If the real part of either or both of x,y are zero, then return0. Otherwise return 1.
y and x; Same as &.
See AlsoOperators , == , != , <= , >= , < , > , & , and , | , or , ! , ~
7.3.16 |
Logical OR. Imaginary components of x and y are ignored.
Syntax Description
out = y | x; If the real part of either or both of x,y is non-zero, thenreturn 1. Otherwise return 0.
y or x; Same as |.
See AlsoOperators , == , != , <= , >= , < , > , & , and , | , or , ! , ~
7.3.17 or
Logical OR. Imaginary components of x and y are ignored.
Syntax Description
out = y | x; If the real part of either or both of x,y is non-zero, thenreturn 1. Otherwise return 0.
y or x; Same as |.
See AlsoOperators , == , != , <= , >= , < , > , & , and , | , or , ! , ~
7.3.18 !
Logical NOT operator. If a value is 0, then NOT returns 1. For all other values, NOT returns0. NOT(A) is equivalent to A==0, where == is the comparison operator.
Syntax Description
148 151 152 152 152 153 153 153 153 154 154 154
155
148 151 152 152 152 153 153 153 153 154 154 154
155
148 151 152 152 152 153 153 153 153 154 154 154
155
Scripting Language 155
© 2003 - 2013 Lumerical Solutions, Inc
out = !a; applies logical not operator to a
out = ~a; applies logical not operator to a
See AlsoOperators , == , != , <= , >= , < , > , & , and , | , or , ! , ~
7.3.19 ~
Logical NOT operator. If a value is 0, then NOT returns 1. For all other values, NOT returns0. NOT(A) is equivalent to A==0, where == is the comparison operator.
Syntax Description
out = !a; applies logical not operator to a
out = ~a; applies logical not operator to a
See AlsoOperators , == , != , <= , >= , < , > , & , and , | , or , ! , ~
7.3.20 "
String operator. Strings can be created with single or double quotes.
The following escape sequences are recognized when creating strings with double quotes:\" double quotes in string\n newline (linefeed) character in string\\ backslash in string
Syntax Description
out="my string"; use double quotes to create strings
NOTE: Literal backslashes and double quotesIt is always possible to create a literal backslash in a string with \\. However, \ alsoresults 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
148 151 152 152 152 153 153 153 153 154 154 154
155
148 151 152 152 152 153 153 153 153 154 154 154
155
Reference Guide156
© 2003 - 2013 Lumerical Solutions, Inc
mystring = "C:\Program Files\Lumerical"; # use double quotesmystring = "C:\\Program Files\\Lumerical"; # use double quotesand \\ 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 twocommands are valid and equivalent:mystring = 'C:\Program Files\Lumerical\'; # use singlequotesmystring = "C:\\Program Files\\Lumerical\\"; # use doublequotes and \\ escape character
The other potential command, where we use a single backslash, is not valid syntax andwill result in an error.mystring = "C:\Program Files\Lumerical\"; # use doublequotes
The problem is that the script interpreter will interpret the final \" as an escape characterfor 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 nodouble quote character closing the string.
See AlsoOperators , ' , num2str , + , endl , write , eval
7.3.21 '
String operator. Strings can be created with single or double quotes.
The following escape sequences are recognized when creating strings with single quotes:'' single quote in string (two single quote characters)
Syntax Description
out='my string'; use single quotes to create strings
See AlsoOperators , " , num2str , + , endl , write , eval
148 156 175 150 157 123 176
148 155 175 150 157 123 176
Scripting Language 157
© 2003 - 2013 Lumerical Solutions, Inc
7.3.22 endl
Add an end of line character to a string
Syntax Description
out = "line1"+endl+"line2"; Add an end of line character to the string.
See AlsoOperators , num2str , + , " , write
7.3.23 ?
Print output to the screen. Use the format script command to change the precision of theoutput.
Syntax Description
?command; Displays the output of the command on the screenThis function does not return any data.
See AlsoSystem level , write , format , #
7.3.24 comments
Use the # character to comment script files. Anything after the # character is ignored. Thecomments are not displayed when the script file is run. Comments can not be used whentyping commands directly into the script prompt.
Syntax Description
x=1; # set x to 1 Anything after the # character is ignored.
See AlsoSystem level
7.4 FunctionsStandard mathematical and matrix functions.
Trigonometric and complex
Command Description
sin Trigonometric sin function.
148 175 150 155 123
109 123 121 157
109
162
Reference Guide158
© 2003 - 2013 Lumerical Solutions, Inc
cos Trigonometric cos function.
tan Trigonometric tan function.
asin Inverse trigonometric sin function.
acos Inverse trigonometric cos function.
atan Inverse trigonometric tan function.
atan2 Same as atan, but returns angle in correct quadrant.
real Returns the real part of variable
imag Returns the imaginary part of variable
conj Complex conjugate
abs Absolute value
angle Phase of a complex number.
unwrap Removes phase difference of more than 2
Logarithmic, exponential and power
Command Description
log The natural logarithm. Input can be complex ornegative.
log10 The log, base 10. Input can be complex or negative.
sqrt The square root.
exp The exponential.
Matrix functions
Command Description
size Returns the dimensions of a matrix.
length Returns the total number of elements in a matrix.
pinch Remove singleton dimensions from a matrix.
sum The sum of a matrix.
max The max value in a matrix.
min The min value in a matrix.
162
162
162
163
163
163
164
164
164
164
165
165
165
165
166
166
166
166
167
167
168
168
Scripting Language 159
© 2003 - 2013 Lumerical Solutions, Inc
dot The dot product of two vectors.
cross The cross product of two vectors.
flip Flip a matrix in one dimension.
interp Linear interpolation function.
spline Cubic spline interpolation.
integrate Integrate a matrix.
integrate2 Integrate a matrix, ignore singleton dimensions.
find Find values that satisfy a condition in a matrix.
findpeaks Find peaks in a matrix.
transpose Transpose a matrix.
ctranspose Transpose a matrix, and do complex conjugate.
mult Perform matrix multiplication of two or morematrices.
reshape Reshape the matrix to have different dimensionsconserving the overall product of the dimensions.
eig Calculate the eigenvalues and/or eigenvectors of amatrix.
permute Rearrange the dimensions of a matrix.
inv Calculate the inverse of a matrix.
mean Return the mean value of a matrix
var Returns the variance
std Returns the standard deviance
mapfind Returns a string value associated to specified point,given a file containing a map of values to a string
See alsoManipulating variables
String functions
Command Description
num2str Convert number to a string.
168
168
170
171
172
173
173
174
174
175
175
169
170
169
170
171
192
193
194
194
130
175
Reference Guide160
© 2003 - 2013 Lumerical Solutions, Inc
str2num Convert a string into a floating point number.
eval Execute string containing Lumerical scriptinglanguage.
feval Run a Lumerical script file.
length Returns the total length of the string.
substring Returns a substring of a string, as a specifiedposition and length.
findstring Returns the position of a substring in a string.
replace Replaces a part of a string with another, at aspecified position.
replacestring Replaces all instances of a substring with anotherstring.
splitstring Split a single long string into a cell (string) arraybased on a delimiting character.
Frequency and time-domain
Command Description
fft Fast Fourier transform.
fftw Returns the angular frequency vector.
fftk Returns the spatial wavevector kx.
invfft Inverse fft.
czt Chirped z-transform.
Line and polygon functions
Command Description
polyarea Returns the area of a polygon.
centroid Returns the center of mass of a polygon.
polyintersect Determines if two polygons intersect.
inpoly Determines if a series of points are inside our outsidea polygon.
polygrow Grows or shrinks a polygon by a specified amount.
polyand Combines two polygons into one with an and
176
176
176
166
176
177
177
178
178
178
180
181
182
183
183
184
184
185
185
186
Scripting Language 161
© 2003 - 2013 Lumerical Solutions, Inc
operation.
polyor Combines two polygons into one with an oroperation.
polyxor Combines two polygons into one with a xoroperation.
lineintersect Returns the intersection of line segments.
linecross Determines if line segments cross each other.
Miscellaneous
Command Description
ceil Round up.
floor Round down.
mod Modulus after division.
round Rounds to the nearest integer.
rand Returns a uniformly distributed random numberbetween 0 and 1.
lognrnd Returns a lognormal distributed random number.
randn Returns a normally distributed random number.
randreset Resets the random number seed.
finite Determines if a number is finite or NaN.
solar Returns the solar power spectrum
stackrt Calculates reflection and transmission of multi-layerstacks
all Returns 1 if all of the specified matrix entries arenonzero and returns 0 otherwise.
any Returns 1 if any of the specified matrix entries arenonzero and returns 0 otherwise.
quadtri Returns approximated integration (first orderquadrature) of data on a 2D finite element mesh.
precision Returns truncated value to a user specified precision.
186
187
187
188
188
188
189
189
190
190
190
191
191
191
192
192
193
195
Reference Guide162
© 2003 - 2013 Lumerical Solutions, Inc
7.4.1 sin
Trigonometric sine function. Angle units are in radians. Function is defined for complexangles. Phase of a complex number is evaluated between - and .
Syntax Description
out = sin(x); Returns the complex sine of x.
See Also Functions , asin
7.4.2 cos
Trigonometric cosine function. Angle units are in radians. Function is defined for complexangles. Phase of a complex number is evaluated between - and .
Syntax Description
out = cos(x); Returns the complex cosine of x.
See Also Functions , acos
7.4.3 tan
Trigonometric tangent function. Angle units are in radians. Function is defined for complexangles. Phase of a complex number is evaluated between - and .
Syntax Description
out = tan(x); Returns the complex tangent of x.
See Also Functions , atan , atan2
7.4.4 asin
Inverse trigonometric sine function. Angle units are in radians. Function is defined forcomplex values. Phase of a complex number is evaluated between - and . If x iscomplex, or abs(x) > 1, the following equation is used: asin(x) = -i ln( ix + sqrt(1-x 2))
Syntax Description
157 162
157 163
157 163 163
Scripting Language 163
© 2003 - 2013 Lumerical Solutions, Inc
out = asin(x); Returns the complex arcsine of x.
See Also Functions , sin
7.4.5 acos
Inverse trigonometric cosine function. Angle units are in radians. Function is defined forcomplex values. Phase of a complex number is evaluated between - and . If x iscomplex, or abs(x) > 1, the following equation is used: acos(x) = -i ln( x + i sqrt( 1-x 2))
Syntax Description
out = acos(x); Returns the complex arccosine of x.
See Also Functions , cos
7.4.6 atan
Inverse trigonometric tangent function. Angle units are in radians. Function is defined forcomplex values. Phase of a complex number is evaluated between - and . If x iscomplex, or abs(x) > 1, the following equation is used: atan(x) = 0.5 i ln( (i+x)/(i-x) )
Syntax Description
out = atan(x); Returns the complex arctangent of x.
See Also Functions , atan2 , tan
7.4.7 atan2
Inverse trigonometric tangent function, calculates the arctangent of y/x, but returns theangle in the correct quadrant. Angle units are in radians. Function is defined for realvalues only.
Syntax Description
out = atan2(y,x); x,y must be real.
See Also
157 162
157 162
157 163 162
Reference Guide164
© 2003 - 2013 Lumerical Solutions, Inc
Functions , atan , tan
7.4.8 real
Returns the real part of a number or matrix.
Syntax Description
out = real(x); Returns the real part of x.
See Also Functions , imag
7.4.9 imag
Returns the imaginary part of a number or matrix.
Syntax Description
out = imag(x); Returns the imaginary part of x.
See Also Functions , real , conj
7.4.10 conj
Returns the complex conjugate of a number or matrix.
Syntax Description
out = conj(x); Returns the complex conjugate of x.
See Also Functions , real , imag
7.4.11 abs
Returns the absolute value of a number or matrix.
Syntax Description
out = abs(x); Returns the absolute value of x.
See Also Functions , real , imag
157 163 162
157 164
157 164 164
157 164 164
157 164 164
Scripting Language 165
© 2003 - 2013 Lumerical Solutions, Inc
7.4.12 angle
Returns the angle or phase of a complex number or matrix in radians.
Syntax Description
out = angle(x); Returns the phase of x.
See Also Functions , real , imag , unwrap
7.4.13 unwrap
Removes changes of more than 2 from a 1D array. It can be useful after angle(x) to seephase without discontinuities.
The unwrap function is primarily intended for 1D arrays. Care must be taken when applyingit to matrices with more than one dimension.
Syntax Description
out = unwrap(x); Return the values of x without discontinuities.
See Also Functions , real , imag , angle
7.4.14 log
The natural logarithm. Input can be complex or negative.
Syntax Description
out = log(x); The natural logarithm. Input can be complex or negative.
See Also Functions , log10
7.4.15 log10
The log, base 10. Input can be complex or negative.
Syntax Description
out = log10(x); The log, base 10. Input can be complex or negative.
See Also Functions , log
157 164 164 165
157 164 164 165
157 165
157 165
Reference Guide166
© 2003 - 2013 Lumerical Solutions, Inc
7.4.16 sqrt
The square root.
Syntax Description
out = sqrt(x); The square root.
See Also Functions , ^
7.4.17 exp
The exponential.
Syntax Description
out = exp(x); The exponential.
See Also Functions , log , ^
7.4.18 size
Returns the size of a matrix.
Syntax Description
y = size(x); y is a matrix which shows the dimensions of x.
See Also Functions , length , flip , transpose
7.4.19 length
Returns the number of elements in a matrix. If the argument is a string, it will return thelength of the string.
Syntax Description
y = length(x); y the number of elements in a matrix. For example, if x isan n by m matrix, y = length( x ) = n * m.
See AlsoFunctions , size , transpose , flip , substring , findstring , replace ,
157 151
157 165 151
157 166 170 175
157 166 175 170 176 177 177
Scripting Language 167
© 2003 - 2013 Lumerical Solutions, Inc
replacestring
7.4.20 pinch
Removes all singleton dimensions from a matrix.
Syntax Description
out = pinch(x); Removes all singleton dimensions. For example, if x is amatrix 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 NxMxKxPmatrix then
y=pinch(x,2); will return an NxKxP matrix where
y(i,j,k) = x(i,1,j,k)
pinch(x,I,j); Removes a specified dimension but keeps a specific indexfor the dimension being removed. If x is an NxMxKxPmatrix then
y=pinch(x,2,4); will return an NxKxP matrix where
y(i,j,k) = x(i,4,j,k)
See AlsoFunctions , find , size , flip
7.4.21 sum
Sum of elements in a matrix.
Syntax Description
out = sum(x); Sum of all the elements in a matrix, over all dimensions.
out = sum(x,2); Sum x over the specified dimension.
See AlsoFunctions , integrate , mean
178
157 174 166 170
157 173 192
Reference Guide168
© 2003 - 2013 Lumerical Solutions, Inc
7.4.22 max
The maximum value in a matrix. For complex numbers, only the real part is considered.
Syntax Description
out = max(x); The maximum value in a matrix.
See AlsoFunctions , min , abs , mean
7.4.23 min
The minimum value in a matrix. For complex numbers, only the real part is considered.
Syntax Description
out = min(x); The minimum value in a matrix.
See AlsoFunctions , max , abs , mean
7.4.24 dot
Dot product.
Matrix A, B must have the same number of elements. The dot product will be calculatedwith the following formula.
i
iBiAC )()(
Syntax Description
C = dot(A, B); Returns the dot product of A and B
See Also Functions , cross , * , length , size
7.4.25 cross
Vector cross product.
Matrix A, B must be the same size. The cross product will be computed on the firstdimension that has a size of 3. There must be at least one dimension with a size of 3.
157 168 164 192
157 168 164 192
157 168 150 166 166
Scripting Language 169
© 2003 - 2013 Lumerical Solutions, Inc
Assume that A,B are 2D matrices, where the second dimension contains the vectorcomponents. The size of the second dimension must be 3. Then the elements of C will becalculated with the standard cross product formulas.
)1,()2,()2,()1,()3,(
)1,()3,()3,()1,()2,(
)2,()3,()3,()2,()1,(
iBiAiBiAiC
iBiAiBiAiC
iBiAiBiAiC
Syntax Description
C = cross(A, B); Returns the cross product of A and B
See Also Functions , dot , * , length , size
7.4.26 eig
Find the eigen value and/or eigen vector of a matrix. The matrix has to be square.
Syntax Description
out = eig(A);out = eig(A, 1);
Returns the eigenvalues of matrix A.
out = eig(A, 2); Returns the eigenvectors of matrix A.
out = eig(A, 3); Returns both the eigenvalues and eigenvectors of matrixA.
See AlsoOperators , = , == , != , <= , >= , < , > , & , and , | , or , !
, ~ , mult , permute , reshape , inv
7.4.27 mult
Perform matrix multiplication of two or more matrices. The dimensions of the matrices haveto match
Syntax Description
out = mult(A,B,...) Returns the matrix multiplication of matrices, A x B x C ...
157 168 150 166 166
148 132 151 152 152 152 153 153 153 153 154 154
154 155 169 170 170 171
Reference Guide170
© 2003 - 2013 Lumerical Solutions, Inc
See AlsoOperators , = , == , != , <= , >= , < , > , & , and , | , or , !
, ~ , eig , permute , reshape , inv
7.4.28 flip
Flip a matrix along one dimension.
Syntax Description
C = flip(A, dim); Flips the matrix A along the dimension dim.
See Also Functions , size , length , pinch , transpose , reshape , permute
7.4.29 permute
This function is a more general version of the transpose function. It allows matrixdimensions to be rearranged as needed.
Syntax Description
out = permute(A, [i,j,k, ...]) Returns a matrix with the same elements as A but withrearranged dimensions i,j,k, etc.
See AlsoOperators , = , == , != , <= , >= , < , > , & , and , | , or , !
, ~ , eig , reshape , mult , inv , flip , transpose , size
7.4.30 reshape
Reshapes the matrix A to have the size i,j,k.The product of the specified dimensions,i*j*k*..., must be the same as that of the original matrix A.
Syntax Description
out = reshape(A, [i,j,k, ...]) Returns an array with the same elements as A butreshaped to have the size i by j by k by ...
148 132 151 152 152 152 153 153 153 153 154 154
154 155 169 170 170 171
157 166 166 167 175 170 170
148 132 151 152 152 152 153 153 153 153 154 154
154 155 169 170 169 171 170 175 166
Scripting Language 171
© 2003 - 2013 Lumerical Solutions, Inc
See AlsoOperators , = , == , != , <= , >= , < , > , & , and , | , or , !
, ~ , eig , permute , mult , inv , flip , transpose , size
7.4.31 inv
Calculate the inverse of a matrix. The matrix has to be invertible.
Syntax Description
out = Inv(A) Returns the inverse of matrix A
See AlsoOperators , = , == , != , <= , >= , < , > , & , and , | , or , !
, ~ , eig , mult
7.4.32 interp
Linear interpolation of a data set. The data can be complex.
Syntax Description
out = interp(Ex, xold,xnew);
Does a linear interpolation of a 1D function. Ex is existing dataxold specifies the points where Ex is sampledxnew specifies new point to interpolate the data.
The xnew does does not have to be within the bounds ofxold.
interp(Ex, xold, yold, xnew,ynew);
The 2D version of interp.
interp(Ex, xold, yold, zold,xnew, ynew, znew);
The 3D version of interp.
interp(Ex, xold, yold, zold,told, xnew, ynew, znew,tnew);
The 4D version of interp.
See Also Functions , spline
148 132 151 152 152 152 153 153 153 153 154 154
154 155 169 170 169 171 170 175 166
148 132 151 152 152 152 153 153 153 153 154 154
154 155 169 169
157 172
Reference Guide172
© 2003 - 2013 Lumerical Solutions, Inc
7.4.33 interptri
The script command interpolates a data set from triangular to linear grid. The data can becomplex.
Syntax Description
out = interptri(tri, vtx,u, xi, yi,extrap_val);
Does a triangular to linear interpolation of a function andoutputs a PxQ array of interpolated values, z(xi,yi).
u is existing data of the finite element mesh (Nx1).xi (length P) / yi (length Q) specifies the points where uis to be sampled on the rectilinear mesh, in the x-direction and the y-directiontri is the elements of the triangular mesh taken from thesimulation region, the connectivity array, Mx3,containing row entries that index the three vertices of Mtrianglesvtx are the vertices of the triangular mesh, Nx2,containing row entries of (x,y) pairs, taken from thesimulation regionextrap_val(optional): if an interpolation point is outside ofthe finite element mesh, the point will be assigned thisvalue (default is Inf)
See Alsoquadtri
7.4.34 spline
Does a cubic spline interpolation of a data set.
Syntax Description
out = spline(Ex,xold,xnew); Cubic spline interpolation of a 1D function. Ex is existing dataxold specifies the points where Ex is sampledxnew specifies new point to interpolate the data.
The xnew does does not have to be within the bounds ofxold.
See Also Functions , interp157 171
Scripting Language 173
© 2003 - 2013 Lumerical Solutions, Inc
7.4.35 integrate
Returns the integral over the specified dimension of a matrix.
Integrals over singleton dimensions will return zero (i.e. the area under a single point iszero). See integrate2 for an alternate behavior.
Syntax Description
out = integrate(A, n, x1); Integrates A over the nth dimension in the matrix. x1 is the corresponding position vector for that dimension.
out = integrate(A, d, x1,x2, ...);
Calculates the integral of A over the specified list ofdimension(s) d.d is a vector containing the dimensions over which tointegrate.xi are the position vectors corresponding to the dimensionsof A over which the integration is occurring. For example
power = integrate(A,1:2,x,y) will integrate A over an x-ysurface.
See Also Functions , integrate2 , max , min , interp , find , pinch , round ,getdata , sum , length
7.4.36 integrate2
Very similar to the standard integrate function, except that singleton dimensions areignored.
As described in the integrate function description, integrating over dimensions with a singlevalue (singleton dimensions) returns zero because the area under a single point is zero. Insome cases, particularly when you are not sure which dimensions are singleton, thisbehavior can cause difficulties. The integrate2 function automatically ignores alldimensions with a size of one, which avoids the problem of a zero valued integrals due tosingleton dimensions.
Syntax Description
out = integrate2(A, 1, x1); Integrates A over the first dimension in the matrix. x1 is the corresponding position vector.
out = integrate2(A, d, x1, x2,...);
Calculates the integral of A over the specified dimension(s)d.
157 173 168 168 171 174 167 189
269 167 166
Reference Guide174
© 2003 - 2013 Lumerical Solutions, Inc
d is a vector containing the dimensions over which tointegrate.xi is the position vector corresponding to the dimensions ofA over which the integration is occurring. If any of the xivectors only have 1 element, integrate returns 0.For example
power = integrate2(A,1:2,x,y) will integrate A over an x-ysurface.
See Also Functions , integrate , max , min , interp , find , pinch , round ,getdata , sum , length
7.4.37 find
This function will search for entries in a matrix that meet some condition. The indices ofthose values are returned.For multi-dimensional matrixes, the find function will still return a single index. This isuseful 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 closestvalue to 5e-6.
out = find(x>5); Will return indices of all values of x that are greater than 5.
See AlsoFunctions , pinch , findpeaks , integrate , length , size , mod ,meshgrid3dx , meshgrid3dy , meshgrid3dz
7.4.38 findpeaks
Returns the position of peaks in a matrix. A peak is defined as a data point that is largerthan 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 inthe data, a value of 1 is returned.
findpeaks(y,n); Returns a matrix containing the positions of the largest npeaks found in the data. The returned values are ordered
157 173 168 168 171 174 167 189
269 167 166
157 167 174 173 166 166 189
135 135 136
Scripting Language 175
© 2003 - 2013 Lumerical Solutions, Inc
from largest to smallest. The returned matrix is always ofdimension nX1. If less than n peaks are found, theremaining values of the returned matrix are 1.
See AlsoFunctions , find
7.4.39 transpose
Transpose a 1D or 2D matrix.
Syntax Description
y = transpose(x); If x is an N x M matrix, then y will be M x N, where theentries are y(j,i)=x(i,j).
See AlsoFunctions , ctranspose , reshape , flip , permute , size
7.4.40 ctranspose
Transpose a 1D or 2D matrix and take the complex conjugate of each element.
Syntax Description
y = ctranspose(x); If x is an N x M matrix, then y will be M x N, where the
entries are y(j,i)=x(i,j)*.
See AlsoFunctions , transpose
7.4.41 num2str
Convert an integer, floating point number, or matrix into a string. Use the format scriptcommand 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 or2D matrix.
See AlsoOperators , " , + , ? , endl , write , format ,str2num , findstring ,replace , replacestring , substring , eval
157 174
157 175 170 170 170 166
157 175
148 155 150 157 157 123 121 176 177
177 178 176 176
Reference Guide176
© 2003 - 2013 Lumerical Solutions, Inc
7.4.42 str2num
Convert a string into a floating point number. Use the format script command to change theprecision of the output.
Syntax Description
out = str2num(string); Converts string into a number.
See AlsoOperators , " , + , ? , endl , write , format , findstring , replace ,replacestring , substring
7.4.43 eval
Execute string containing Lumerical scripting language.
Syntax Description
eval(string); Execute string containing Lumerical scripting language atthe Lumerical script prompt.This function does not return any data.
See AlsoOperators , feval , str2num , num2str
7.4.44 feval
Evaluates a string as script file. This function is useful for running script files that are not inyour path and files with spaces in the name.
Syntax Description
feval(filename); Execute string containing the name of a script file at theLumerical script prompt.This function does not return any data.
See AlsoOperators , eval , str2num , num2str
7.4.45 substring
Can be used to extract a substring from a string.
Syntax Description
148 155 150 157 157 123 121 177 177
178 176
148 176 176 175
148 176 176 175
Scripting Language 177
© 2003 - 2013 Lumerical Solutions, Inc
s1 = substring(s,pos); Returns a substring of s, starting at position pos to the endof s. The position pos can be 1 to length(s).
s1 = substring(s,pos,len); Returns a substring of s, starting at position pos, with lencharacters. If len is -1 (or any value less than 0) it returnsthe substring at position pos to the end of s. The defaultvalue of len is -1.
See AlsoFunctions , length , findstring , replace , replacestring , str2num , num2str
, splitstring
7.4.46 findstring
Returns the position of a given substring in a string.
Syntax Description
pos = findstring(s,s1); Returns the position of the first instance substring s1 in s.If s1 is not found in s, it returns -1.
pos = findstring(s,s1,p0); Returns the position of the first instance substring s1 in s,starting at position p0. If s1 is not found in s, starting fromp0, it returns -1.
See AlsoFunctions , length , substring , replace , replacestring , str2num , num2str
, splitstring
7.4.47 replace
Replaces a substring of a string with a new string.
Syntax Description
snew = replace(s,pos,len,s1);
Replaces len characters of s, starting at position pos, withthe string in s1. If len is 0, it will insert the string s1between pos-1 and pos. If len is -1 (or any values less than0) it will replace all remaining characters in s with s1,starting at pos. The position pos can be 1 to length(s).
See AlsoFunctions , length , substring , findstring , replacestring , str2num ,num2str , splitstring
157 166 177 177 178 176
175 178
157 166 176 177 178 176
175 178
157 166 176 177 178 176
175 178
Reference Guide178
© 2003 - 2013 Lumerical Solutions, Inc
7.4.48 replacestring
Replaces a substring of a string with a new string.
Syntax Description
snew = replacestring(s,s1,s2);
Replaces all instances of s1 in s with s2.
See AlsoFunctions , length , substring , findstring , replace , str2num , num2str ,splitstring
7.4.49 splitstring
Split a long string into a series of substrings, where the substrings are stored in a cell (ie.string) array.
Syntax Description
S2 = splitsting(S1,endl); Split the string S1 into a series of strings, using the end ofline character as the delimiter between strings. S2 is acell array.
See AlsoFunctions , length , substring , findstring , replace , str2num , num2str ,cell , dir , getresult
7.4.50 fft
Compute the 1D, 2D or 3D Fast Fourier Transform (fft) of a matrix. In the 1D case thetransform is given by
)1)(1)(2
(
1
][)(][mn
N
iN
nxxw enEEfftmE
The fft, inverse fft and all associated functions have an option (option 1 below) that controlsthe format used to store the frequency domain data. When working with spectral data it isnot 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 alsouse option 1=n if you want to pass that same spectral data to invfft. Similarly, if you useoption 1=n for fft, then you also need to use option 1=n with fftw to get the proper frequencyvector corresponding to your spectrum. invfft and fftk work in the same way.
157 166 176 177 177 176 175
178
157 166 176 177 177 176 175
147 114 270
Scripting Language 179
© 2003 - 2013 Lumerical Solutions, Inc
Syntax Description
out = fft(Ex); Returns the fast Fourier transform of Ex. Ex can be 1D, 2Dor 3D.
out = fft(Ex,option1,option2);
option1 This option controls the format used to store the frequencydomain data. The options are:
1 : the standard fft (zero frequency is at the first elementof the matrix). 2 : zero frequency is the first element, but only data upto and including the Nyquist frequency is stored. Thisoption is only useful for real valued, 1D time/spatialsignals.3 : the fft is shifted so zero frequency is the centralelement of the spectrum (precisely, this means the zerofrequency point is at element floor(N/2 + 1), where N isthe number of samples).
option2 This option is either a 1, 2 or 3 element vector dependingon whether Ex is 1D, 2D or 3D. For each dimension,specify a value of either 0, 1 or N to obtain the desired 0padding options.
0: no zero padding1: zero padding up to the next power of 2 longer than thelength of Ex (default)N: zero pad up to length N if N > length(Ex), wherelength of Ex is the length in a specific dimension. If N <=length(Ex), it will zero pad up to the next power of 2longer than the length of Ex. For the fastest results, Nshould be a power of 2 and can be entered, for example,as 2 12.
Note: FFT ConventionsThere are different, but equivalent conventions for defining Fourier transforms. Lumericaldefines 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 theforward FFT and a positive sign in the exponential for the inverse FFT. To convert betweenthe different FFT conventions, switch the invfft and fft and rescale the results. For a signaly with N elements this can be done as follows:
Reference Guide180
© 2003 - 2013 Lumerical Solutions, Inc
Lumerical MATLAB
fft(y,1,0)invfft(y,1,0)
ifft(y)*N fft(y)/N
See Also Functions , invfft , fftw , fftk , czt
7.4.51 fftw
Returns the angular frequency vector corresponding to time vector t.
)1(,,02
)( MMdt
tfftww
,where M=length(t).
fftw and all related functions have an option (option 1 below) that controls the format used tostore the frequency domain data. When working with spectral data it is not possible toswitch between formats; there are no functions to convert between formats. This impliesthat if you use option 1=n to produce a spectrum with fft, then you must also use option1=n if you want to pass that same spectral data to invfft. Similarly, if you use option 1=nfor fft, then you also need to use option 1=n with fftw to get the proper frequency vectorcorresponding to your spectrum. Invfft and fftk work in the same way.
Syntax Description
out = fftw(t); Returns the angular frequency vector corresponding to timevector t.
fftw(t,option1,option2); Option1 1 : the standard fft (default) 2 : frequencies above the Nyquist frequency areremoved 3 : the fft is shifted so both positive and negativefrequencies are seen
Option20: no zero padding1: zero padding up to the next power of 2 longer than thelength of Ex (default)N: zero pad up to length N if N > length(t). If N <= length(t), it will zero pad up to the next power of 2 longer thanthe length of t. For the fastest results, N should be apower of 2 and can be entered, for example, as 2 12.
157 182 180 181 183
Scripting Language 181
© 2003 - 2013 Lumerical Solutions, Inc
See Also Functions , fft , fftk , invfft
7.4.52 fftk
Returns the spatial wavevector kx associated with a fourier transform of a function of x.
)1(,,02
)( MMdx
xfftkk
,where M=length(x).
fftk and all related functions have an option (option 1 below) that controls the format used tostore the frequency domain data. When working with spectral data it is not possible toswitch between formats; there are no functions to convert between formats. This impliesthat if you use option 1=n to produce a spectrum with fft, then you must also use option1=n if you want to pass that same spectral data to invfft. Similarly, if you use option 1=nfor fft, then you also need to use option 1=n with fftw to get the proper frequency vectorcorresponding to your spectrum. Invfft and fftk work in the same way.
Syntax Description
out = fftk(x); Returns the spatial wavevector kx associated with a fouriertransform of a function of x..
fftk(x,option1,option2); Option1 1 : the standard fft (default) 2 : frequencies above the Nyquist frequency areremoved 3 : the fft is shifted so both positive and negativefrequencies are seen
Option20: no zero padding 1: zero padding up to the next power of 2 longer than thelength of Ex (default)N: zero pad up to length N if N > length(x). If N <= length(x), it will zero pad up to the next power of 2 longer thanthe length of x. For the fastest results, N should be apower of 2 and can be entered, for example, as 2 12.
See Also Functions , fft , fftw , invfft
157 178 181 182
157 178 180 182
Reference Guide182
© 2003 - 2013 Lumerical Solutions, Inc
7.4.53 invfft
Compute the 1D,2D or 3D inverse Fast Fourier Transform (fft) of a matrix. In the 1D casethe transform is given by
)1)(1)(2
(
1
][1
)(][mn
N
iN
nwwx enE
NEinvfftmE
The inverse fft, fft and all related functions have an option (option 1 below) that controls theformat used to store the frequency domain data. When working with spectral data it is notpossible to switch between formats; there are no functions to convert between formats. Thisimplies that if you use option 1=n to produce a spectrum with fft, then you must also useoption 1=n if you want to pass that same spectral data to invfft. Similarly, if you use option1=n for fft, then you also need to use option 1=n with fftw to get the proper frequency vectorcorresponding 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 can1D,2D or 3D.
invfft(x,option1,option2); option1 This option controls the format used to store the frequencydomain data. The options are:
1 : the standard fft (zero frequency is at the first elementof the matrix). 2 : zero frequency is the first element, but only data upto and including the Nyquist frequency is stored. Thisoption is only useful for real valued, 1D time/spatialsignals.3 : the fft is shifted so zero frequency is the centralelement of the spectrum (precisely, this means the zerofrequency point is at element floor(N/2 + 1), where N isthe number of samples).
option2 This option is either a 1, 2 or 3 element vector dependingon whether Ex is 1D, 2D or 3D. For each dimension,specify a value of either 0, 1 or N to obtain the desired 0padding options.
0: no zero padding1: zero padding up to the next power of 2 longer than thelength of Ex (default)N: zero pad up to length N if N > length(Ex), where
Scripting Language 183
© 2003 - 2013 Lumerical Solutions, Inc
length of Ex is the length in a specific dimension. If N <=length(Ex), it will zero pad up to the next power of 2longer than the length of Ex. For the fastest results, Nshould be a power of 2 and can be entered, for example,as 2 12.
See Also Functions , fft , fftw , fftk
7.4.54 czt
Returns the chirped z-transform of a set of data. The czt function is often more convenientthan the standard fft functions because you can specify an arbitrary range of k.
2,1
]2[]2[]1[]1[
][][
]2,1[)2,1,2,1,(]2,1[
][),,(][
nn
mknixmknixxxk
n
mknixxxk
ennEkkxxEcztmmE
enEkxEcztmE
Syntax Description
out = czt(Ex,t,w) Returns the chirped z-transform of Ex, function of t, ateach desired angular frequency w. Note that w must be alinearly spaced set of angular frequencies but can coverany range.
czt(Ex,x,y,kx,ky); The two dimensional chirped z-transform. kx and ky mustbe linearly spaced sets of wavenumbers but can cover anyrange.
See Also Functions , fft
7.4.55 polyarea
Returns the area of a polygon. The area is positive if the vertices are defined in a counter-clockwise direction, and negative if the vertices are defined in a clockwise direction.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N>= 3. The second dimension represents the x,y positions. For example, a valid polygon isV = [ 0,0; 1,0; 1,1; 0,1];
Syntax Description
157 178 180 181
157 178
Reference Guide184
© 2003 - 2013 Lumerical Solutions, Inc
out = polyarea(V); Returns the area of V. The sign of the area indicates if V isdefined in a counter-clockwise (positive) or clockwise(negative) direction.
See Also Functions , centroid , polyintersect , inpoly , polygrow , polyand , polyor
, polydiff , polyxor
7.4.56 centroid
Returns the center of mass of a polygon.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N>= 3. The second dimension represents the x,y positions. For example, a valid polygon isV = [ 0,0; 1,0; 1,1; 0,1];
Syntax Description
out = centroid(V); Returns the center of mass of V, assuming uniformdensity. The output is a 2x1 matrix representing the x andy positions.
See Also Functions , polyarea , polyintersect , inpoly , polygrow , polyand , polyor
, polydiff , polyxor
7.4.57 polyintersect
Determines if two polygons intersect.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N>= 3. The second dimension represents the x,y positions. For example, a valid polygon isV = [ 0,0; 1,0; 1,1; 0,1];
Syntax Description
out = polyintersect(V1,V2); Returns0 if the polygons do not overlap0.5 if the polygons touch1 if they overlap2 if one polygon completely encloses the other
See Also Functions , polyarea , centroid , inpoly , polygrow , polyand , polyor ,
157 184 184 185 185 186
186 186 187
157 183 184 185 185 186
186 186 187
157 183 184 185 185 186 186
Scripting Language 185
© 2003 - 2013 Lumerical Solutions, Inc
polydiff , polyxor
7.4.58 inpoly
Determines if a point is inside our outside a polygon. The function is vectorized so it can beused to create a mesh of a polygon.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N>= 3. The second dimension represents the x,y positions. For example, a valid polygon isV = [ 0,0; 1,0; 1,1; 0,1];
Syntax Description
out = inpoly(V,x,y); Returns a matrix of the same dimension of x with 1 if thecorresponding point is inside the polygon and 0 otherwise.The matrices x and y must have the same length, or one ofthem can be a singleton.
See Also Functions , polyarea , centroid , polyintersect , polygrow , polyand , polyor
, polydiff , polyxor
7.4.59 polygrow
Returns a polygon that has grown or shrunk by the specified amount. The polygon is grownin a direction normal to every line segment.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N>= 3. The second dimension represents the x,y positions. For example, a valid polygon isV = [ 0,0; 1,0; 1,1; 0,1];
Syntax Description
out = plygrow(V,dx); Returns a new polygon that has grown by dx. To shrink apolygon, use dx < 0.
See Also Functions , polyarea , centroid , polyintersect , inpoly , polyand , polyor
, polydiff , polyxor
186 187
157 183 184 184 185 186
186 186 187
157 183 184 184 185 186
186 186 187
Reference Guide186
© 2003 - 2013 Lumerical Solutions, Inc
7.4.60 polyand
Combines two polygons into one using a boolean and operation.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N>= 3. The second dimension represents the x,y positions. For example, a valid polygon isV = [ 0,0; 1,0; 1,1; 0,1];
Syntax Description
V3 = polyand(V1,V2); Returns a new polygon, V3, that is the and of V1 and V2.
See Also Functions , polyor , polydiff , polyxor , polyarea , centroid , polyintersect
, inpoly , polygrow
7.4.61 polyor
Combines two polygons into one using a boolean or operation.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N>= 3. The second dimension represents the x,y positions. For example, a valid polygon isV = [ 0,0; 1,0; 1,1; 0,1];
Syntax Description
V3 = polyor(V1,V2); Returns a new polygon, V3, that is the or of V1 and V2.
See Also Functions , polyand , polydiff , polyxor , polyarea , centroid , polyintersect
, inpoly , polygrow
7.4.62 polydiff
Combines two polygons into one by taking the difference.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N>= 3. The second dimension represents the x,y positions. For example, a valid polygon isV = [ 0,0; 1,0; 1,1; 0,1];
Syntax Description
V3 = polydiff(V1,V2); Returns a new polygon, V3, that is V1-V2.
See Also Functions , polyand , polyor , polyxor , polyarea , centroid , polyintersect
157 186 186 187 183 184
184 185 185
157 186 186 187 183 184
184 185 185
157 186 186 187 183 184
Scripting Language 187
© 2003 - 2013 Lumerical Solutions, Inc
, inpoly , polygrow
7.4.63 polyxor
Combines two polygons into one using a boolean xor operation.
The polygon vertices are contained in a single matrix of dimension Nx2 (or 2xN) where N>= 3. The second dimension represents the x,y positions. For example, a valid polygon isV = [ 0,0; 1,0; 1,1; 0,1];
Syntax Description
V3 = polyxor(V1,V2); Returns a new polygon, V3, that is the xor of V1 and V2.
See Also Functions , polyand , polyor , polydiff , polyarea , centroid , polyintersect
, inpoly , polygrow
7.4.64 lineintersect
Returns the intersection points of lines in the x-y plane. Note that the intersection pointdoes not have to lie on the line segments themselves that define the lines. To see if the linesegments actually cross the command linecross should be used.
Line segments are contained in a single matrix of dimension 2*Nx2, where there are N linesegments. For example, the matrix L = [ 0,0; 1,1; 0,0, 0,1]; represents 2 lines segments,one from (0,0) to (1,1) and another from (0,0) to (0,1).
Syntax Description
out = lineintersect(L1,L2); Returns the intersection of the lines represented by thesegments in L1 and L2. L1 and L2 must have the samesize (2*N,2 for N line segments). The result is a sequenceof x,y points in the form Nx2 representing the intersectionsof the N lines. There are special cases when
The lines are parallel. In this case, the position returnedis (1.#INF,b). The value of 1.#INF can be tested for usingthe script commands finite. The value of b is 0 if the linesare not coincident and 1 if they are coincident.The points in a segment are degenerate, ie the same. Inthis case, the position returned is (1.#INF,b), where b is0, 1, 2 if the both line segments are degenerate, the firstis degenerate, or the second is degenerate respectively.
184 185 185
157 186 186 186 183 184
184 185 185
Reference Guide188
© 2003 - 2013 Lumerical Solutions, Inc
See Also Functions , linecross , finite
7.4.65 linecross
Determines if line segments cross each other.
Line segments are contained in a single matrix of dimension 2*Nx2, where there are N linesegments. For example, the matrix L = [ 0,0; 1,1; 0,0, 0,1]; represents 2 lines segments,one from (0,0) to (1,1) and another from (0,0) to (0,1).
Syntax Description
out = linecross(L1,L2); Returns a matrix of dimension N which determines if the Nline segments in L1 and the N line segments in L2 cross.L1 and L2 must have the same size (2*Nx2 for N linesegments). The result is a matrix of length N that is 0 ifthe segments do not cross, 1 if they cross and 0.5 if theendpoint of one line touches another. Line segments thatare coincident and touch also return a value of 0.5
See Also Functions , lineintersect , finite
7.4.66 ceil
The ceil command rounds the input to the nearest integer greater than or equal to itself.
Syntax Description
out = ceil(X); Returns the nearest integer greater than or equal to X.
See AlsoFunctions , floor , mod
7.4.67 floor
The floor command rounds the input to the nearest integer less than or equal to itself.
Syntax Description
out = floor(X); Returns the nearest integer less than or equal to X.
See AlsoFunctions , ceil , mod
157 188 191
157 187 191
157 188 189
157 188 189
Scripting Language 189
© 2003 - 2013 Lumerical Solutions, Inc
7.4.68 mod
Modulus after division.
Syntax Description
out = mod(X,Y); Returns X - n.*Y where n = floor(X./Y) if Y is not equal to 0.The input X must be a real array or a real scalar. Y mustbe a real scalar.The following are true by convention:mod(X,0) = Xmod(X,X) = 0
See AlsoFunctions , floor , ceil
7.4.69 sign
Get the sign of a number.
Syntax Description
out = sign(data); Real valuessign = 0 for data=0sign = 1 for data>0sign =-1 for data<0
Complex valuessign = 0 for data=0+0isign = data/abs(data) for data!=0
See AlsoFunctions , floor , ceil
7.4.70 round
Rounds a number to the nearest integer.
Syntax Description
out = round(x); Rounds x to the nearest integer.
See AlsoFunctions
157 188 188
157 188 188
157
Reference Guide190
© 2003 - 2013 Lumerical Solutions, Inc
7.4.71 rand
Generate a uniform random number between 0 and 1.
Syntax Description
out = rand; Generates a uniform random number between 0 and 1.
out = rand(min,max); Generates a random number between min and max. Bydefault, min and max are 0 and 1 respectively.
out = rand(min,max,option); option = 1: output is a double precision number betweenmin and max (default)option = 2: output is an integer between min and max.
See AlsoFunctions , randreset , randmatrix
7.4.72 lognrnd
Generate a lognormal distributed random number. This command is available inINTERCONNECT only.
Syntax Description
out = lognrnd (mean,stddev); Generates a lognormal distributed random number withuser defined mean value and standard deviation.
See AlsoFunctions , randreset , randn
7.4.73 randn
Generate a normally distributed random number. This command is available inINTERCONNECT only.
Syntax Description
out = randn; Generates a normally distributed random number withmean 0 and standard deviation 1.
out = randn(mean,stddev); Generates a normally distributed random number with userdefined mean value and standard deviation.
See AlsoFunctions , randreset , lognrnd , randnmatrix
157 191 133
157 191 190
157 191 190 134
Scripting Language 191
© 2003 - 2013 Lumerical Solutions, Inc
7.4.74 randreset
Resets the random number generator seed.
Syntax Description
out = randreset; Resets the random number seed based on the clock time.This function returns the random number seed that wasused.
out = randreset(seed); Set the seed to a specific value
See AlsoFunctions , rand , randmatrix
7.4.75 finite
The finite command returns 1 (true) if a value is finite. Numbers such as NaN or #1.INFreturn 0 (false).
Syntax Description
out = finite(x); Returns a matrix of the same size as x. The values are 1for values of x that are finite and 0 for values that are NaN.For example, finite(1/0) returns 0.
See AlsoFunctions
7.4.76 solar
Returns the solar power spectrum, in Watts/meter 2/meter. This command is available inFDTD and DEVICE.
The values are based on the global tilt values from the following link:http://rredc.nrel.gov/solar/spectra/am1.5/ASTMG173/ASTMG173.html
Syntax Description
out = solar(1); Returns the power of the solar spectrum as a function ofwavelength, in W/m 2/m
out = solar(0); Returns the corresponding wavelength vector, in m
See Also plot , integrate
157 190 133
157
198 173
Reference Guide192
© 2003 - 2013 Lumerical Solutions, Inc
7.4.77 stackrt
Analytically calculates the reflection and transmission of a plane wave through a multi-layerstack. This function returns the fraction of transmitted and reflected power (Ts, Tp, Rs,Rp), and the complex reflection and transmission coefficients (ts, tp, rs, rp), for both S andP polarizations. All results are returned in a single dataset as a function of frequency andincidence angle (optional).
Note: Thickness of first and last layerIt is necessary to specify the thickness of each layer, including the first and last layers. Often, a thickness of zero can be used for these layers, meaning the results will becalculated just beyond the first and last interface. If a larger value is used, the results willbe calculated further from the interface. For non-lossy materials, this will not effect thereflected and transmitted power, but it will change phase of the complex coefficients.
Syntax Description
RT = stackrt(n,d,f); Arguments for a stack with Nlayers:n: Refractive index of each layer. Size is either Nlayers, orNlayers x length(f) if dispersive materials are involved.d: Thickness of each layer. Size is Nlayers. f: Frequency vector.
RT = stackrt(n,d,f,theta); theta: Angle vector, in degrees. Optional.
See Also Functions
7.4.78 mean
The mean value in a matrix is returned.
Syntax Description
out = max(a); The mean value of the matrix a is returned.
See Alsomax , min , abs , sum
7.4.79 all
The script command returns 1 if all of the specified matrix entries are nonzero and returns 0otherwise.
Syntax Description
157
168 168 164 167
Scripting Language 193
© 2003 - 2013 Lumerical Solutions, Inc
out = all(A); Will return 1 if all of the A matrix entries are nonzero andwill return 0 otherwise.
See Alsoany , almostequal
7.4.80 any
The script command returns 1 if any of the specified matrix entries are nonzero and returns0 otherwise.
Syntax Description
out = any(A); Will return 1 if any of the A matrix entries are nonzero andwill return 0 otherwise.
See Alsoall , almostequal
7.4.81 var
The script command returns the variance of all entries of the matrix specified, wherevariance is defined as,
N
iiN
x1
2
)(1
var
Syntax Description
out = var(A); Will return variance of all of matrix A, over all dimensions.
See Alsostd , mean
193 151
192 151
194 192
Reference Guide194
© 2003 - 2013 Lumerical Solutions, Inc
7.4.82 std
The script command returns the standard deviation of the all entries of the matrix specified,where standard deviation is defined as,
N
iiN
x1
2
)(1
Syntax Description
out = std(A); Will return standard deviation of matrix A, over alldimensions.
See Alsovar , mean
7.4.83 mapfind
The script command returns the nearest value from a file containing a map of values to astring. It returns the string value located at the specified nearest point.
Syntax Description
out = mapfind (filename,x,y); Find the nearest value from a file containing a map ofvalues to a string. It l returns the string value located at thenearest point (x,y).
out = mapfind (filename,x,y,z);
Find the nearest value from a file containing a map ofvalues to a string. It returns the string value located at thenearest point (x,y,z).
out = mapfind (filename,x,y,z,w);
Find the nearest value from a file containing a map ofvalues to a string. It returns the string value located at thenearest point (x,y,z,w).
See Alsoreaddata , readdata
193 192
122 122
Scripting Language 195
© 2003 - 2013 Lumerical Solutions, Inc
7.4.84 quadtri
The script command approximates integration (first order quadrature) of data on a 2D finiteelement mesh.
Syntax Description
out = quadtri(tri,vtx,u); outputs a scalar, the integral of u on the finite elementmesh, where
tri: the connectivity array, Mx3, containing row entriesthat index the three vertices of M trianglesvtx: the vertex array, Nx2, containing row entries of (x,y)pairsu: the data on the finite element mesh (Nx1)
See Alsointerptri
7.4.85 expand
The script command returns the expansion coefficients between two arbitrary DFTmonitors. Typically, the reference monitor contains the modal fields for the expansion.
*11
*22
2
1*2
2
*21
2
1*2
2
*21
*5.0
*5.0
*25.0
*25.0
HESdP
HESdN
N
HESd
N
HESdb
N
HESd
N
HESda
For more detail on how to use this command, and how to interpret the results, please see Using Mode Expansion Monitors.
Syntax Description
expand('a','a_ref',x,y,z); outputs the expansion coefficients between the fields oftwo monitors
172
Reference Guide196
© 2003 - 2013 Lumerical Solutions, Inc
a: the monitor name, of which expansion is performed a_ref: the reference monitorx/y/z: the displacement from the monitor a from thereference monitor a_ref
See AlsoAdding Objects , Using Mode Expansion Monitors, setexpansion , removeexpansion
, expand2
7.4.86 norm
The script command returns the natural norm induced by the L2-norm (Spectral Norm).
Syntax Description
out = norm(y); Returns y to the L2-norm, y is a matrix.
See AlsoFunctions
7.5 Loop and conditional statementsThe scripting language currently supports FOR loops and IF statements. Other controlstructures such as while loops or case statements must be constructed from these.
Command Description
for For loop.
if If statement.
while A for loop must be used. See the for loop section.
7.5.1 for
for loops allow some operations to be repeated a number of times. A while loop can beimplemented 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 valueof 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
205 262
263
157
196
197
196
Scripting Language 197
© 2003 - 2013 Lumerical Solutions, Inc
} 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 executewhile x<10.
See Also Loops , if
7.5.2 if
The scripting language supports if statements in the following forms:
Syntax Description
if(x < 5) { y = x 2; } Simple if statement on one line.
if(x < 5) { y = x 2; }
Multi-line if statement
if(x < 5) { y = x 2; } else { y = x 3; }
If else statement.
if(x < 5) { if(x > 0) {y = x 2; } } else { y = x 3; }
Nested if statement with else.
See Also Loops , for
7.6 Plotting commandsLine and image plots are supported. These figures can be exported to jpeg images.
Plotting functions
Command Description
196 197
196 196
Reference Guide198
© 2003 - 2013 Lumerical Solutions, Inc
plot Makes line plots.
plotxy Makes line plots, when data sets are sampled atdifferent position vectors.
polar Makes polar plots.
polar2 Makes polar plots, when data sets are sampled atdifferent position vectors.
polarimage Makes a 2D polar image plot.
histc Makes a histogram plot.
legend Makes a legend on a figure with line plots.
image Makes 2D image plots.
setplot Sets figure properties.
visualize Pass in simulation data to the visualizer.
vectorplot Makes vector plots.
Miscellaneous plotting functions
Command Description
selectfigure Selects a figure.
exportfigure Exports a figure.
closeall Closes all figure windows.
7.6.1 plot
Create line plots. All data sets must be sampled on the same position vector.
See plotxy for data sets that are sampled on different position vectors.
Syntax Description
out = plot(x,y); Creates a plot of y vs x, y and x are both 1D vectors withthe 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)
198
199
200
200
201
202
202
202
204
203
205
204
204
205
Scripting Language 199
© 2003 - 2013 Lumerical Solutions, Inc
plot(x,y1,y2,y3); Creates a plot with 3 curves, x,y1, y2, y3 must be thesame 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, returnsthe figure number.
plot(x,y, "x label", "y label","title", "options");
Creates a plot with desired options. Options can be be log10x, log10y, loglogplot points greyscalepolar (same as the polar script command)any comma separated list of the above, for example"log10x,greyscale"
Returns the figure number.
See Also Plotting commands , plotxy , legend , image , closeall , setplot ,exportfigure , visualize , vectorplot , polar
7.6.2 plotxy
Create line plots. In particular, this function is used when the data sets are sampled ondifferent position vectors.
Syntax Description
out = plotxy(x,y); Creates a plot of y vs x, y and x are both 1D vectors withthe same length. The figure number is returned.
plotxy(x1,y1,x2,y2,xn,yn); Creates a plot with multiple curves. The xn-yn pairs musthave the same length, but x1, x2, and xn can have differentstart-end values and resolutions. It returns the figurenumber.
plotxy(x1,y1,x2,y2, "x label","y label", "title");
Creates line plots with axis labels and a title, returns thefigure number.
See Also Plotting commands , plot , legend , image , closeall , setplot , exportfigure
, visualize , vectorplot
197 199 202 202 205 204
204 203 205 200
197 198 202 202 205 204
204 203 205
Reference Guide200
© 2003 - 2013 Lumerical Solutions, Inc
7.6.3 polar
Create polar plots. All data sets must be sampled on the same position vector.
See polar2 for data sets that are sampled on different position vectors.
Syntax Description
out = polar(theta,rho) Creates a polar coordinate plot of the angle theta versusthe radius rho. theta is the angle from the x-axis to theradius vector specified in radians; rho is the length of theradius vector.
Theta and rho can be vectors of the same length, or if thelength of theta is n, then y can be a nxm matrix.
The figure number is returned.
polar(theta,rho1,rho2,rho3) Creates a plot with 3 curves, theta, rho1, rho2, rho3 mustbe the same length, returns the figure number.
polar(theta,rho,"x label", "ylabel", "title")
Creates a plot of y vs x with axis labels and a title, returnsthe figure number.
polar(theta,rho,"x label", "ylabel", "title", "options");
Creates a plot with desired options. Options can be be log10x, log10y, loglogplot points greyscalepolar (same as the polar script command)any comma separated list of the above, for example"log10x,greyscale"
Returns the figure number.
See Also Plotting commands , polar2 , legend , image , closeall , setplot ,exportfigure , polarimage , plot
7.6.4 polar2
Create polar plots. In particular, this function is used when the data sets are sampled ondifferent position vectors.
Syntax Description
out = polar2(theta,rho) Creates a polar coordinate plot of the angle theta versusthe radius rho. theta is the angle from the x-axis to the
197 200 202 202 205 204
204 201 198
Scripting Language 201
© 2003 - 2013 Lumerical Solutions, Inc
radius vector specified in radians; rho is the length of theradius vector.
Theta and rho can be vectors of the same length, or if thelength of theta is n, then y can be a nxm matrix.
The figure number is returned.
polar2(theta1,rho1,theta2,rho2)
Creates a plot with 2 curves. The two data sets can besampled on different theta vectors.
polar2(theta,rho,"x label", "ylabel", "title")
Creates a plot of y vs x with axis labels and a title, returnsthe figure number.
polar2(theta,rho,"x label", "ylabel", "title", "options");
Creates a plot with desired options. Options can be be log10x, log10y, loglogplot points greyscalepolar (same as the polar script command)any comma separated list of the above, for example"log10x,greyscale"
Returns the figure number.
See Also Plotting commands , polar , legend , image , closeall , setplot ,exportfigure , polarimage
7.6.5 polarimage
Create 2D polar image plots. This is typically used to plot far field data.
Syntax Description
polarimage(ux,uy,data); Creates a 2D image plot. If ux is of dimension N x 1, where ux goes from -1 to 1 uy is of dimension M x 1, where uy goes from -1 to 1 data must be of dimension N x M
out = image(ux,uy,data, "xlabel", "y label", "title");
Creates a 2D image plot with axis labelsOptionally returns the figure number.
image(ux,uy,data, "x label","y label", "title", "options");
Creates a 2D image plot with axis labels and options,options can be
logplot
See Also Plotting commands , plot , polar , image , closeall , setplot , exportfigure
197 200 202 202 205 204
204 201
197 198 200 202 205 204
Reference Guide202
© 2003 - 2013 Lumerical Solutions, Inc
, visualize , Near to far field projections
7.6.6 histc
The script command create a histogram plot.
Syntax Description
out = histc(y); Creates a histogram plot of y.Returns the figure number.
histc(y,n); Creates a histogram plot of y, using n bins.Returns the figure number.
histc (y,n, "x label", "ylabel", "title");
Creates a histogram plot of y, using n bins, with axislabels and a title.Returns the figure number.
See Also Plotting commands , histogram , legend , plot , closeall , visualize
7.6.7 legend
Add a legend to a line plot.
Syntax Description
legend("legend1","legend2",...,"legendn");
Adds a legend to the selected figure.This function does not return any data.
See Also Plotting commands , legend , plot , closeall , visualize
7.6.8 image
Create 2D image plots.
Syntax Description
out = image(x,y,z); Creates a 2D image plot. If x is of dimension N x 1 y is of dimension M x 1 z must be of dimension N x M
Returns the figure number.
204 203
197 134 202 198 205 203
197 202 198 205 203
Scripting Language 203
© 2003 - 2013 Lumerical Solutions, Inc
image(x,y,z, "x label", "ylabel", "title");
Creates a 2D image plot with axis labels, returns the figurenumber.
image(x,y,z, "x label", "ylabel", "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 , plot , closeall , setplot , exportfigure , visualize ,polarimage , vectorplot
7.6.9 visualize
Send data to the visualizer.
Syntax Description
visualize(R); Plots the dataset R in the Visualizer.
visualize("name", x,y,z, p1,"p1", p2,"p2", "a1",a1,"a2",a2);
Plots data on a spatial grid.name - Visualizer namex,y,z - spatial grid vectorsp1,"p1" - additional parameter vectors (vector, thenparameter name)."a1",a1 - data attributes (data name, then data matrix)
visualize("name", x,y,z, p1,"p1", p2,"p2", "a1",a1x,a1y,a1z);
Plot vector data "a1",a1x,a1y,a1z - data attributes (data name, then datamatrix X,Y,Z components)
visualize("name", p1,"p1", p2,"p2", "a1",a1x,a1y,a1z);
Plot data not attached to a spatial grid.
See Also Plotting commands , Datasets , exportfigure , image , plot , setplot ,closeall
197 198 205 204 204 203
201 205
197 141 204 202 198 204
205
Reference Guide204
© 2003 - 2013 Lumerical Solutions, Inc
7.6.10 selectfigure
Selecting a figure will show the figure on screen (give it focus). A warning will be generatedif the figure does not exist.
Syntax Description
selectfigure; Selects the last figure that was created.This function does not return any data.
selectfigure(1); Selects figure 1.
See Also Plotting commands , exportfigure , image , plot , setplot , closeall
7.6.11 setplot
Set figure properties.
Syntax Description
?setplot; Creates a string which lists all figure properties for thefigure that is currently selected. Unless the setfigure()command was called, the most recently created plot willbe selected.
setplot("property", "propertyvalue");
Set the desired property of the currently selected figure toproperty value.
See Also Plotting commands , image , plot , visualize
7.6.12 exportfigure
Exports the current figure to a JPG image. If the file extension is not specified, ".jpg" will beused. The image size will be the same as the figure window size.
If a file is overwritten, a warning will be generated. If an export fails, a warning will begenerated.
Syntax Description
exportfigure("filename"); Exports the current figure to a JPG image with the name"filename".The exported image will have the same size as the current
197 204 202 198 204 205
197 202 198 203
Scripting Language 205
© 2003 - 2013 Lumerical Solutions, Inc
figure.
exportfigure("filename",xres,yres);
Exports the current figure to a JPG image with the name"filename".The exported image will have the specified resolution, xres,yres, in the x,y directions respectively.
See Also Plotting commands , selectfigure , image , plot , setplot , closeall ,visualize
7.6.13 closeall
Close all open figure windows.
Syntax Description
closeall; Close all open figure windows.This function does not return any data.
See Also Plotting commands , plot , image
7.6.14 vectorplot
The script command vectorplot creates a vector plot from a rectilinear dataset. Therectilinear dataset must be a vector, like the E field, and it must have no additionalparameters (i.e. if you have E vs. x,y.z.f and f has 2 or more values, then the commandfails). Generally, it is easier to use visualize(E) and then select the vector plot option.
Syntax Description
vectorplot(E); Creates a vector plot of the dataset
See Also Plotting commands , plotxy , legend , image , closeall , setplot ,exportfigure , plot
7.7 Adding ObjectsThe following commands can be used to add objects. Objects are always added to thelocation specified by the groupscope variable. Please note that not all the commands areavailable for all products. Please refer to the table at the bottom of the page for eachcommand to see which products it applies to.
197 204 202 198 204 205
203
197 198 202
197 199 202 202 205 204
204 198
Reference Guide206
© 2003 - 2013 Lumerical Solutions, Inc
Simulation environment
Command Description
switchtolayout Closes the analysis window, deletes currentsimulation data and allows you to manipulatesimulation objects for a new simulation.
layoutmode Used to determine if the simulation file is open inlayout or in analysis mode.
groupscope Changes the group scope.
addgroup Adds a container group to the simulationenvironment.
addanalysisgroup Add an analysis group.
addobject Add an object from the object library.
addgridattribute Add a grid attribute object.
Structures
Command Description
addcircle Add a circle primitive.
addcustom Add a custom primitive.
addimport Add an import primitive.
addpyramid Add a pyramid primitive.
addpoly Add a polygon primitive
addrect Add a rectangle primitive.
addring Add a ring primitive.
addsphere Add a sphere primitive.
addsurface Add a surface primitive.
addstructuregroup Add a structure group.
Simulation region
Command Description
addfdtd Add an FDTD simulation area.
addeigenmode Adds a MODE simulation area.
208
209
226
209
210
210
220
211
211
211
212
212
212
213
213
214
209
214
214
Scripting Language 207
© 2003 - 2013 Lumerical Solutions, Inc
addpropagator Adds a propagator simulation object to the MODESolutions simulation environment.
addmesh Add a mesh override region.
adddevice Adds a DEVICE simulation area.
Sources
Command Description
adddipole Add a dipole source.
addgaussian Add a Gaussian source.
addplane Add a plane source.
addmode ; addmodesource Add a mode source.
addtfsf Add a TFSF source.
addimportedsource Add an imported source.
Monitors
Command Description
addindex Add an index monitor.
addeffectiveindex Add an effective index monitor.
addtime Add a time monitor.
addmovie Add a movie monitor.
addprofile Add a profile monitor.
addpower Add a power monitor.
addmodeexpansion Add a mode expansion monitor.
Create objects in Deck
Command Description
createbeam Creates a new Gaussian beam that is accessiblefrom the deck.
Simulation environment
Command Description
214
215
219
215
216
216
215 215
216
217
217
222
217
218
218
222
218
Reference Guide208
© 2003 - 2013 Lumerical Solutions, Inc
switchtolayout Closes the analysis window, deletes currentsimulation data and allows you to manipulatesimulation objects for a new simulation.
switchtodesign Switches INTERCONNECT to design mode.
layoutmode Used to determine if the simulation file is open indesign (layout) or in analysis mode.
designmode Returns true if the simulation is currently in designmode.
groupscope Changes the group scope.
Adding Elements
Command Description
addelement Adds an element from the INTERCONNECT elementlibrary.
Adding simulation objects
Command Description
adddope Add a constant doping region.
addcustomdoping Add a doping region with custom data.
adddiffusion Add a diffusion region.
addbulkgen Add a bulk generation region.
addimportdope Add an import primitive for a doping region.
addimportgen Add an import primitive for a generation region.
addcontact Add a contact to the electrical contacts table.
7.7.1 switchtolayout
Closes the analysis window and allows you to manipulate simulation objects for a newsimulation. If a simulation file is open in ANALYSIS mode, any commands to modifyobjects will return errors. You must switch to LAYOUT mode before modifying any objects.
Syntax Description
switchtolayout; Switches to LAYOUT mode.This function does not return any data.
208
209
226
221
219
219
220
219
220
210
Scripting Language 209
© 2003 - 2013 Lumerical Solutions, Inc
See AlsoAdding Objects , layoutmode
7.7.2 layoutmode
Used to determine if the simulation file is open in layout or in analysis mode.
Syntax Description
?layoutmode; Returns 1 if in layout mode, and 0 if in analysis mode.
See AlsoAdding Objects , switchtolayout , designmode
7.7.3 addgroup
Adds a container group to the simulation environment. This command is not available inINTERCONNECT.
Syntax Description
addgroup; Adds a container group to the simulation environment.This function does not return any data.
See AlsoAdding Objects , addtogroup , addstructuregroup , addanalysisgroup
7.7.4 addstructuregroup
Adds a structure group to the simulation environment. This command is not available inINTERCONNECT.
Syntax Description
addstructuregroup; Adds a structure group to the simulation environment.This function does not return any data.
See AlsoAdding Objects , addtogroup , adduserprop , addgroup , addanalysisgroup
205 209
205 208
205 230 209 210
205 230 231 209 210
Reference Guide210
© 2003 - 2013 Lumerical Solutions, Inc
7.7.5 addanalysisgroup
Adds an analysis group to the simulation environment. This command is not available inINTERCONNECT.
Note: It is not currently possible to add user defined Analysis Parameters or Results from ascript.
Syntax Description
addanalysisgroup; Adds an analysis group to the simulation environment.This function does not return any data.
See AlsoAdding Objects , addtogroup , adduserprop , addgroup , addstructuregroup
7.7.6 addobject
Adds a object from the object library.
This command is available in FDTD and MODE Solutions.
Syntax Description
addobject("script_ID"); Adds an object from the object library.This function does not return any data.
?addobject; Returns names of objects in the library.
See AlsoAdding Objects , addtogroup , adduserprop
7.7.7 addcontact
Adds a new contact to the electrical contact table. This command is available in DEVICEonly.
Syntax Description
addcontact; Adds a new contact to the electrical contact table.This function does not return any data.
See AlsoAdding Objects
205 230 231 209 209
205 230 231
205
Scripting Language 211
© 2003 - 2013 Lumerical Solutions, Inc
7.7.8 addcircle
Adds a circle primitive to the simulation environment. This command is not available inINTERCONNECT.
Syntax Description
addcircle; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.9 addcustom
Adds a custom primitive to the simulation environment. This command is available in FDTDand MODE.
Syntax Description
addcustom; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.10 addimport
Adds an import primitive to the simulation environment. This command is available in FDTDand MODE.
Syntax Description
addimport; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects
205
205
205
Reference Guide212
© 2003 - 2013 Lumerical Solutions, Inc
7.7.11 addpyramid
Adds a pyramid primitive to the simulation environment. This command is not available inINTERCONNECT.
Syntax Description
addpyramid; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.12 addpoly
Adds a polygon primitive to the simulation environment. This command is not available inINTERCONNECT.
Syntax Description
addpoly; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.13 addrect
Adds a rectangle primitive to the simulation environment.This command is not available inINTERCONNECT.
Syntax Description
addrect; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects
205
205
205
Scripting Language 213
© 2003 - 2013 Lumerical Solutions, Inc
7.7.14 addtriangle
Adds a 3 vertex, triangle shaped polygon primitive to the simulation environment. Thiscommand is not available in INTERCONNECT.
Syntax Description
addtriangle; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects , addpoly
7.7.15 addring
Adds a ring primitive to the simulation environment. This command is not available inINTERCONNECT.
Syntax Description
addring; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.16 addsphere
Adds a sphere primitive to the simulation environment. This command is not available inINTERCONNECT.
Syntax Description
addsphere; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects
205 212
205
205
Reference Guide214
© 2003 - 2013 Lumerical Solutions, Inc
7.7.17 addsurface
Adds a surface primitive to the simulation environment. This command is available in FDTDand MODE.
Syntax Description
addsurface; Adds primitive to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.18 addfdtd
Adds a FDTD simulation area to the simulation environment. This command is available inFDTD and MODE.
Syntax Description
addfdtd; Adds a simulation area to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.19 addeigenmode
Adds an eigenmode simulation object to the MODE Solutions simulation environment. Thiscommand is available in MODE only.
Syntax Description
addeigenmode; Add an eigenmode mode simulation region.
See AlsoAdding Objects
7.7.20 addpropagator
Adds a propagator simulation object to the MODE Solutions simulation environment. Thiscommand is available in MODE only.
Syntax Description
205
205
205
Scripting Language 215
© 2003 - 2013 Lumerical Solutions, Inc
addpropagator; Add a propagator mode simulation region.
See AlsoAdding Objects
7.7.21 addmesh
Adds a mesh override region to the simulation environment. This command is available inFDTD and MODE.
Syntax Description
addmesh; Adds a mesh override region to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.22 addmode
7.7.23 addmodesource
Adds a mode source to the simulation environment. This command is available in MODEonly.
Syntax Description
addmodesource; Adds source to the simulation environment.This function does not return any data.
See AlsoAdding Objects , addmode , updatesourcemode
7.7.24 adddipole
Adds a dipole source to the simulation environment. This command is available in FDTDand MODE.
Syntax Description
adddipole; Adds source to the simulation environment.This function does not return any data.
205
205
205 215 251
Reference Guide216
© 2003 - 2013 Lumerical Solutions, Inc
See AlsoAdding Objects
7.7.25 addgaussian
Adds a gaussian source to the simulation environment. This command is available in FDTDand MODE.
Syntax Description
addgaussian; Adds source to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.26 addplane
Adds a plane wave source to the simulation environment. This command is available inFDTD and MODE.
Syntax Description
addplane; Adds source to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.27 addtfsf
Adds a Total Field Scattered Field (tfsf) source to the simulation environment. Thiscommand is available in FDTD and MODE.
Syntax Description
addtfsf; Adds source to the simulation environment.This function does not return any data.
See AlsoAdding Objects
205
205
205
205
Scripting Language 217
© 2003 - 2013 Lumerical Solutions, Inc
7.7.28 addimportedsource
Adds an imported source to the simulation environment. This command is available inFDTD only.
Syntax Description
addimportedsource; Adds source to the simulation environment.This function does not return any data.
See AlsoAdding Objects , asapimport , asapload , asapexport
7.7.29 addindex
Adds an index monitor to the simulation environment. This command is available in FDTDand MODE.
Syntax Description
addindex; Adds monitor to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.30 addtime
Adds a time monitor to the simulation environment. This command is available in FDTD andMODE.
Syntax Description
addtime; Adds monitor to the simulation environment.This function does not return any data.
See AlsoAdding Objects
205 124 124 123
205
205
Reference Guide218
© 2003 - 2013 Lumerical Solutions, Inc
7.7.31 addmovie
Adds a movie monitor to the simulation environment. This command is available in FDTDand MODE.
Syntax Description
addmovie; Adds monitor to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.32 addprofile
Adds a profile monitor to the simulation environment. This command is available in FDTDand MODE.
Syntax Description
addprofile; Adds monitor to the simulation environment.This function does not return any data.
See AlsoAdding Objects
7.7.33 createbeam
Creates a new Gaussian beam that is accessible from the deck. This command is availablein MODE only.
Syntax Description
createbeam; Creates a Gaussian beam in the deck/global workspace.The Gaussian beam has the properties specified in theOverlap analysis->Beam tab of the analysis windowReturns the name of the Gaussian beam created, which isby default "gaussian#" (# being the total number ofGaussian beams existing in the current deck).
See AlsoAdding Objects
205
205
205
Scripting Language 219
© 2003 - 2013 Lumerical Solutions, Inc
7.7.34 adddevice
Adds a Device simulation region to the simulation environment. This command is onlyavailable in DEVICE.
Syntax Description
adddevice; Add a device simulation region.
See Also Adding Objects
7.7.35 adddope
Adds a region with constant doping to the simulation environment. This command is onlyavailable in DEVICE.
Syntax Description
adddope; Add a constant doping region.
See Also Adding Objects
7.7.36 adddiffusion
Adds a diffusion region to the simulation environment. This command is only available inDEVICE.
Syntax Description
adddiffusion; Add a diffusion region.
See Also Adding Objects
7.7.37 addimportdope
Adds a doping region to the simulation environment where the doping profile has been orwill be imported into DEVICE. This command is only available in DEVICE.
Syntax Description
addimportdope; Add an import primitive to define a doping region.
205
205
205
Reference Guide220
© 2003 - 2013 Lumerical Solutions, Inc
See Also Adding Objects
7.7.38 addbulkgen
Adds a bulk generation region to the simulation environment. This command is onlyavailable in DEVICE.
Syntax Description
addbulkgen; Add a bulk generation region.
See Also Adding Objects
7.7.39 addimportgen
Adds a generation region to the simulation environment where the generation profile hasbeen imported into DEVICE. This command is only available in DEVICE.
Syntax Description
addimportgen; Add an import primitive to define a generation region.
See Also Adding Objects
7.7.40 addgridattribute
Adds a grid attribute object to the simulation environment. See the Reference Guide Attributes page for more information. This command is only available in FDTD.
Syntax Description
addgridattribute(type); Adds a grid attribute object to the simulation.type: Type of attribute to add. Options are "lcorientation", "permittivity rotation", or "matrix transform".
addgridattribute(type,value,x,y,z);
Adds a grid attribute with spatially varying data.type: Type of attribute to add. Options are "lcorientation", "permittivity rotation", or "matrix transform".value: the attribute value. Depending on the attributetype, the value may be a scalar number (i.e.concentration), a 3 element vector (i.e. orientation), 9element tensor, etc. The size of the value matrix should
205
205
205
Scripting Language 221
© 2003 - 2013 Lumerical Solutions, Inc
be Nx X Ny X Nz X M… , where Nx, Ny, Nz are the sizesof the position vectors, and M is the size of the attributevalue (scalar, vector, tensors, etc). x,y,z: Vectors that specify the position where theattribute values are specified.
ExampleThe following script is an excerpt from LCD_twist.lsf in the Twisted Nematic LCD
application example which defines a spatially varying liquid crystal.# define x/y/zx = 0;y = 0;z = linspace(0e-6,5e-6,100);
X = meshgrid3dx(x,y,z);Y = meshgrid3dy(x,y,z);Z = meshgrid3dz(x,y,z);n = matrix(length(x),length(y),length(z),3);
# define the orientation functionn(1:length(x),1:length(y),1:length(z),1) = cos(Z*pi*1e5);n(1:length(x),1:length(y),1:length(z),2) = sin(Z*pi*1e5);n(1:length(x),1:length(y),1:length(z),3) = Z;
# add LC import grid attributeaddgridattribute("lc orientation",n,x,y,z-2.5e-6); # center atz=0setnamed("LC attribute","nz",50); # set resolution
See Also Adding Objects
7.7.41 addelement
Adds an element from the INTERCONNECT element library to the simulation environment.This command is only available in INTERCONNECT.
Syntax Description
addelement("element"); Adds an element from the element library.If no element name is given, this command will add acompound element by default.
205
Reference Guide222
© 2003 - 2013 Lumerical Solutions, Inc
7.7.42 addmodeexpansion
Adds a mode expansion monitor to the simulation environment. This command is availablein FDTD and MODE.
Syntax Description
addmodeexpansion; Adds a mode expansion monitor to the simulationenvironment.This function does not return any data.
See AlsoAdding Objects , Using Mode Expansion Monitors, setexpansion , removeexpansion
7.7.43 addeffectiveindex
Adds an effective index monitor to the simulation environment. This command is onlyavailable in MODE Solutions.
Syntax Description
addindex; Adds an effective index monitor to the simulationenvironment.This function does not return any data.
See AlsoAdding Objects
7.7.44 addchargemonitor
Adds a charge monitor to the simulation environment. This command is ONLY available inDEVICE.
Syntax Description
addchargemonitor; Adds a charge monitor to the simulation environment.
See AlsoAdding Objects , addpower, addfieldmonitor
205 262
263
205
205 223
Scripting Language 223
© 2003 - 2013 Lumerical Solutions, Inc
7.7.45 addfieldmonitor
Adds a charge monitor to the simulation environment. This command is ONLY available inDEVICE.
Syntax Description
addfieldmonitor; Adds a field monitor to the simulation environment.
See AlsoAdding Objects , addpower, addchargemonitor
7.8 Manipulating objectsPhysical structures, sources, monitors, and the simulation volume itself are consideredobjects. Objects generally have properties that can be modified.
Selecting and deleting objects
Command Description
groupscope Changes the group scope.
deleteall Deletes all objects in the current group scope.
delete Deletes the selected objects.
selectall Selects all objects in the current group scope.
unselectall Unselect all objects.
select Selects objects with a given name in the currentgroup scope.
selectpartial Selects any objects where partialname can be foundin the name, in the current TAB.
shiftselect The same as select("name"); but does not unselectcurrently selected objects. Can be used to selectmultiple objects.
shiftselectpartial The same as selectpartial("partialname"); but doesnot unselect currently selected objects. Can be usedto select multiple objects.
Moving and copying objects
Command Description
205 222
226
226
227
227
227
227
228
228
229
Reference Guide224
© 2003 - 2013 Lumerical Solutions, Inc
flipelement Flips an element in the schematic editor.
rotateelement Rotates and element in the schematic editor.
move Move an object.
copy Copy an object.
addtogroup Add an object/objects into a group.
Object properties
Command Description
adduserprop Add a user property to a structure group.
set Set a property of selected objects.
setnamed Set a property of any objects with a given name.
setcontact Set a property of an electrical contact.
setglobalmonitor Set global monitor properties.
setglobalsource Set global source properties.
setmodes Set mode labels.
setposition Set an element's vertical and horizontal positions.
setrectangle Set width and height of an element rectangle.
setactivesolver Set the specified solver as the active solver
runsetup Force group setup scripts to run.
get Get a property of selected objects.
getcontact Get a property of an electrical contact.
getnumber Get the number of selected objects.
getnamed Get a property of any objects with a given name.
getnamednumber Get the number of objects with a given name.
getglobalmonitor Get global monitor properties.
getglobalsource Get global source properties.
getposition Get current horizontal or vertical position of anelement.
getrectangle Get the width or height of an element rectangle.
229
229
229
230
230
231
231
232
232
233
233
233
234
263
235
235
236
236
237
237
237
234
234
Scripting Language 225
© 2003 - 2013 Lumerical Solutions, Inc
haveproperty Returns the number of selected objects with aparticular property.
importsurface Import surface data from a file. Only applies to importprimitives.
importsurface2 Import surface data from script variables. Onlyapplies to import primitives.
importnk Import n and k data from a file. Only applies to importprimitives.
importdoping Import data from Tecplot formatted file (text)
importnk2 Import n and k data from script variables. Onlyapplies to import primitives.
setsourcesignal Set a custom source time signal.
updatesourcemode Updates the mode for a mode source.
clearsourcedata Clears source data for an imported source, or theselected mode for a mode source.
setexpansion Associates a DFT monitor with a mode expansionmonitor.
removeexpansion Removes a DFT monitor from a mode expansionmonitor.
getname Returns the dataset name of the variable selected.
setname Sets the dataset name of the variable selected.
importdataset Imports an unstructured dataset named 'charge' to an'eh Density' grid attribute.
cleardataset Clear the dataset from any current grid attribute.
Controlling the view
Command Description
redraw Redraw graphics.
redrawoff Turn automatic redraw off.
redrawon Turn automatic redraw on.
redrawmode Get the current status of automatic redrawing; turn itoff or on
238
238
240
241
243
252
251
254
262
263
263
263
264
264
256
257
257
257
Reference Guide226
© 2003 - 2013 Lumerical Solutions, Inc
setview Control how the graphics are drawn in the LayoutEditor
getview Get the current view control properties from theLayout Editor.
orbit A built in function to do an orbit of the perspectiveview with option of creating a movie.
framerate Measure graphics performance of your computer.
Undo and redo commands
Command Description
undo Undo last modify object command.
redo Redo command after an undo.
7.8.1 groupscope
Changes the group scope. Script commands that add or modify simulation object use thegroupscope property to know where to act within the object tree. For example, if you wantto delete everything within a particular group, set the groupscope to that group (i.e. ::model::my_group). If you want to delete all objects in the simulation, set the group scopethe root level (i.e. ::model).
Syntax Description
?groupscope; returns the current group scope
groupscope("group_name"); changes the group scope
See Also Manipulating objects , delete , selectall , select
7.8.2 deleteall
Deletes all objects in the current group scope.
Syntax Description
deleteall; Deletes all objects in the current group scope.This function does not return any data.
See Also Manipulating objects , groupscope
258
259
259
260
260
260
223 227 227 227
223 226
Scripting Language 227
© 2003 - 2013 Lumerical Solutions, Inc
7.8.3 delete
Deletes selected objects.
Syntax Description
delete; Deletes selected objects.This function does not return any data.
See Also Manipulating objects , groupscope
7.8.4 selectall
Selects all objects in the current group scope.
Syntax Description
selectall; Selects all objects in the current group scope.This function does not return any data.
See Also Manipulating objects , groupscope
7.8.5 unselectall
Unselect all objects and groups.
Syntax Description
unselectall; Unselects all objects and groups.This function does not return any data.
See Also Manipulating objects
7.8.6 select
Selects objects with a given name in the current group scope. A failed select command willhave the same result as the unselectall command.
Syntax Description
select("name"); Selects objects with the name "name" in the current groupscope.
223 226
223 226
223
Reference Guide228
© 2003 - 2013 Lumerical Solutions, Inc
This function does not return any data.
select("group name::name"); Selects all objects with the name "name" located in thegroup named "group name". The group named "groupname" must be in the current group scope.
See Also Manipulating objects , groupscope , unselectall
7.8.7 selectpartial
Selects any objects with a given partial name, in the current TAB.
Syntax Description
selectpartial("partialname"); Selects any objects where "partialname" can be found inthe object name provided the object is not in a group. Toselect objects located in groups see the command below.This function does not return any data.
selectpartial("partialgroupname::partialname");
Selects any objects where "partialgroupname" can befound in the group name and "partialname" can be found inthe object name.
See Also Manipulating objects , groupscope
7.8.8 shiftselect
Same as select, but does not unselect other currently selected objects. Note that onlyobjects from the same "group" can be selected simultaneously.
Syntax Description
shiftselect("name"); The same as select("name"), but does not unselectcurrently selected objects. Can be used to select multipleobjects.This function does not return any data.
shiftselect("group name::name");
The same as select("groupname::name"), but does notunselect currently selected objects.
See Also Manipulating objects , groupscope
223 226 227
223 226
223 226
Scripting Language 229
© 2003 - 2013 Lumerical Solutions, Inc
7.8.9 shiftselectpartial
Same as selectpartial, but does not unselect other currently selected objects.
Syntax Description
shiftselectpartial("partialname");
The same as selectpartial("partialname"), but does notunselect currently selected objects. Can be used to selectmultiple objects. This function does not return any data.
shiftselectpartial("partialgroupname::partialname");
The same as selectpartial("partialgroupname::partialname"), but does not unselect currently selected objects. Can beused to select multiple objects.
See Also Manipulating objects , groupscope
7.8.10 flipelement
Flip element in the schematic editor. This command is only available in INTERCONNECT.
Syntax Description
flipelement("element"); Flips element in the schematic editor.
See Also Manipulating objects , rotateelement
7.8.11 rotateelement
Flip element in the schematic editor. This command is only available in INTERCONNECT.
Syntax Description
rotateelement("element"); Rotates element in the schematic editor.
See Also Manipulating objects , flipelement
7.8.12 move
Move selected objects.
Syntax Description
223 226
223 229
223 229
Reference Guide230
© 2003 - 2013 Lumerical Solutions, Inc
move(dx); In 2D or 3D, move by dx
move(dx,dy); In 2D or 3D, move by dx and dy.This function does not return any data.
move(dx,dy,dz); In 3D, move by dx, dy, and dz.In 2D, dz will be ignored.
See Also Manipulating objects , copy , select
7.8.13 copy
Create a copy of the selected objects. The copied objects will typically be identical (samename, position, etc). For some objects that must have a unique name, '_1' will beappended to the name.
Syntax Description
copy; Copy the selected objects.
copy(dx); Same as copy; but with a specified move of dx.
copy(dx,dy); Same as copy; but with a specified move of dx, dy.
copy(dx,dy,dz); Same as copy; but with a specified move of dx, dy, dz.
See Also Manipulating objects , move , select , cp (copy files) , copytoclipboard
7.8.14 addtogroup
Add selected objects to a group. This command is not available in INTERCONNECT.
Syntax Description
addtogroup("group name"); Adds selected object(s) to a group. If a group with name"group name" already exists, then the objects are added tothe existing group. Otherwise, a group named "groupname" is created.This function does not return any data.
See AlsoManipulating objects , addgroup , addstructuregroup , addanalysisgroup ,adduserprop , runsetup
223 230 227
223 229 227 115 127
223 209 209 210
231 235
Scripting Language 231
© 2003 - 2013 Lumerical Solutions, Inc
7.8.15 adduserprop
Adds a user defined custom property to the Setup user defined Structure and Analysisgroups. This command is not available in INTERCONNECT.
Syntax Description
adduserprop("propertyname", type, value);
Adds a user property to a selected structure group. Thename is set to "property name". The type is an integerfrom 0 to 5. The corresponding variable types are0 number1 text2 length3 time 4 frequency5 materialThe value of the user property is set to value.
See AlsoManipulating objects , addstructuregroup , runsetup
7.8.16 set
Set a property of currently selected objects. This command will return an error in analysismode.
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 usedto set the value of a selected object in a group. Value can be a number or string. This function does notreturn any data.
set("property",value,i); This form can be used to set the property of the ithselected object when multiple objects are selected. Itcannot be used to set the value of a selected object in agroup. The objects are ordered by their location in the object tree.The uppermost selected object is given the index 1, andthe index numbers increase as you go down the tree.
See Also
223 209 235
Reference Guide232
© 2003 - 2013 Lumerical Solutions, Inc
Manipulating objects , get , setnamed , setmaterial , addmaterial ,haveproperty , runsetup , runanalysis
7.8.17 setnamed
Like the set command, except that the object name must be specified. This command willreturn 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 specificname, instead of selected objects.
setnamed("name","property", value,i);
This form can be used to set the property of the ith namedobject when multiple objects have the same name. The objects are ordered by their location in the object tree.The uppermost selected object is given the index 1, andthe index numbers increase as you go down the tree.
setnamed("groupname::name", "property", value);
The same as set, but acts on objects within the groupnamed "groupname" that are named "name", instead ofselected objects.
setnamed("groupname::name", "property", value,i);
This form can be used to set the property of the ith objectwith the name "name" in the group "groupname" whenmultiple objects have the same name. The objects are ordered by their location in the object tree.The uppermost selected object is given the index 1, andthe index numbers increase as you go down the tree.
See Also Manipulating objects , set , get , getnamed , getnamednumber
7.8.18 setglobalmonitor
Set global monitor properties. This command will return an error in analysis mode. Thiscommand is available in FDTD and MODE.
Syntax Description
?setglobalmonitor; Returns a list of the global monitor properties
setglobalmonitor("property",value);
Set the global monitor property named "property" to avalue.This function does not return any data.
223 235 232 277 276
238 235 270
223 231 235 236 237
Scripting Language 233
© 2003 - 2013 Lumerical Solutions, Inc
See Also Manipulating objects , set , getglobalmonitor , setglobalsource , getglobalsource
7.8.19 setglobalsource
Set global source properties. This command will return an error in analysis mode. Thiscommand is available in FDTD and MODE.
Syntax Description
?setglobalsource; Returns a list of the global source properties
setglobalsource("property",value);
Set the global source property named "property" to a value.This function does not return any data.
See Also Manipulating objects , set , setglobalmonitor , getglobalmonitor ,getglobalsource
7.8.20 setmodes
Set mode labels. This command is only available in INTERCONNECT.
Syntax Description
setmodes (“TE,TM”); Set a list of comma separated mode labels that will sharethe same s-parameters. Orthogonal identifies areassociated to each mode from 1 to number of modes.
See Also Manipulating objects
7.8.21 setposition
Set horizontal and vertical positions of an element. This command is only available inINTERCONNECT.
Syntax Description
setposition("element",x,y); Set an element vertical and horizontal positions.
See Also Manipulating objects , getposition , setrectangle
223 231 237 233
237
223 231 232 237
237
223
223 234 234
Reference Guide234
© 2003 - 2013 Lumerical Solutions, Inc
7.8.22 setrectangle
Set the width or height of an element rectangle. This command is only available inINTERCONNECT.
Syntax Description
setrectangle ("element",w,h); Sets the width (w) and height (h) of an element rectangle.
See Also Manipulating objects , getrectangle , setposition
7.8.23 getposition
Get the current horizontal or vertical position of an element. This command is only availablein INTERCONNECT.
Syntax Description
out=getposition("element",”x”);
Returns the current horizontal position of an element.
out=getposition("element",”y”);
Returns the current vertical position of an element.
See Also Manipulating objects , setposition , getrectangle
7.8.24 getrectangle
Get the width or height of an element rectangle. This command is only available inINTERCONNECT.
Syntax Description
out=getrectangle("element",”w”);
Returns the width of an element rectangle.
out=getrectangle("element",”h”);
Returns the height of an element rectangle.
See Also Manipulating objects , setrectangle , getposition
223 234 233
223 233 234
223 234 234
Scripting Language 235
© 2003 - 2013 Lumerical Solutions, Inc
7.8.25 get
Get a property from selected objects. The property names for the get command are thesame as the property names in the Edit dialogue box. For example, if you see a propertycalled "mesh accuracy", then you can use the command get("mesh accuracy"); to get thatproperty. It is possible to get numeric, string, drop down and checkbox properties.
Syntax Description
?get; Returns a list of the properties of the selected object(s).
out = get("property"); Gets the requested property value from the currentlyselected object. It cannot be used to get the property valueof a selected object in a group. If multiple objects are selected get("property") is the sameas get("property",i), where i is the number of the firstselected objects with the requested property. Out can be a matrix or a string, depending on the propertyrequested.
get("property",i); Gets the property of the ith selected object. Use this to acton a series of objects. It cannot be used to get the value ofa selected object in a group. The objects are ordered by their location in the object tree.The uppermost selected object is given the index 1, andthe index numbers increase as you go down the tree.
See Also Manipulating objects , getnumber , getnamed , getnamednumber , set ,haveproperty , runsetup
7.8.26 runsetup
Runsetup forces the setup scripts of structure and analysis groups to run.
In most cases, it is not necessary to use this function, as group setup scriptsautomatically re-run at the end of script, if the object has been modified. It is onlynecessary to use this function when you need to force the setup script to run before theend of your script file.
Syntax Description
runsetup; Forces setup scripts of groups to run.
See Also
223 236 236 237 231
238 235
Reference Guide236
© 2003 - 2013 Lumerical Solutions, Inc
Manipulating objects , get , set , runanalysis
7.8.27 getnumber
Get the number of objects that are selected.
Syntax Description
out = getnumber; Returns the number of objects that are selected;
See Also Manipulating objects , get , getnamed , getnamednumber , set
7.8.28 getnamed
Get a property from objects with a given name.
If multiple objects are selected, and the values are different, the smallest value is returned. To be certain of the results, be sure that only one object is selected, or use the form ofgetnamed 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 specificname, instead of selected objects.
out=getnamed("name","property", i);
Gets the property of the ith named object. Use this to acton a series of objects.The objects are ordered by their location in the object tree.The uppermost selected object is given the index 1, andthe index numbers increase as you go down the tree.
out = getnamed("groupname::name","property");
The same as get, but acts on objects named "name"located in the group "groupname", instead of selectedobjects.
out = getnamed("groupname::name","property");
Gets the property of the ith object named "name" locatedin the group "groupname". Use this to act on a series ofobjects.The objects are ordered by their location in the object tree.The uppermost selected object is given the index 1, andthe index numbers increase as you go down the tree.
See Also
223 235 231 270
223 235 236 237 231
Scripting Language 237
© 2003 - 2013 Lumerical Solutions, Inc
Manipulating objects , get , getnumber , getnamednumber , set , setnamed
7.8.29 getnamednumber
Get the number of objects with a given name.
Syntax Description
out = getnamednumber( "name");
The same as getnumber, but acts on objects with aspecific 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 selectedobjects.
See Also Manipulating objects , get , getnamed , getnumber , set , setnamed
7.8.30 getglobalmonitor
Set global monitor properties. This command will return an error in analysis mode. Thiscommand is available in FDTD and MODE.
Syntax Description
?getglobalmonitor; Returns a list of the global monitor properties
?getglobalmonitor("property");
Returns the value of the requested property.
See Also Manipulating objects , get , setglobalmonitor , setglobalsource , getglobalsource
7.8.31 getglobalsource
Set global monitor properties. This command will return an error in analysis mode. Thiscommand is available in FDTD and MODE.
Syntax Description
?getglobalsource; Returns a list of the global source properties
?getglobalsource("property"); Returns the value of the requested property.
223 235 236 237 231
232
223 235 236 236 231 232
223 235 232 233
237
Reference Guide238
© 2003 - 2013 Lumerical Solutions, Inc
See Also Manipulating objects , get , setglobalmonitor , getglobalmonitor ,setglobalsource
7.8.32 getsolver
Returns the solver that is currently active. This command is only available in MODE.
Syntax Description
?getsolver; Returns the solver that is currently active.
7.8.33 haveproperty
Returns the number of selected objects with a particular property. This command is notavailable in INTERCONNECT.
Syntax Description
out = haveproperty("property");
Returns the number of selected objects with the specifiedproperty.
See Also Manipulating objects , get , set
7.8.34 importsurface
Import surface data. This command only applies to import primitives. The function returns 1if the data is successfully imported. Example script files showing how to use thesefunctions can be found in the Online Help. See the User Guide, Structures section. Thiscommand is available in FDTD and MODE.
Note: Non-uniform sampling of imported dataThe import object is primarily intended to load data that is sampled on a uniform mesh. Itis also capable of importing non-uniformly sampled data, but with some limitations. Themain limitation is that within the simulation file (.fsp or .lms) the import surface objectalways stores the data on a uniform mesh. When non-uniform data is imported, that datais interpolated onto a uniform mesh during at import time. The size of the newinterpolated uniform grid will be the greater of: a) the smallest grid size in the originaldata or, b) a grid size that results in 4 times the original number of sample points. Thesecond condition is intended to prevent the size of the interpolated surface data matrixfrom becoming extremely large in cases where the mesh is highly graded. If you areconcerned about the possibility of interpolation errors, the best option is to interpolate thedata onto a uniform mesh yourself, then import the uniformly sampled data into the
223 235 232 237
233
223 235 231
Scripting Language 239
© 2003 - 2013 Lumerical Solutions, Inc
simulation.It is worth remembering that the data stored within the import object will undergo asecond round of interpolation when it is interpolated onto the actual simulation meshcoordinates used by the actual simulation engine.
Clearly, the behavior of this object with respect to non-uniformly sampled data could beimproved. Rather than forcing all data to be stored on a uniform mesh, it could simplystore the original non-uniform data, then apply more sophisticated interpolation when thesimulation engine is generating the final simulation mesh. If such an improvement isimportant to you, please contact us at [email protected].
Syntax Description
out = importsurface(filename,upper_surface,file_units,x0,y0,z0,invertXY);
Import a surface from the file in the string filename ina three dimensional simulation. All arguments afterfilename are optional.
out = importsurface(filename,upper_surface,file_units,x0,y0,invertXY);
Import a surface from the file in the string filename ina two dimensional simulation. All arguments afterfilename are optional.
Parameter Default value Type Description
filename required string name of the file with surface datato import. May contain completepath to file, or path relative tocurrent working directory
upper_surface 1 number This optional argument should be1 to import the upper surface and0 to import the lower surface.
file_units "m" string The optional string argumentfile_units can be "m", "cm, "mm","microns" or "nm" to specify theunits in the file.
x0 0 number The optional arguments x0, y0 andz0 specify the data origin in theglobal coordinates of the GraphicalLayout Editor. For example, if youare importing a surface defined byan AFM that is on a slab of Si thatranges from 0 to 2 microns, you
Reference Guide240
© 2003 - 2013 Lumerical Solutions, Inc
should set z0 to 2 microns.
y0 0 number
z0 0 number
invertXY 0 number The optional argument invertXYcan be used to reverse how the xand y axes are read from the file.
See Also Manipulating objects , importsurface2
7.8.35 importsurface2
Import surface data from script variables. This command only applies to import primitives.The function returns 1 if the data is successfully imported. Example script files showinghow to use these functions can be found in the Online Help. See the User Guide,Structures section. This command is available in FDTD and MODE.
Note: Non-uniform sampling of imported dataThe import object is primarily intended to load data that is sampled on a uniform mesh. Itis also capable of importing non-uniformly sampled data, but with some limitations. Themain limitation is that within the simulation file (.fsp or .lms) the import surface objectalways stores the data on a uniform mesh. When non-uniform data is imported, that datais interpolated onto a uniform mesh during at import time. The size of the newinterpolated uniform grid will be the greater of: a) the smallest grid size in the originaldata or, b) a grid size that results in 4 times the original number of sample points. Thesecond condition is intended to prevent the size of the interpolated surface data matrixfrom becoming extremely large in cases where the mesh is highly graded. If you areconcerned about the possibility of interpolation errors, the best option is to interpolate thedata onto a uniform mesh yourself, then import the uniformly sampled data into thesimulation.It is worth remembering that the data stored within the import object will undergo asecond round of interpolation when it is interpolated onto the actual simulation meshcoordinates used by the actual simulation engine.
Clearly, the behavior of this object with respect to non-uniformly sampled data could beimproved. Rather than forcing all data to be stored on a uniform mesh, it could simplystore the original non-uniform data, then apply more sophisticated interpolation when thesimulation engine is generating the final simulation mesh. If such an improvement isimportant to you, please contact us at [email protected].
223 240
Scripting Language 241
© 2003 - 2013 Lumerical Solutions, Inc
Syntax Description
out = importsurface2(Z,x,y,upper_surface);
Import a surface from the variables Z, x and y in threedimensional simulations. The upper_surfaceargument is optional.
Parameter Default value Type Description
Z required matrix The two dimensional matrix thatdefines the surface.
x required matrix If Z is an NxM matrix, then xshould have dimension Nx1. Fortwo dimensional simulation, if Y isan Nx1 matrix then x should havedimension Nx1.
y required matrix If Z is an NxM matrix, then yshould have dimension Mx1.
upper_surface 1 number This optional argument should be1 to import the upper surface and0 to import the lower surface.
Y required matrix This argument should be an Nx1matrix that defines the surface fortwo dimensional simulations.
See Also Manipulating objects , importsurface
7.8.36 importnk
Import the refractive index (n and k) over an entire volume or surface from a file. Thiscommand only applies to import primitives. The function returns 1 if the data is successfullyimported. Example script files showing how to use these functions can be found in theOnline Help. See the User Guide, Structures section. This command is available in FDTDand MODE.
Note: Non-uniform sampling of imported dataThe import object is primarily intended to load data that is sampled on a uniform mesh. Itis also capable of importing non-uniformly sampled data, but with some limitations. Themain limitation is that within the simulation file (.fsp or .lms) the import surface objectalways stores the data on a uniform mesh. When non-uniform data is imported, that datais interpolated onto a uniform mesh during at import time. The size of the new
223 238
Reference Guide242
© 2003 - 2013 Lumerical Solutions, Inc
interpolated uniform grid will be the greater of: a) the smallest grid size in the originaldata or, b) a grid size that results in 4 times the original number of sample points. Thesecond condition is intended to prevent the size of the interpolated surface data matrixfrom becoming extremely large in cases where the mesh is highly graded. If you areconcerned about the possibility of interpolation errors, the best option is to interpolate thedata onto a uniform mesh yourself, then import the uniformly sampled data into thesimulation.It is worth remembering that the data stored within the import object will undergo asecond round of interpolation when it is interpolated onto the actual simulation meshcoordinates used by the actual simulation engine.
Clearly, the behavior of this object with respect to non-uniformly sampled data could beimproved. Rather than forcing all data to be stored on a uniform mesh, it could simplystore the original non-uniform data, then apply more sophisticated interpolation when thesimulation engine is generating the final simulation mesh. If such an improvement isimportant to you, please contact us at [email protected].
Syntax Description
out = importnk(filename,file_units,x0,y0,z0,reverse_index_order);
Import n (and k) data from filename in threedimensional simulations. All arguments after thefilename are optional.
out = importnk(filename,file_units,x0,y0,reverse_index_order);
Import n and k data from filename in two dimensionalsimulations. All arguments after the filename areoptional.
Parameter Default value Type Description
filename required string name of the file with n (and k) datato import. May contain completepath to file, or path relative tocurrent working directory
file_units "m" string The optional string argumentfile_units can be "m", "cm, "mm","microns" or "nm" to specify theunits in the file.
x0 0 number The optional arguments x0, y0 andz0 specify the data origin in theglobal coordinates of the GraphicalLayout Editor. For example, if youdefined your volume with respect
Scripting Language 243
© 2003 - 2013 Lumerical Solutions, Inc
to a particular point in space, forexample (0,0,-5) microns, thenyou should set z0 to -5 microns.
y0 0 number
z0 0 number
reverse_index_order 0 number The optional argument reverse_index_order can be set to1 to reverse how the indices areinterpreted in the file. It is best toverify the correct setting with agraphical import before using thescript command.
See Also Manipulating objects , importnk2
7.8.37 importnk2
Import the refractive index (n and k) over an entire volume or surface from script variables.This command only applies to import primitives. The function returns 1 if the data issuccessfully imported. Example script files showing how to use these functions can befound in the Online Help. See the User Guide, Structures section. This command isavailable in FDTD and MODE.
Note: Non-uniform sampling of imported dataThe import object is primarily intended to load data that is sampled on a uniform mesh. Itis also capable of importing non-uniformly sampled data, but with some limitations. Themain limitation is that within the simulation file (.fsp or .lms) the import surface objectalways stores the data on a uniform mesh. When non-uniform data is imported, that datais interpolated onto a uniform mesh during at import time. The size of the newinterpolated uniform grid will be the greater of: a) the smallest grid size in the originaldata or, b) a grid size that results in 4 times the original number of sample points. Thesecond condition is intended to prevent the size of the interpolated surface data matrixfrom becoming extremely large in cases where the mesh is highly graded. If you areconcerned about the possibility of interpolation errors, the best option is to interpolate thedata onto a uniform mesh yourself, then import the uniformly sampled data into thesimulation.It is worth remembering that the data stored within the import object will undergo asecond round of interpolation when it is interpolated onto the actual simulation meshcoordinates used by the actual simulation engine.
223 243
Reference Guide244
© 2003 - 2013 Lumerical Solutions, Inc
Clearly, the behavior of this object with respect to non-uniformly sampled data could beimproved. Rather than forcing all data to be stored on a uniform mesh, it could simplystore the original non-uniform data, then apply more sophisticated interpolation when thesimulation engine is generating the final simulation mesh. If such an improvement isimportant to you, please contact us at [email protected].
Syntax Description
out = importnk2(n,x,y,z); Import n (and k) data from script variables in threedimensional simulations. All arguments are required.
out = importnk2(n,x,y); Import n (and k) data from script variables in twodimensional simulations. All arguments are required.
Parameter Default value Type Description
n required matrix The refractive index. This shouldbe an NxMxP matrix in threedimensions and an NxM matrix intwo dimensions. If it is complex-valued, then the imaginary part isinterpreted as k.
x required matrix If n is an NxMxP matrix, then xshould have dimension Nx1. Fortwo dimensional simulation, if n isan NxM matrix then x should havedimension Nx1. Values of x mustbe uniformly spaced.
y required matrix If n is an NxMxP matrix, then yshould have dimension Mx1. Fortwo dimensional simulation, if n isan NxM matrix then y should havedimension Mx1. Values of y mustbe uniformly spaced.
z 1 number If n is an NxMxP matrix, then zshould have dimension Px1.Values of z must be uniformlyspaced.
See Also Manipulating objects , importnk223 241
Scripting Language 245
© 2003 - 2013 Lumerical Solutions, Inc
7.8.38 importnkobfuscated
This command is identical to importnk but makes it possible to import data from a file thathas been obfuscated. For details on how to obfuscate the data files, please see the OnlineHelp in the User Guide, Structures section. This command is available in FDTD Solutionsonly, for versions 8.6.3 and higher.
Note: Non-uniform sampling of imported dataThe import object is primarily intended to load data that is sampled on a uniform mesh. Itis also capable of importing non-uniformly sampled data, but with some limitations. Themain limitation is that within the simulation file (.fsp or .lms) the import surface objectalways stores the data on a uniform mesh. When non-uniform data is imported, that datais interpolated onto a uniform mesh during at import time. The size of the newinterpolated uniform grid will be the greater of: a) the smallest grid size in the originaldata or, b) a grid size that results in 4 times the original number of sample points. Thesecond condition is intended to prevent the size of the interpolated surface data matrixfrom becoming extremely large in cases where the mesh is highly graded. If you areconcerned about the possibility of interpolation errors, the best option is to interpolate thedata onto a uniform mesh yourself, then import the uniformly sampled data into thesimulation.It is worth remembering that the data stored within the import object will undergo asecond round of interpolation when it is interpolated onto the actual simulation meshcoordinates used by the actual simulation engine.
Clearly, the behavior of this object with respect to non-uniformly sampled data could beimproved. Rather than forcing all data to be stored on a uniform mesh, it could simplystore the original non-uniform data, then apply more sophisticated interpolation when thesimulation engine is generating the final simulation mesh. If such an improvement isimportant to you, please contact us at [email protected].
Syntax Description
out =importnkobfuscated(key,filename,file_units,x0,y0,z0,reverse_index_order);
Import n (and k) data from filename in three dimensionalsimulations. All arguments after the filename are optional.
Parameter Default value Type Description
key required string The key that is used to decryptthe obfuscated file.
Reference Guide246
© 2003 - 2013 Lumerical Solutions, Inc
filename required string name of the file with n (and k) datato import. May contain completepath to file, or path relative tocurrent working directory
file_units "m" string The optional string argumentfile_units can be "m", "cm, "mm","microns" or "nm" to specify theunits in the file.
x0 0 number The optional arguments x0, y0 andz0 specify the data origin in theglobal coordinates of the GraphicalLayout Editor. For example, if youdefined your volume with respectto a particular point in space, forexample (0,0,-5) microns, thenyou should set z0 to -5 microns.
y0 0 number
z0 0 number
reverse_index_order 0 number The optional argument reverse_index_order can be set to1 to reverse how the indices areinterpreted in the file. It is best toverify the correct setting with agraphical import before using thescript command.
See Also Manipulating objects , importnk
7.8.39 importbinary
Import binary data (1s and 0s) over an entire volume from a file. The object will be presentwherever the binary data is 1 and not when it is 0. This command only applies to importprimitives. The function returns 1 if the data is successfully imported. Example script filesshowing how to use these functions can be found in the Online Help. See the User Guide,Structures section. This command is available in FDTD and MODE.
Note: Non-uniform sampling of imported dataThe import object is primarily intended to load data that is sampled on a uniform mesh. Itis also capable of importing non-uniformly sampled data, but with some limitations. The
223 241
Scripting Language 247
© 2003 - 2013 Lumerical Solutions, Inc
main limitation is that within the simulation file (.fsp or .lms) the import surface objectalways stores the data on a uniform mesh. When non-uniform data is imported, that datais interpolated onto a uniform mesh during at import time. The size of the newinterpolated uniform grid will be the greater of: a) the smallest grid size in the originaldata or, b) a grid size that results in 4 times the original number of sample points. Thesecond condition is intended to prevent the size of the interpolated surface data matrixfrom becoming extremely large in cases where the mesh is highly graded. If you areconcerned about the possibility of interpolation errors, the best option is to interpolate thedata onto a uniform mesh yourself, then import the uniformly sampled data into thesimulation.It is worth remembering that the data stored within the import object will undergo asecond round of interpolation when it is interpolated onto the actual simulation meshcoordinates used by the actual simulation engine.
Clearly, the behavior of this object with respect to non-uniformly sampled data could beimproved. Rather than forcing all data to be stored on a uniform mesh, it could simplystore the original non-uniform data, then apply more sophisticated interpolation when thesimulation engine is generating the final simulation mesh. If such an improvement isimportant to you, please contact us at [email protected].
Syntax Description
out = importbinary(filename,file_units,x0,y0,z0,reverse_index_order);
Import binary data from filename in three dimensionalsimulations. All arguments after the filename areoptional.
Parameter Default value Type Description
filename required string name of the file with binary data toimport. May contain completepath to file, or path relative tocurrent working directory
file_units "m" string The optional string argumentfile_units can be "m", "cm, "mm","microns" or "nm" to specify theunits in the file.
x0 0 number The optional arguments x0, y0 andz0 specify the data origin in theglobal coordinates of the GraphicalLayout Editor. For example, if youdefined your volume with respect
Reference Guide248
© 2003 - 2013 Lumerical Solutions, Inc
to a particular point in space, forexample (0,0,-5) microns, thenyou should set z0 to -5 microns.
y0 0 number
z0 0 number
reverse_index_order 0 number The optional argument reverse_index_order can be set to1 to reverse how the indices areinterpreted in the file. It is best toverify the correct setting with agraphical import before using thescript command.
See Also Manipulating objects , importbinary2
7.8.40 importbinary2
Import binary data (1s and 0s) over an entire volume from script variables. The object will bepresent wherever the binary data is 1 and not when it is 0. This command only applies toimport primitives. The function returns 1 if the data is successfully imported. Example scriptfiles showing how to use these functions can be found in the Online Help. See the UserGuide, Structures section. This command is available in FDTD and MODE.
Note: Non-uniform sampling of imported dataThe import object is primarily intended to load data that is sampled on a uniform mesh. Itis also capable of importing non-uniformly sampled data, but with some limitations. Themain limitation is that within the simulation file (.fsp or .lms) the import surface objectalways stores the data on a uniform mesh. When non-uniform data is imported, that datais interpolated onto a uniform mesh during at import time. The size of the newinterpolated uniform grid will be the greater of: a) the smallest grid size in the originaldata or, b) a grid size that results in 4 times the original number of sample points. Thesecond condition is intended to prevent the size of the interpolated surface data matrixfrom becoming extremely large in cases where the mesh is highly graded. If you areconcerned about the possibility of interpolation errors, the best option is to interpolate thedata onto a uniform mesh yourself, then import the uniformly sampled data into thesimulation.It is worth remembering that the data stored within the import object will undergo asecond round of interpolation when it is interpolated onto the actual simulation meshcoordinates used by the actual simulation engine.
223 248
Scripting Language 249
© 2003 - 2013 Lumerical Solutions, Inc
Clearly, the behavior of this object with respect to non-uniformly sampled data could beimproved. Rather than forcing all data to be stored on a uniform mesh, it could simplystore the original non-uniform data, then apply more sophisticated interpolation when thesimulation engine is generating the final simulation mesh. If such an improvement isimportant to you, please contact us at [email protected].
Syntax Description
out = importbinary2(binary,x,y,z); Import binary data from script variables in threedimensional simulations. All arguments are required.
Parameter Default value Type Description
binary required matrix The binary data This should be anNxMxP matrix in three dimensionsand an NxM matrix in twodimensions. It should have onlyvalues of 0 or 1. If other values arepresent, all non-zero values will beinterpreted as 1.
x required matrix If n is an NxMxP matrix, then xshould have dimension Nx1. Fortwo dimensional simulation, if n isan NxM matrix then x should havedimension Nx1. Values of x mustbe uniformly spaced.
y required matrix If n is an NxMxP matrix, then yshould have dimension Mx1. Fortwo dimensional simulation, if n isan NxM matrix then y should havedimension Mx1. Values of y mustbe uniformly spaced.
z 1 number If n is an NxMxP matrix, then zshould have dimension Px1.Values of z must be uniformlyspaced.
See Also Manipulating objects , importbinary223 246
Reference Guide250
© 2003 - 2013 Lumerical Solutions, Inc
7.8.41 importbinaryobfuscated
This command is identical to importbinary but makes it possible to import data from a filethat has been obfuscated. For details on how to obfuscate the data files, please see theOnline Help in the User Guide, Structures section. This command is available in FDTDSolutions only, for versions 8.6.3 and higher.
Note: Non-uniform sampling of imported dataThe import object is primarily intended to load data that is sampled on a uniform mesh. Itis also capable of importing non-uniformly sampled data, but with some limitations. Themain limitation is that within the simulation file (.fsp or .lms) the import surface objectalways stores the data on a uniform mesh. When non-uniform data is imported, that datais interpolated onto a uniform mesh during at import time. The size of the newinterpolated uniform grid will be the greater of: a) the smallest grid size in the originaldata or, b) a grid size that results in 4 times the original number of sample points. Thesecond condition is intended to prevent the size of the interpolated surface data matrixfrom becoming extremely large in cases where the mesh is highly graded. If you areconcerned about the possibility of interpolation errors, the best option is to interpolate thedata onto a uniform mesh yourself, then import the uniformly sampled data into thesimulation.It is worth remembering that the data stored within the import object will undergo asecond round of interpolation when it is interpolated onto the actual simulation meshcoordinates used by the actual simulation engine.
Clearly, the behavior of this object with respect to non-uniformly sampled data could beimproved. Rather than forcing all data to be stored on a uniform mesh, it could simplystore the original non-uniform data, then apply more sophisticated interpolation when thesimulation engine is generating the final simulation mesh. If such an improvement isimportant to you, please contact us at [email protected].
Syntax Description
out =importbinaryobfuscated(key,filename,file_units,x0,y0,z0,reverse_index_order);
Import binary data from filename in three dimensional simulations.All arguments after the filename are optional.
Parameter Default value Type Description
key required string The key that is used to decryptthe obfuscated file.
Scripting Language 251
© 2003 - 2013 Lumerical Solutions, Inc
filename required string name of the file with binary data toimport. May contain completepath to file, or path relative tocurrent working directory
file_units "m" string The optional string argumentfile_units can be "m", "cm, "mm","microns" or "nm" to specify theunits in the file.
x0 0 number The optional arguments x0, y0 andz0 specify the data origin in theglobal coordinates of the GraphicalLayout Editor. For example, if youdefined your volume with respectto a particular point in space, forexample (0,0,-5) microns, thenyou should set z0 to -5 microns.
y0 0 number
z0 0 number
reverse_index_order 0 number The optional argument reverse_index_order can be set to1 to reverse how the indices areinterpreted in the file. It is best toverify the correct setting with agraphical import before using thescript command.
See Also Manipulating objects , importbinary
7.8.42 updatesourcemode
Updates the mode profile of selected mode source. If there is no mode profile stored in thesource, then the mode with the highest effective index will be selected. If a mode isalready stored in the source, then the mode with the best overlap with the old mode will beselected. Note that the mode source must be selected before running this command. Thiscommand is available in FDTD and MODE.
Syntax Description
?updatesourcemode; Updates mode profile of the selected Mode source.
223 246
Reference Guide252
© 2003 - 2013 Lumerical Solutions, Inc
Returns the fraction of electromagnetic fields thatoverlap between the old and the new mode
?updatesourcemode(mode_number);
Updates the mode source and selects the desiredmode number. For example, updatesourcemode(1);will calculate the fundamental mode. Please note thatmaking this call will force a recalculation of a mode,even if the same mode has previously been calculated.In addition, making this call will force the modeselection method to become "user select". Thisoptional argument was introduced in FDTD Solutions8.6.3 and MODE Solutions 6.5.3.
NOTE: Saving simulation files before using updatesourcemodeIf you have a script file which updates the simulation mesh, then you should use the savescript command before updating the source mode. This will ensure that the mesh hasbeen updated before the new mode is calculated.
NOTE: overlapThe fraction of electromagnetic fields that overlap between the two modes is given by theexpression below. It is also the fraction of power from mode2 that can propagate inmode1. For more information, please see overlap script command.
SdHESdHE
SdHESdHEoverlap
*22
*11
*12
*21
Re
1Re
See AlsoManipulating objects , addmode , clearsourcedata , clearmodedata , getresult
, overlap, expand , seteigensolver , geteigensolver
7.8.43 setsourcesignal
Sets a custom source time signal.
This is an advanced source setting for users wanting a custom source time signal. For thevast majority of simulations, a custom time signal is not required. If this function is notused, the time signal will be automatically generated. This command is available in FDTDand MODE.
For an example script file which uses this script command, see Online User Guide->Sources->Custom time signal.
113
223 215 254 254
270 195 255 256
Scripting Language 253
© 2003 - 2013 Lumerical Solutions, Inc
Syntax Description
setsourcesignal("name", t,amplitude, phase);
Sets the time domain signal of source named "name". t,amplitude, and phase are 1D vectors with the same length.
setsourcesignal("name", t,amplitude, phase, fcentre,bandwidth);
Allows you to specify the precise center frequency andbandwidth that will be used for all simulations. These valuesare used for materials fits, calculating the mesh, and sourcelimits.If fcentre and bandwidth are not specified, they will beautomatically estimated from the time signal.
See Alsosourcepower
7.8.44 updatemodes
Updates the mode profile(s) of selected mode expansion monitor If there are no modeprofiles stored in the mode expansion monitor, then the mode with the highest effectiveindex will be selected. If mode profiles are already stored in the mode expansion monitor,then the modes with the best overlap with the old modes will be selected. Note that themode expansion monitor must be selected before running this command. This command isavailable in FDTD and MODE.
Syntax Description
updatemodes; Updates mode profile of the selected mode expansionmonitor. Returns 1 if the update was successful and -1 if not.
updatemodes(mode_number); Updates the mode expansion monitor and selects thedesired mode numbers. For example,updatesourcemode(1:10); will calculate the 10 modeswith the highest refractive index. Please note thatmaking this call will force a recalculation of a modes,even if the same modes have previously beencalculated. In addition, making this call will force themode selection method to become "user select". Thisoptional argument was introduced in FDTD Solutions8.6.3 and MODE Solutions 6.5.3.
NOTE: Saving simulation files before using updatesourcemodeIf you have a script file which updates the simulation mesh, then you should use the save
Reference Guide254
© 2003 - 2013 Lumerical Solutions, Inc
script command before updating the source mode. This will ensure that the mesh hasbeen updated before the new mode is calculated.
NOTE: overlapThe fraction of electromagnetic fields that overlap between the two modes is given by theexpression below. It is also the fraction of power from mode2 that can propagate inmode1. For more information, please see overlap script command.
SdHESdHE
SdHESdHEoverlap
*22
*11
*12
*21
Re
1Re
See AlsoManipulating objects , addmode , clearsourcedata , clearmodedata , getresult
, overlap, expand , seteigensolver , geteigensolver
7.8.45 clearsourcedata
Clears source data for an imported source, or the selected mode for a mode source. Thiscommand is available in FDTD and MODE.
Syntax Description
clearsourcedata; Clears source data for the selected source.
ExampleClear source data from an imported source. This will make the file much smaller, whichcan be convenient when emailing simulation files.
select("source3");clearsourcedata;
See Alsoupdatesourcemode , asapimport , asapload , asapexport , clearmodedata ,getresult , overlap, expand , seteigensolver , geteigensolver
7.8.46 clearmodedata
Clears mode data for a mode expansion monitor This command is available in FDTD andMODE, as of versions 8.6.3 and 6.5.3 respectively. This is mainly useful to reduce filesizes when saving.
113
223 215 254 254
270 195 255 256
251 124 124 123 254
270 195 255 256
Scripting Language 255
© 2003 - 2013 Lumerical Solutions, Inc
Syntax Description
clearmodedata; Clears mode data for the selected mode expansion mnoitor.
See Alsoupdatesourcemode , asapimport , asapload , asapexport , clearsourcedata ,getresult , overlap, expand , seteigensolver , geteigensolver
7.8.47 seteigensolver
Mode sources and mode expansion monitors in FDTD and MODE have embeddedeigensolvers. This script command makes it possible to set the properties of thateigensolver without using the GUI.
Changing any values of the embedded eigensolver with this command will automaticallyinvalidate any existing mode data. This means that new updates based on overlapcalculations with previous modes will fail after using this command. Therefore please callthis command before making any calls to updatesourcemode or updatemodes.
Syntax Description
?seteigensolver; Returns a list of the properties of the embeddedeigensolver
seteigensolver("property",value);
This will set the eigensolver properties of the currentlyselected objects.Value can be a number or string. This function does notreturn any data.
ExampleChange the radius of curvature for a mode expansion calculation, and calculate the first 10modes which can be subsequently used for mode expansion.
select("mode_expansion");seteigensolver("bent waveguide",true);seteigensolver("bend radius",10e-6);updatemodes(1:10);
See AlsoManipulating objects , addmode , clearsourcedata , clearmodedata , getresult
, overlap, expand , seteigensolver , geteigensolver , updatemodes ,
251 124 124 123 254
270 195 255 256
223 215 254 254
270 195 255 256 253
Reference Guide256
© 2003 - 2013 Lumerical Solutions, Inc
updatesourcemode
7.8.48 geteigensolver
Mode sources and mode expansion monitors in FDTD and MODE have embeddedeigensolvers. This script command makes it possible to get the properties of thateigensolver without using the GUI.
Syntax Description
?geteigensolver; Returns a list of the properties of the embeddedeigensolver
geteigensolver("property"); This will get the eigensolver properties of the currentlyselected objects. The returned value may be a number or astring, depending on the property.
ExampleChange the radius of curvature for a mode expansion calculation, and calculate the first 10modes which can be subsequently used for mode expansion.
select("mode_expansion");?geteigensolver("bent waveguide");
See AlsoManipulating objects , addmode , clearsourcedata , clearmodedata , getresult
, overlap, expand , seteigensolver , geteigensolver , updatemodes ,updatesourcemode
7.8.49 redraw
Force the graphical viewports of the CAD to update. The viewports update automatically bydefault, so this command is only required after using the redrawoff command. Thiscommand is not available in INTERCONNECT.
Syntax Description
redraw; Redraws graphics.This function does not return any data.
251
223 215 254 254
270 195 255 256 253
251
Scripting Language 257
© 2003 - 2013 Lumerical Solutions, Inc
See Also Manipulating objects , redrawon , redrawoff , redrawmode
7.8.50 redrawoff
Disable automatic updating of the graphical viewports in the CAD. This can greatlyincrease the speed of scripts that add large numbers of objects. This command is notavailable in INTERCONNECT.
Syntax Description
redrawoff; Prevents redrawing of graphics.This function does not return any data.Cannot use this command in group setup scripts sinceredrawing is automatically turned off.
See Also Manipulating objects , redrawon , redraw , redrawmode
7.8.51 redrawon
Enable automatic updating of the graphical viewports in the CAD. Automatic updating isthe default behavior, so this command is only required after using the redrawoff command.This command is not available in INTERCONNECT.
Syntax Description
redrawon; Turns redrawing back on.This function does not return any data.
See Also Manipulating objects , redraw , redrawoff , redrawmode
7.8.52 redrawmode
This command can be used to determine the current status of automatic redrawing. It canalso be used to set the current status of automatic redrawing. The graphics will be redrawnafter any script command that may change the properties of a graphical object. Thiscommand is not available in INTERCONNECT.
Syntax Description
out = redrawmode; The value of out indicates if automatic redrawing is off or onout=1: automatic redrawing is onout=0: automatic redrawing is off
223 257 257 257
223 257 256 257
223 256 257 257
Reference Guide258
© 2003 - 2013 Lumerical Solutions, Inc
out = redrawmode(in); Set the automatic redrawing off or on. To turn it on, usein=1. To turn it off, use in=0. The value of out is set afterexecuting the command so that out=in once this commandhas been executed.
See Also Manipulating objects , redraw , redrawoff
7.8.53 setview
This command allows the viewing properties of the Layout Editor to be modified. Thiscommand is not available in INTERCONNECT.
Syntax Description
outstring = setview; Returns a list of the view properties that can be set. Thecommand?setview;
will returnextent, zoom, theta, phi
setview("property"); Sets the default value for any of the view properties. Forexample,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 a2x1, 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 viewcompared to the default level. To zoom in by a factor of 2 inthe perspective view, use setview("zoom",2);
theta Controls the polar angle of the perspective view, indegrees.
phi Controls the azimuthal angle of the perspective view, indegrees.
223 256 257
Scripting Language 259
© 2003 - 2013 Lumerical Solutions, Inc
See Also Manipulating objects , getview , orbit , redraw
7.8.54 getview
This command allows the viewing properties of the Layout Editor to be retrieved. Thiscommand is not available in INTERCONNECT.
Syntax Description
outstring = getview; Returns a list of the view properties that can be set. Thecommand?getview;
will returnextent, zoom, theta, phi
out = getview("property"); Returns the current value of any of the view properties. Forexample,zoom_level = getview("zoom");
will return the current zoom setting of the perspective viewrelative to the default level.
The properties that can be obtained with getview are described in setview .
See Also Manipulating objects , setview , orbit , redraw
7.8.55 orbit
This command performs an elliptical viewing orbit of the structure in the perspective view.Note that the commands setview , getview and redraw make it possible to createany type of orbit you would like in your own script file. This command is not available inINTERCONNECT.
Syntax Description
orbit; Performs an orbit of the current perspective view.
orbit(zoom_factor); Performs an orbit with the specified minimum zoomfactor. By default the zoom factor is 1.5.
orbit(zoom_factor, frame_rate); Performs an orbit with the specified frame ratespecified in frames per second. The default frame rateis 15.
223 259 259 256
258
223 258 259 256
258 259 256
Reference Guide260
© 2003 - 2013 Lumerical Solutions, Inc
orbit(zoom_factor, frame_rate,"filename");
The orbit will be streamed to the mpeg file filename forlater viewing.
See Also Manipulating objects , setview , getview , framerate
7.8.56 framerate
Orbits the perspective view and returns the framerate. This can be useful for estimating yourgraphics performance. If comparing the performance of two computers, be sure to useexactly the same simulation file. This command is available in FDTD only.
Syntax Description
fr = framerate(num_frames,zoom);
num_frames - Number of frames to drawzoom - Zoom factor used in perspective viewfr - number of frames / wall time required to completeorbit.
See Also Manipulating objects , setview , getview , orbit
7.8.57 undo
Undo the last command that modified any objects, you can undo the last 5 commands.
Syntax Description
undo; Undo last modify object command.This function does not return any data.
See Also Manipulating objects , redo
7.8.58 redo
Redo a command after a previous undo.
Syntax Description
redo; Redo command after previous undo.This function does not return any data.
See Also
223 258 259 260
223 258 259 259
223 260
Scripting Language 261
© 2003 - 2013 Lumerical Solutions, Inc
Manipulating objects , undo
7.8.59 addport
Add a port to a compound/script element. (Note that this command does not apply forprimitive elements.) This command is only available in INTERCONNECT.
Syntax Description
addport("element", "port","type", "data");
Adds a new port to the element with the specifiedproperties.Returns the name of the port that is created.
Property Defaultvalue
Type Description
element required string Name of the element to add aport to.
port required string Name of the port to add. Thenamed will be modified if thereis already a port of the samename.
type required string The type of port to add. Theoptions are: Bidirectional,Input, Output, Analyzer Input
data required string The type of data for the port.The options are: Variant,Optical Signal, ElectricalSignal, Digital Signal
Manipulating objects , removeport
7.8.60 removeport
Remove a port from a compound/script element. (Note that this command does not applyfor primitive elements.) This command is only available in INTERCONNECT.
Syntax Description
removeport("element","port");
Removes "port" from "element".Returns 1 if the port is successfully removed, 0 otherwise.
223 260
223 261
Reference Guide262
© 2003 - 2013 Lumerical Solutions, Inc
Manipulating objects , addport
7.8.61 connect
Connects one element to another via the specified ports. This command is only available inINTERCONNECT.
Syntax Description
connect("element1", "port1","element2", "port2");
Connects "port1" of "element1" to "element2" or "port2".
Manipulating objects , disconnect
7.8.62 disconnect
Disconnect one element to another via the specified ports. This command is only availablein INTERCONNECT.
Syntax Description
connect("element1", "port1","element2", "port2");
Deletes the connection between "port1" of "element1" and"port2" of "element2".
Manipulating objects , connect
7.8.63 setexpansion
Associates a DFT monitor with a mode expansion monitor. This command is available inFDTD and MODE.
Syntax Description
?setexpansion; List all monitors under the "Monitors for expansion" list forthe selected mode expansion monitor.
setexpansion("name","dft_monitor");
Adds the "dft_monitor" to the "Monitors for expansion" listof the selected mode expansion monitor, with the specifiedname.
addmodeexpansion , removeexpansion , Using Mode Expansion Monitors
223 261
223 262
223 262
222 263
Scripting Language 263
© 2003 - 2013 Lumerical Solutions, Inc
7.8.64 removeexpansion
Removes a DFT monitor from a mode expansion monitor. This command is available inFDTD and MODE.
Syntax Description
removeexpansion("name"); Removes the DFT monitor with the specified name from the"Monitors for expansion" list of the selected modeexpansion monitor.
addmodeexpansion , setexpansion , Using Mode Expansion Monitors
7.8.65 setactivesolver
Set the specified solver as the active solver. For example, this can be used to togglebetween the Eigenmode solver and Propagator simulations in MODE Solutions. Thiscommand is available only in MODE.
Syntax Description
?setactivesolver; Lists all the possible solver choices
setactivesolver('solver_name');
Set the solver with the specified name as the active solver.
7.8.66 getname
The script command getname is used to get the name of a datset.
Syntax Description
?getname(a); Returns the name of the dataset of the variable a.
?a.getname; Returns the name of the dataset of the variable a.
See Alsosetname
7.8.67 setname
The script command setname is used to set the name of a datset.
Syntax Description
a.setname("test"); Returns the name of the dataset of the variable a.
222 262
263
Reference Guide264
© 2003 - 2013 Lumerical Solutions, Inc
See Alsogetname
7.8.68 importdataset
This command can import charge density to a selected 'eh density' grid attribute. A filecontains an unstructured dataset called 'charge' with scaler attributes 'n' and 'p' can beexported from DEVICE, for example Mach_Zehnder. The unstructured dataset 'charge' inthis file can be imported to the 'eh Density' grid attribute in FDTD, MODE or DEVICE, byGUI or this command. This command is NOT available in INTERCONNECT.
Syntax Description
importdataset("device_data.mat")
Imports the unstructured dataset 'charge' in the file fromthe current working directory.
importdataset(charge) Implements 'charge' from the file that is already importedby matlabload
Property Description
device_data.mat A Matlab formatted file, that contains data exported fromDEVICE
charge Name of an unstructured data set
See Also Manipulating objects , cleardataset
7.8.69 cleardataset
This command clears the dataset from any current eh Density grid attribute. This is onlyuseful for keeping file size small.This command is ONLY available in MODE and DEVICE.
Syntax Description
cleardataset; clears the dataset from any current eh Density gridattribute.
See Also Manipulating objects , importdataset
263
125
223 264
223 264
Scripting Language 265
© 2003 - 2013 Lumerical Solutions, Inc
7.9 Running simulationsMoving between tabs
Command Description
switchtolayout Closes the analysis window and allows you tomanipulate simulation objects for a new simulation.
layoutmode Used to determine if the simulation file is open inlayout or in analysis mode.
Running Simulations
Command Description
run Launch the simulation. (Options available)
runparallel Launch the simulation in parallel mode.
addjob Add a simulation to the job queue.
runjobs Run all simulations in the job queue.
clearjobs Remove all simulations from the job queue.
runsweep Runs a parameter sweep or optimization task
Command Description
run Launch the simulation. (Options available)
runsweep Runs a parameter sweep or optimization task
7.9.1 runparallel
Launch the simulation in parallel mode. Equivalent to run and run(3). When the simulationfinishes, all simulation data will be saved to the current file. This command has beendeprecated. Use run.
Syntax Description
runparallel; Launch the simulation in parallel mode as defined in theresource manager. This function does not return any data.
See Also run, runanalysis
208
209
265
266
266
266
267
267
270
Reference Guide266
© 2003 - 2013 Lumerical Solutions, Inc
7.9.2 addjob
Adds a simulation file to the job manager queue. This command is not available inINTERCONNECT.
Syntax Description
addjob(filename); Add the simulation file "filename" to the job managerqueue.
See Also run, runsweep , runjobs , clearjobs , currentfilename
7.9.3 runjobs
Run all simulations in the job manager queue. The script execution will be paused whilethe jobs run, then resume when all of the simulations have complete successfully. If errorsoccur, the script will not proceed. This command is not available in INTERCONNECT.
Syntax Description
runjobs; Run jobs in the Job queue. Use the computer resourcesand parallel settings that are specified in the ResourceManager.
runjobs(option); option=0: run jobs in single process mode using only thelocal computer.option=1: run jobs using the computer resources andparallel settings that are specified in the ResourceManager. (default)
See Also run, runsweep , addjob , clearjobs , save , load
7.9.4 clearjobs
Remove all jobs from the job manager queue. This command is not available inINTERCONNECT.
Syntax Description
clearjobs; Remove all jobs from the Job queue.
See Also run, addjob , runjobs
267 266 266 117
267 266 266 113 113
266 266
Scripting Language 267
© 2003 - 2013 Lumerical Solutions, Inc
7.9.5 runsweep
Runs a parameter sweep or optimization task.
Syntax Description
runsweep; Runs all sweeps and optimization tasks.
runsweep("taskname"); Runs only the sweep or optimization named taskname.
See Also run, getsweepdata , addjob , runjobs
7.10 Measurement and optimization dataThe following commands are used to access data from simulation objects.
Most raw data is recorded in multi-dimensional form. For example, monitors in FDTD andMODE Solutions typically return data in 4D matrices. The first three dimensions of thematrix correspond to the spatial dimensions X, Y, Z. The 4th dimension corresponds to thefrequency or time dimension, depending on the type of monitor. For example, suppose youhave a FDTD Solutions simulation with a frequency monitor in the XY plane that records 20frequency points. Assuming the monitor spans 100 mesh points in the x direction and 55mesh points in the y direction, the size of the Ex field component data matrix will be100x55x1x20. Notice that the 3rd dimension (corresponding to Z) has a size of 1, sincethe monitor only recorded data at one Z position.
Command Description
getresult Get results from simulation objects.
getdata Get raw data from simulation objects.
getelectric Get raw |E|2 data matrix from monitor
getmagnetic Get raw |H|2 data matrix from monitor
runanalysis Runs the analysis script in analysis objects
clearanalysis Clears d-card data obtained by running analysisscripts.
havedata Used to see if there is any available data storedwithin an object.
haveresult Used to see if there are any available results withinan object.
268 266 266
270
269
274
274
270
273
271
271
Reference Guide268
© 2003 - 2013 Lumerical Solutions, Inc
read and write data to file Read and write data to a file.
copydcard Creates a copy of a d-card.
cleardcard Clears a d-card.
Parameter sweep,optimization, and yield analysis data is saved with the simulation file andis not cleared when switching the current simulation to layout mode. These results can beaccessed with the following commands:
Command Description
getsweepdata Gets raw data from parameter sweeps,optimizations, and yield analysis.
getsweepresult Gets results from parameter sweeps andoptimizations.
havesweepdata Used to check if parameter sweep and optimizationshave data.
havesweepresult Used to check if parameter sweep and optimizationshave results.
loadsweep Loads previously generated sweep result
savesweep Saves the generated sweep result
issweep Checks if the simulation is in sweep mode.
7.10.1 getsweepdata
Gets raw data from a parameter sweep, optimization, or yield analysis. In most cases, it ismore convenient to a complete dataset with getsweepresult, rather than getting individualdata elements with getsweepdata.
Syntax Description
?getsweepdata; Returns names of all sweep, optimization, and yieldanalysis objects.
?getsweepdata("sweep_name");
Returns all the names of the available data which is storedin the sweep, optimization, or yield analysis object.
out = getsweepdata("sweep_name", "data");
Returns parameter sweep, optimization, or yield analysisdata.
The following data can be obtained from an optimization:
275
273
274
268
269
272
272
275
275
Scripting Language 269
© 2003 - 2013 Lumerical Solutions, Inc
fomTrend - Figure of merit as a function of generationfomHistory - Figure of merit history (for each generationthere will be generation size number)bestFom - Best figure of merit obtained during sweepbestParameter - Parameter which corresponds tobestFomparamHistory - Parameter history
For a parameter sweep and yield analysis, this commandreturns both parameters and results.
See Alsogetdata , runsweep , havesweepdata , savedata , getsweepresult , savesweep
, loadsweep
7.10.2 getsweepresult
Get parameter sweep or optimization results in the form of a dataset.
Syntax Description
?getsweepresult; Returns names of all sweep or optimization objects withavailable results.
?getsweepresult("sweep_name");
Returns names of the available results from the sweep oroptimization task.
out = getsweepresult("sweep_name", "result");
Returns parameter sweep or optimization dataset.
See AlsoDataset introduction , runsweep , havesweepresult , getresult , savedata ,getsweepdata , savesweep , loadsweep
7.10.3 getdata
Get data from the simulation. Remember to run the simulation before using getdata.
Syntax Description
?getdata; Returns names of all objects with data.
?getdata("monitor") Returns list of of results within the simulation object.
?getdata( "monitor","result");
Returns list of of data within the simulation object result.
269 267 272 121 269
275 275
141 267 272 270 121
268 275 275
Reference Guide270
© 2003 - 2013 Lumerical Solutions, Inc
out = getdata( "monitor","result", "dataname");
Gets the simulation data.
See AlsoMeasurements , havedata , getsweepdata
7.10.4 getresult
Get results from simulation objects. Results will be returned as datasets.
Syntax Description
?getresult("monitor_name"); Returns the names of all the results for the monitor. All thedataset and scalar matrix results will be returned in thiscase.
R = getresult("monitor_name","T");
Returns the result T from the monitor. T is a dataset.
See AlsoMeasurements , haveresult , Dataset introduction , "." operator , visualize ,getdata , rectilineardataset , matrixdataset , getattribute , addattribute ,splitstring
7.10.5 runanalysis
Runs the analysis script in analysis objects.
Note: Scripts that already have data are not re-run; to re-run a script, first clear data usingclearanalysis.
Syntax Description
runanalysis; Runs the analysis scripts in all analysis objects in thesimulation file.This function does not return any data.
runanalysis("group name"); Runs the analysis script in the analysis object named"group name".This function does not return any data.
See Also
267 271 268
267 271 141 168 203
269 139 139 141 140
178
Scripting Language 271
© 2003 - 2013 Lumerical Solutions, Inc
run, getdata , getresult , havedata , clearanalysis , runsetup
7.10.6 havedata
Used to see a simulation object (such as a monitor) has any data. This command is verysimilar to haveresult, but is intended to be used with the getdata command, rather thangetresult. This command is not available in INTERCONNECT.
Syntax Description
havedata; Returns 1 if any simulation objects have raw data, and 0 ifnone have any raw data.
havedata("name"); Returns 1 if "name" has raw data, and 0 if it does not haveany raw data.
havedata("name","data"); Returns 1 if "name" has the raw data named "data", and 0if it does not have that data.
See AlsoMeasurements , getdata , haveresult , getresult , copydcard , cleardcard ,workspace , havesweepdata
Available in
FDTD SolutionsMODE SolutionsINTERCONNECTDEVICE
YesYesNoYes
7.10.7 haveresult
Used to see a simulation object (such as a monitor) has any results.
Note: This command is very similar to havedata, but is intended to be used with thegetresult command, rather than getdata.
Syntax Description
haveresult; Returns 1 if any simulation objects currently have anyresults.
haveresult("name"); Returns 1 if "name" has any results, and 0 if it does not.
haveresult("name","data"); Returns 1 if the "name" has a result named "data", and 0 ifit does not.
269 270 271 273 235
267 269 271 270 273 274
136 272
Reference Guide272
© 2003 - 2013 Lumerical Solutions, Inc
See AlsoMeasurements , getresult , havedata , getdata , copydcard , cleardcard ,workspace , havesweepdata
7.10.8 havesweepdata
Used to check if parameter sweep and optimizations have data. Similar to havedata, but forsweeps and optimization tasks.
Syntax Description
havesweepdata; Returns 1 if any sweeps or optimizations have data.Returns 0 if data is not available.
havesweepdata("name"); Returns 1 if the specified sweep or optimization has data.
havesweepdata("name","data");
Returns 1 if the sweep or optimization "name" has thespecified data.
See AlsoMeasurements , runsweep , getsweepdata , getdata , havedata
7.10.9 havesweepresult
Used to check if parameter sweep and optimizations have results. Similar to haveresult, butused for checking if sweeps and optimization tasks have available results.
Syntax Description
havesweepresult; Returns 1 if any sweeps or optimizations have results.Returns 0 if data is not available.
havesweepresult("name"); Returns 1 if the specified sweep or optimization hasresults.
havesweepresult("name","data");
Returns 1 if the sweep or optimization "name" has thespecified result.
See AlsoMeasurements , runsweep , getsweepresult , getresult , haveresult
267 270 271 269 273 274
136 272
267 267 268 269 271
267 267 269 270 271
Scripting Language 273
© 2003 - 2013 Lumerical Solutions, Inc
7.10.10 copydcard
Will create a global copy of any d-card currently in memory. This command is available inFDTD and MODE.
Syntax Description
copydcard( "name"); Will create a global copy of any d-card currently in memorycalled "name". By default, the new name will be "::global_name".This function does not return any data.
copydcard( "name","newname");
Will create a global copy of any d-card currently in memorycalled "name". The new name will be "::newname".
See AlsoMeasurements , havedata , cleardcard
Available in
FDTD SolutionsMODE SolutionsINTERCONNECTDEVICE
YesYesNoNo
7.10.11 clearanalysis
Clears analysis object results. This data is also cleared by switching from Analysis Modeto Layout Mode. This command is not available in INTERCONNECT.
Note: The analysis object results are calculated with the runanalysis command.
Syntax Description
clearanalysis; Clears analysis object results. This function does not return any data.
clearanalysis( "name1","name2", ...);
Clears data from specific analysis objects.
See AlsoMeasurements , switchtolayout , getdata , runanalysis , havedata
267 271 274
267 208 269 270 271
Reference Guide274
© 2003 - 2013 Lumerical Solutions, Inc
7.10.12 cleardcard
Clears global d-cards. Only global d-cards are cleared. Local d-cards are associated withthe current simulation and can only be cleared by switching from Analysis Mode to LayoutMode. This command is available in FDTD and MODE.
Syntax Description
cleardcard; Clears all the global d-cards. This function does not return any data.
cleardcard( "name1","name2", ...);
Clears any number of specified d-cards.
See AlsoMeasurements , havedata , copydcard
7.10.13 getelectric
Returns the sum of the amplitude squares for all electric field components, i.e. it returns |
Ex|2+|Ey|2+|Ez|2. This command is available in FDTD and MODE.
Syntax Description
out = getelectric( "monitorname");
Returns |Ex|2+|Ey|2+|Ez|2 from the monitor.
getelectric( "monitorname",option);
The optional argument, option, can have a value of 1 or 2. Ifit is 2, the data is unfolded where possible according to thesymmetry or anti-symmetric boundaries if it comes from amonitor that intersect such a boundary at x min, y min or zmin. The default value of option is 2.
See AlsoMeasurements , getdata , getmagnetic , cwnorm, nonorm
7.10.14 getmagnetic
Returns the sum of the amplitude squares for all magnetic field components, i.e. it returns |
Hx|2+|Hy|2+|Hz|2. This command is available in FDTD and MODE.
Syntax Description
out = getmagnetic( "monitorname");
Returns |Hx|2+|Hy|2+|Hz|2 from the monitor.
267 271 273
267 269 274
Scripting Language 275
© 2003 - 2013 Lumerical Solutions, Inc
getmagnetic( "monitorname", option);
The optional argument, option, can have a value of 1 or 2. Ifit is 2, the data is unfolded where possible according to thesymmetry or anti-symmetric boundaries if it comes from amonitor that intersect such a boundary at x min, y min or zmin. The default value of option is 2.
See Also Measurements , getdata , getelectric , cwnorm, nonorm
7.10.15 Read and write data to files
Please see the following section for file I/O commands.System level commands: File input and output
7.10.16 loadsweep
The script command loads the sweep object with the previously generated sweep result.
Syntax Description
loadsweep; Loads previously generated sweep result to all the sweepobjects in simulation.
loadsweep("name"); Loads previously generated sweep result to the specifiedsweep objects in simulation.
See AlsoMeasurements , getdata , runsweep , havesweepdata , savedata ,getsweepresult , savesweep
7.10.17 savesweep
The script command saves the sweep object results.
Syntax Description
savesweep; Saves the sweep result of all sweep objects in simulation.
savesweep("name"); Saves the sweep result of the specified sweep object.
See AlsoMeasurements , getdata , runsweep , havesweepdata , savedata ,getsweepresult , loadsweep
267 269 274
109
267 269 267 272 121
269 275
267 269 267 272 121
269 275
Reference Guide276
© 2003 - 2013 Lumerical Solutions, Inc
7.11 Material databaseThe following commands are used to add or copy materials in the material database, aswell as to set any material property and verify the resulting complex index of a givenmaterial 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 thesecommands.This section is not relevant for INTERCONNECT.
Command Description
addmaterial Adds a new material into the material database.
copymaterial Copies an existing material in the material database
setmaterial Sets any property of an existing material in thematerial database.
getmaterial Returns properties of a material in the materialdatabase.
getindex Returns the complex index of a material.
getfdtdindex Returns the material index as it will be in an actualFDTD simulation.
getmodeindex Returns the material index as it will be in an actualMODE simulation.
getnumericalpermittivity An advanced function that returns permittivity, takinginto account the effect of finite size of dt in an FDTDsimulation.
7.11.1 addmaterial
Adds a new material to the material database. This command is not available inINTERCONNECT.
Syntax Description
?addmaterial; Displays all types of materials that can be added into thematerial database.
out = addmaterial("materialtype");
Adds a new material and returns the name of the newmaterial. The argument "materialtype" is has to matchcorrect string exactly.
See Also
276
277
277
277
278
278
279
280
Scripting Language 277
© 2003 - 2013 Lumerical Solutions, Inc
Material database , setmaterial , getindex , getfdtdindex
7.11.2 copymaterial
Makes a copy of a material in the material database. This command is not available inINTERCONNECT.
Syntax Description
out = copymaterial("materialname");
Creates a copy of the material "materialname". The newname is returned.
See AlsoMaterial database , setmaterial , getindex , getfdtdindex
7.11.3 setmaterial
Modifies properties of a material in the material database. This command is not available inINTERCONNECT.
Syntax Description
?setmaterial("materialname");
Displays the property names of the specified material thatcan be modified.
setmaterial( "materialname","propertyname", newvalue);
Sets the property named "propertyname" of the materialwith the name "materialname" to newvalue. The argumentnewvalue can be a number or a string. The arguments"propertyname" and "materialname" have to match correctstring exactly. For example, setmaterial("Si","Mesh order",4);will set the property "mesh order" of the materials "Si" to4.
See AlsoMaterial database , addmaterial , getmaterial , getindex , getfdtdindex
7.11.4 getmaterial
Returns properties of a material in the material database. This command is not available inINTERCONNECT.
Syntax Description
276 277 278 278
276 277 278 278
276 276 277 278 278
Reference Guide278
© 2003 - 2013 Lumerical Solutions, Inc
?getmaterial( "materialname");
Displays the property names of the specified material thatcan be modified.
out = getmaterial( "materialname","propertyname");
Returns the property named "propertyname" of the materialwith the name "materialname". The returned variable iseither a matrix or a string, depending on the property in thequery.
See AlsoMaterial database , addmaterial , setmaterial , getindex , getfdtdindex
7.11.5 getindex
Returns the complex index of any material that is in the material database. The index atthe specified frequency is interpolated from the neighboring frequencies where the indexdata is available. This command is available in FDTD and MODE.
Syntax Description
out = getindex( "materialname", f);
Returns the complex index of the material with the givenname. The index is returned for the specified frequency f. Frequency f is in Hz.
getindex( "materialname", f,component);
Optional argument component can be 1, 2 or 3 to specifythe x, y or z component for anisotropic materials. Thedefault is 1.
See AlsoMaterial database , getfdtdindex , getmodeindex , addmaterial , setmaterial
7.11.6 getfdtdindex
This function returns the material index of a material in the database as it will be used in anactual FDTD simulation.
Many materials (such as Sampled materials) have properties that depend on frequency.Using getfdtdindex, you can specify frequency range, and the fitting routine will find a bestfit of the material data over that range. The index evaluated at the specified f is thenreturned. Note that the fit result depends on the fit parameters, Max coefficients andTolerance set for the material, thus getfdtdindex result depends on those parameters aswell.
This command is available in FDTD and MODE.
276 276 277 278 278
276 278 279 276 277
Scripting Language 279
© 2003 - 2013 Lumerical Solutions, Inc
Syntax Description
out = getfdtdindex( "materialname", f, fmin,fmax);
Returns the complex index of the material with the givenname. 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. Allfrequency units are in Hz.
getfdtdindex("materialname",f,fmin, fmax, component);
Optional argument component can be 1, 2 or 3 to specifythe x, y or z component for anisotropic materials. Thedefault is 1.
See AlsoMaterial database , getindex , getmodeindex , addmaterial , setmaterial
7.11.7 getmodeindex
This function returns the material index of a material in the database as it will be used in anactual MODE simulation.
Many materials (such as Sampled Materials) have properties that depend on frequency.Using getmodeindex, you can obtain the refractive index as a function of the specifiedfrequency, f, as it will be used in MODE calculations. Note that when multi-coefficientmodels are used, the fit result depends on the fit parameters, Max coefficients andTolerance set for the material. This command is available in FDTD and MODE.
Syntax Description
out = getmodeindex( "materialname", f);
Returns the complex index of the material with the givenname. The index is returned for the specified frequency f.This result is identical to getindex unless the optionalarguments fitsampled and fitanalytic are used. Allfrequency units are in Hz.
getmodeindex("materialname", f,component);
Optional argument component can be 1, 2 or 3 to specifythe x, y or z component for anisotropic materials. Thedefault is 1.
getmodeindex("materialname", f,component, fitsampled,fitanalytic, fmin, fmax);
Optional arguments to specify if Sampled Materials orAnalytic Materials should be fitted using Lumerical's multi-coefficient model (MCM), which is commonly used inFDTD simulations. If either of these options are set to 1(true) then you must supply a minimum and maximum
276 278 279 276 277
Reference Guide280
© 2003 - 2013 Lumerical Solutions, Inc
frequency for fitting. The MCM is typically used in MODESolutions for
Sampled Materials when calculating waveguidedispersion, and forAnalytic Materials only for the purpose of using preciselythe same materials in both FDTD and MODEsimulations.
The default values are 0 (false) for fitsampled andfitanalytic.
See AlsoMaterial database , getindex , getfdtdindex , addmaterial , setmaterial
7.11.8 getnumericalpermittivity
This advanced function returns the permittivity of a material in the database as it will beused in an actual FDTD simulation, including the effects of a finite time step, dt. In FDTD,the relationship between the displacement field, D, and the electric field, E, is given by
EdtD r ,0
In the limit where dt tends to zero, we have
20 ,lim ndtrdt
where n( ) is the refractive index returned by the script function getfdtdindex, or shown inthe Materials Explorer. If you set dt to zero when calling this function, it will return exactlythe same result as the square of getfdtdindex.
The name of the function is a reminder that it returns the numerical permittivity, ie, the ratioof D and E, which is different from the refractive index, ie the ratio of the speed of light in avacuum to the phase velocity of light in the medium. To understand the relationshipbetween the them, we must consider the full, numerical dispersion relation between andk which is given by
2222
2sin
1
2sin
1
2sin
1
2sin
1,
dzk
dz
dyk
dy
dxk
dx
dt
cdtdt zyx
r
In the limit where dt, dx, dt and dz tend to zero, it is easy to show that we have theexpected result
)()0,( n
ck
dt
ck
r
The spatial FDTD mesh and time step are generally chosen to obtain a desired level ofsimulation accuracy, essentially by ensuring that the arguments of the sine functions are
276 278 278 276 277
Scripting Language 281
© 2003 - 2013 Lumerical Solutions, Inc
sufficiently small that sin(x)~x and that the simulation is stable. For some materials, it maybe desired to further reduce the value of the time step, dt, without modifying the spatialFDTD mesh, in order to obtain a higher level of accuracy for
r( ,dt). This script function
makes it possible to calculate, in advance, the value of dt required to obtain the desiredaccuracy for the permittivity.
This command is available in FDTD and MODE.
Syntax Description
out =getnumericalpermittivity( "materialname", f, fmin,fmax, dt);
Returns the complex permittivity of the material with thegiven name. The permittivity is returned for the specifiedfrequency f. This is similar to getfdtdindex except for theadditional parameter dt. All frequency units are in Hz.
getnumericalpermittivity("materialname", f,fmin,fmax, dt, component);
Optional argument component can be 1, 2 or 3 to specifythe x, y or z component for anisotropic materials. Thedefault is 1.
See AlsoMaterial database , getindex , addmaterial , setmaterial , getfdtdindex
7.12 GDSIIThe following commands can be used to import and export GDSII files.
Command Description
gdsopen Opens a GDSII file for writing.
gdsclose Closes a GDSII file for writing.
gdsbegincell Starts a new cell in a GDSII file.
gdsendcell Finishes a cell in a GDSII file.
gdsaddpoly Adds a polygon element to a GDSII file stream.
gdsaddcirlce Adds an approximation of a circle to a GDSII filestream.
gdsaddrect Adds a rectangle element to a GDSII file stream.
gdsaddref Adds a reference to another cell to the current cell inthe GDSII file stream.
gdsimport Imports a cell from a .gds file into the layoutenvironment.
276 278 276 277 278
282
282
283
283
284
284
285
286
286
Reference Guide282
© 2003 - 2013 Lumerical Solutions, Inc
7.12.1 gdsopen
This function creates a new .gds file and returns a file handle that can be used with theother GdsWriter functions to write the file. The default database units are in 0.1nm and theuser units are microns. The GDSII export function works as a group of commands, shownbelow as an example. For more information, please see Userguide - GDSII - Import andexport.
Syntax Description
f = gdsopen("filename","userUnit", "dataBaseUnit")
Opens a .gds file in the current directory, specifies the sizeof user units and size of the GDSII file units. f is a filehandle to open the GDSII file.
Parameter Type Description
filename string name of the GDSII file to export, may also contain afile path.
userUnit number size of user units in GDSII file units.
databaseUnit number size of the GDSII file units in meters.
See Alsogdsclose , gdsbegincell , gdsendcell , gdsaddpoly , gdsimport
7.12.2 gdsclose
This function closes a GDSII file for writing. Before calling this command, a .gds file has tobe previously opened, see gdsopen .
Syntax Description
gdsclose("filename") closes a .gds file in the current working directory.
Parameter Type Description
filename string name of the GDSII file to export, may also contain afile path.
See Alsogdsopen , gdsbegincell , gdsendcell , gdsaddpoly , gdsimport
282 283 283 284 286
282
282 283 283 284 286
Scripting Language 283
© 2003 - 2013 Lumerical Solutions, Inc
7.12.3 gdsbegincell
This function creates a cell in a GDSII file. All GDS elements (polygons, boxes, references,array references, etc) must be placed inside a cell, so this function must be called beforeadding any elements. When finished adding elements, gdsendcell can be called to finish
the cell. Cells cannot be nested, so after calling gdsbegincell, a new cell cannot be
called again until the first called cell has been closed. Although the GDSII file is a flat list ofcells, cells can reference other cells, thus creating a nested hierarchy. See gdsaddreffor more details. A GDS "cell" exists as a "structure group" when imported to FDTD, see gdsimport for more details.
Syntax Description
gdsbegincell(f, "cellname") Creates a new cell in a GDSII file.
Parameter Type Description
f string a file handle that was previously opened with gdsopen.
cellname string name of the cell.
Note: Just to clarify, a GDS cell is different from a Cell Array in FDTD.
See Alsogdsopen , gdsclose , gdsendcell , gdsaddpoly , gdsaddref , gdsimport ,cell
7.12.4 gdsendcell
This function finishes a cell in a GDSII file. This function ends the current cell in the GDSIIfile stream. The command gdsbegincell has to be called before closing a cell.
Syntax Description
gdsendcell(f) Finishes the previously created cell in a GDSII file.
Parameter Type Description
f string a file handle that was previously opened with gdsopen.
See Alsogdsopen , gdsclose , gdsbegincell , gdsaddpoly , gdsimport
286
286
147
282 282 283 284 286 286
147
282 282 283 284 286
Reference Guide284
© 2003 - 2013 Lumerical Solutions, Inc
7.12.5 gdsaddpoly
This function adds a polygon element to a GDSII file stream. Polygons are also known asboundary elements in GDS terminology. This command can be called only if a cell hasbeen created.
Syntax Description
gdsaddpoly(f, layer,[vertices])
Adds a polygon element on a layer with vertices.
Parameter Type Description
f string a file handle that was previously opened with gdsopen.
layer number layer number for this structure.
vertices vector vertices of the polygon, in a 1D vector. They aregrouped in XY pairs e.g., {x1,y1,x2,y2,...xn,yn}. Thevalues are in meters. The first and last values shouldnot be the same, the polygon will be automaticallyclosed.
See Alsogdsopen , gdsclose , gdsbegincell , gdsendcell , gdsaddcircle , gdsaddref, gdsimport
7.12.6 gdsaddcircle
This function adds an approximation of a circle to a GDSII file stream. GDSII files do notsupport circles, so this is just a convenient function to create a polygon representation of acircle. Polygons can only be added in a GDSII cell, so this command can be called only ifa cell has been created.
Syntax Description
gdsaddcircle(f, layer, x, y, r,n)
Adds an approximation of a circle on a layer with x-, y-coordinates, radius and number of polygon sides.
Parameter Type Description
f string a file handle that was previously opened with gdsopen.
282 282 283 283 284 286
286
Scripting Language 285
© 2003 - 2013 Lumerical Solutions, Inc
layer number layer number for this structure.
x number x-coordinate of the center position in meters.
y number y-coordinate of the center position in meters.
r number radius of the circle in meters.
n number number of sides to use in the polygon approximation.It is 64 by default.
See Alsogdsopen , gdsclose , gdsbegincell , gdsendcell , gdsaddpoly , gdsaddref ,gdsimport
7.12.7 gdsaddrect
This function adds a rectangle element to a GDSII file stream. This is just a convenientfunction to create a polygon for the case of a rectangle. Other element type for rectangle(such as, box) is not supported at this moment. Polygons can only be added in a GDSIIcell, so this command can be called only if a cell has been created.
Syntax Description
gdsaddrect(f, layer, x, y,width, height)
Adds a rectangle element on a layer with x-, y-coordinates,width and height.
Parameter Type Description
f string a file handle that was previously opened with gdsopen.
layer number layer number for this structure.
x number x-coordinate of the center position in meters.
y number y-coordinate of the center position in meters.
width number width of the rectangle in meters.
height number height of the rectangle in meters.
See Alsogdsopen , gdsclose , gdsbegincell , gdsendcell , gdsaddpoly , gdsaddref ,gdsimport
282 282 283 283 284 286
286
282 282 283 283 284 286
286
Reference Guide286
© 2003 - 2013 Lumerical Solutions, Inc
7.12.8 gdsaddref
This function adds a reference to another cell to the current cell in the GDSII file stream.This function replicates the referenced cell (has to be previously opened and finished) to thecurrent cell, to create a nested hierarchy. The layer numbers of the replicated structuresfollow the referenced cell. References can only be added in a GDSII cell, so this commandcan be called only if a current cell has been created. In addition, the cell to be replicatedhas to exist before it is referenced.
Syntax Description
gdsaddref(f, "cellname", dx,dy)
Adds a reference to another cell ("cellname") to the currentcell, with a specified move of dx and dy.
Parameter Type Description
f string a file handle that was previously opened withgdsopen.
cellname string name of the referenced cell.
dx number x-movement of the replicated cell in the current cell.
dy number y-movement of the replicated cell in the current cell.
See Alsogdsopen , gdsclose , gdsbegincell , gdsendcell , gdsaddpoly , gdsaddcircle
, gdsaddrect , gdsimport
7.12.9 gdsimport
This command imports a cell from a .gds file into the layout environment. This is equivalentto performing a GDSII import through the FILE->IMPORT menu. See the Reference Guide- Layout editor chapter , Reference Guide - GDSII Import and Userguide - GDSII -Import and export for more information.
This command is NOT available in INTERCONNECT.
Syntax Description
n = gdsimport("filename","cellname", layer);
Imports the specified layer from the specified cell in thespecified file into the current simulation environment. Theobjects created will have their material set to an objectdefined dielectric. In 3D, the 2D geometric data will be
282 282 283 283 284
284 285 286
29 60
Scripting Language 287
© 2003 - 2013 Lumerical Solutions, Inc
extruded to default values in the Z dimension. The optionalreturned value, n, is the number of objects that wereimported from the gds file.
n = gdsimport("filename","cellname", layer,"material");
Same as the above command, but the material of theimported object will be set to the value specified.
n = gdsimport("filename","cellname", layer,"material", zmin, zmax);
This form of the command is only allowed in 3D layouts.The behavior is the same as the above command, but thestructures will be extruded in the Z dimension to thespecified z min and z max values
Parameter Type Description
filename string name of the GDSII file to import. It can contain acomplete path to file, or path relative to the currentworking directory.
cellname string name of the cell to import from the GDSII file.
layer number orstring
the layer number from the GDSII file to import. If onlyelements 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 datatype is 2.
material string a valid name of a material in your current layoutenvironment. Partial names of materials can bematched starting at the beginning of the string. Forexample, "Al (3" would match "Al (300nm)".
zmin number the minimum z value for extruding 2D GDSII data into3D objects
zmax number the maximum z value for extruding 2D GDSII datainto 3D objects
Example:This command imports "cell_1", on the first layer in the GDS_export.gds file, with a
specified material, z min and z max assigned. For more examples, please visit ReferenceGuide - GDSII Import , and Userguide - GDSII - Import and export for associated files.gdsimport("GDS_export.gds", "cell_1", 1, "Ag (Silver) - CRC", 0,1e-6);
60
Reference Guide288
© 2003 - 2013 Lumerical Solutions, Inc
See AlsoSystem level , setnamed , fileexists , gdsopen
7.13 User defined GUIsCustom GUIs can be created with the following commands.
Command Description
message Creates a message window that displays some text.
newwizard Used to create a new user defined wizard.
newwizardpage This creates a page for the wizard.
wizardwidget Adds a new widget to the current wizard window.
runwizard Runs the wizard and returns a value indicating whichbutton was pressed.
wizardgetdata Returns data entered into a specific widget.
killwizard This closes the wizard window.
wizardoption Sets some options for wizard widgets and labels.
fileopendialog Calls the standard windows file open dialog.
filesavedialog Calls the standard windows file save dialog.
Typically, a wizard will be created with the following steps1. Open a new wizard with newwizard2. Add a new wizard page with newwizardpage3. Add widgets to the wizard page with wizardwidget4. Call runwizard to run the wizard5. Use wizardgetdata to obtain values entered into widgets by the user6. Depending on the values returned by runwizard , the wizard can be closed with
killwizard , or a new wizard page is started with newwizardpage .
7.13.1 message
Creates a message window that displays some text. The user must hit Enter, or click theOK button to continue.
Syntax Description
message("text"); Creates a window that displays text.
109 232 117 282
288
289
289
289
291
291
291
292
292
292
289
289
289
291
291
291
291 289
Scripting Language 289
© 2003 - 2013 Lumerical Solutions, Inc
This function does not return any data.
See AlsoUser defined GUI , newwizard
7.13.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. Theminimum values for w and h are 200. title is the wizard window title.
See AlsoUser defined GUI , message
7.13.3 newwizardpage
This creates a page for the wizard and should be done before adding any widgets.
Syntax Description
newwizardpage( "label1"); Creates a button with the label "label1". Typically, this willbe "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 AlsoUser defined GUI , newwizardpage
7.13.4 wizardwidget
Adds a new widget to the current wizard window. This command should only be done aftercreating 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
288 289
288 288
288 289
Reference Guide290
© 2003 - 2013 Lumerical Solutions, Inc
"menu" for a pulldown menu field"label" to add a string label (wizardgetdata does notreturn information for labels)
name is a string used to give the input field, checkbox,menu item or label a name.
wizardwidget( "type", "label",defaultValue);
defaultValue provides a default value for numeric inputs,checkboxes, menu items or strings.
wizardwidget( "type", "label","choices", defaultValue);
If the "type" of widget is a "menu", then the menu choicesmust be provided. These choices should be separated bythe character "|". For example, to create a pulldown widgetwith the name "simulation type" and 3 choices"TE","TM","3D", with the default choice "3D", thecommand iswizardwidget("menu","simulation type","TE|TM|3D",3);
See AlsoUser defined GUI , newwizardpage
7.13.5 wizarddata
This command will cause the wizard window to wait until the user selects OK or Cancel. Itthen returns value data from the matrix in a N+1 length matrix, where N is the number ofwidgets (excluding labels) in the current wizard page.
This function is only available in MODE Solutions.
Syntax Description
out = wizarddata; The values of out areout(1) = 0, 1 or -1. 0 means the user pressed Cancel, 1means the user pressed the first button (typically "OK"or "Next") and -1 means the user pressed the secondbutton (typically "Back")out(2:N+1) gives the numeric values that the userentered for each input field when out(1) is 1. Note thatcheck boxes return 1 if checked and 0 if unchecked.Menu items return a number between 1 and M where Mis the number of choices in the menu. If out(1) is 0 or -1,all the values out(2:N+1) are zero.
See Also User defined GUI , newwizard
288 289
288 289
Scripting Language 291
© 2003 - 2013 Lumerical Solutions, Inc
7.13.6 runwizard
Runs the wizard and returns a value indicating which button was pressed.
Syntax Description
out = runwizard; Returns either 0, +1 or -1.0 means the user pressed Cancel, 1 means the userpressed the first button (created by calling newwizardpage)and -1 means the user pressed the second button (createdby calling newwizardpage).
See AlsoUser defined GUI , newwizardpage
7.13.7 wizardgetdata
Returns data entered into a specific widget.
This function is only available in MODE Solutions.
Syntax Description
out = wizardgetdata(N); Returns the value that the user entered into the Nth widget.Out will be a number or a string, depending on the type ofwidget.
See Also User defined GUI , newwizardpage
7.13.8 killwizard
This closes the wizard window. It should only be called after a wizard window has beencreated with the newwizard command.
Syntax Description
killwizard; This closes the wizard window.
See AlsoUser defined GUI , newwizardpage
288 289
288 289
288 289
Reference Guide292
© 2003 - 2013 Lumerical Solutions, Inc
7.13.9 wizardoption
Sets some options for wizard widgets and labels.
Syntax Description
wizardoption ("optionname",setting);
The options are"fontsize" sets the font size to any value between 8 and40"fieldwidth" sets the width of each widget field to anyvalue between 20 and the full width of the wizard window."fieldheight" sets the height of each field to any valuebetween 8 and the full height of the wizard window."margin", sets size of the left margin to any valuebetween 0 and full width of the wizard window.
See AlsoUser defined GUI , newwizard
7.13.10 fileopendialog
Calls the standard windows file open dialog.
Syntax Description
out = fileopendialog; Brings up the open file dialog box and returns the path thatthe user selects.
out = fileopendialog(".ext"); Brings up the open file dialog box, displaying only files withthe extension .ext. Returns the path of the file that the userselects.
See Also User defined GUIs , filesavedialog
7.13.11 filesavedialog
Calls the standard windows file save dialog.
Syntax Description
out = filesavedialog; Brings up the save file dialog box and returns the path thatthe user selects.
out = filesavedialog(".ext"); Brings up the save file dialog box, displaying only files withthe extension .ext. Returns the path of the file that the user
288 289
288 292
Scripting Language 293
© 2003 - 2013 Lumerical Solutions, Inc
selects.
See Also User defined GUIs , fileopendialog
7.14 Creating your own script commandsRunning a script file from the script promptYou can run any script file simply by typing the name of the file (without the .lsf extension).For example, if you create the file create_array.lsf, you can run this file from the commandprompt, or another script file, with the commandcreate_array;
The current working directory is always in the Lumerical script path, and is the mostcommon location for your script files. You can add additional locations to the path withthe addpath script function. The following location (within the installation directory) is
also always in the path, making it a convenient place to put script functions that may beneeded my all users of the computer. It will be necessary to have admin access to savefiles in this location.C:\Program Files\Lumerical\FDTD\scripts (Windows)
/usr/local/lumerical/scripts (Linux)
Note: Saving script files with the same name as built in script functionsIt is generally not recommended to create script files that have the same name as thestandard script functions. In such cases, where there is a conflict between a script file andstandard script function, the script file will run. In other words, this allows you to overridethe behavior of a standard script function. This can be helpful, but it can also lead toconfusing behavior when done unintentionally.
Calling one script file from anotherOnce you start creating complex scripts, it may be convenient to split them up into anumber of simpler scripts that call one another. If you have multiple scripts in the samedirectory then they can call each other just as you would use any other scriptingcommand.
Note: All script files use a common variable space. As a consequence, variables defined in thescripts are global, and the script files have access to all variables defined in the simulationproject 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.lsfi=1;
288 292
119
Reference Guide294
© 2003 - 2013 Lumerical Solutions, Inc
script_2;?i;
script_2.lsffor(i=1:10) { # do something}
Formatting tipsMultiple commands are allowed on a single line.Blank lines, space and tabs will be ignored. Therefore you can format your script filesany way you choose. Each command must be terminated with a semicolon. On any line, all characters after a # symbol are ignored.
Finally, you can not define a variable or assign values to a variable that has the same nameas one of the script commands. For example, the following linessum = matrix(1,2);angle = acos(pi/2);
are not valid statements since 'sum' and 'angle' are script functions.
Index 295
© 2003 - 2013 Lumerical Solutions, Inc
Index' 156
- 150
! 154, 155
!= 152
" 155
# 157
% 133
& 153
* 150
/ 150
: 132
? 157
[] 132
151
| 154
~ 155
+ 150
< 153
<= 152
= 132
== 151
> 153
>= 152
abs 164
absolute 164
access 137
acos 163
addanalysisgroup 210
addbulkgen 220
addcircle 211
addcustom 211
adddevice 219
adddiffusion 219
adddipole 215
addeigenmode 214
addfdtd 214
addgaussian 216
addgridattribute 220
addgroup 209
addimage 211
addimportdope 219
addimportedsource 217
addimportgen 220
addindex 217
addition 150
addjob 266
addmaterial 276, 277
addmesh 215
addmode 215
addmodesource 215
addmovie 218
addobject 210
addpath 119
addplane 216
addpoly 212
addprofile 218
addpropagator 214
addpyramid 212
addrect 212
addring 213
addsphere 213
addstructuregroup 209
addsurface 214
addtfsf 216
addtime 217
addtogroup 230
addtriangle 213
adduserprop 231
almostequal 151
analysis group 70
analysis tools 81
and 153
angle 165
arccos 163
arcsin 162
Reference Guide296
© 2003 - 2013 Lumerical Solutions, Inc
arctan 163
array 132, 137, 138
asap 123, 124
asapexport 123
asapimport 124
asapload 124
asin 162
assign 137
assignment 132
atan 163
atan2 163
break 120
c 138
CAD layout 29
cd 115
ceil 188
centroid 184
changing CAD layout 39
clear 136
clearanalysis 273
cleardcard 274
clearjobs 266
clearmodedata 254
clearsourcedata 254
clock 116
closeall 205
comment 157
comparison 151
conj 164
conjugate 164
copy 115, 230
copydcard 273
cos 162
cosine 162
cp 115
createbeam 218
cross 168
ctranspose 175
currentfilename 117
czt 183
data export 83
date 116
del 113, 114
delete 227
deleteall 226
detail 60
dir 114
division 150
dot 168
double quote 155
edit 31
eig 169
eigenvalue 169
eigenvector 169
else 197
endl 157
eps0 138
equal 132
equal to 151
equation interpreter 76
escape 120
eval 176
exit 116
exp 166
exponential 166
exportfigure 204
feval 176
fft 178
fftk 181
fftw 180
filebasename 117
filedirectory 118
fileexists 117
fileextension 118
fileopendialog 292
filesavedialog 292
find 174
findpeaks 174
Index 297
© 2003 - 2013 Lumerical Solutions, Inc
findstring 177
finite 191
flip 170
flipelement 229
floor 188
for 196
format 121
framerate 260
gaussian 190
gds 286
gdsii 60, 286
geometry 59
get 235
getcommands 118
getdata 269
geteigensolver 256
getelectric 274
getfdtdindex 278
getglobalmonitor 237
getglobalsource 237
getindex 278
getmagnetic 274
getmaterial 277
getmodeindex 279
getnamed 236
getnamednumber 237
getnumber 236
getnumericalpermittivity 280
getpath 119
getsolver 238
getsweepdata 268
getview 259
graphics graphical rendering 60
greater than 153
greater than or equal to 152
groupscope 226
havedata 271
haveproperty 238
if 197
imag 164
image 202
imaginary 164
import 60, 286
import object 58
importbinary 246, 250
importbinary2 248
importnk 241
importnk2 243
importnkobfuscated 245
importsurface 238
importsurface2 240
inpoly 185
integrate 173
integrate2 173
interp 171
interpolate 171, 172
interptri 172
inverse 182
invfft 182
killwizard 291
layoutmode 209
legend 202
length 166
less than 153
less than or equal to 152
linecross 188
lineintersect 187
linspace 133
ln 165
load 113, 121
loaddata 121
location 59
log 165
log10 165
loop 196
ls 114
main 30
main title bar 29
Reference Guide298
© 2003 - 2013 Lumerical Solutions, Inc
material 59
material database 42
matlab 83, 125
matlabget 127
matlabput 127
matlabsave 124
matrix 133, 138, 169
max 168
mesh 54
mesh refinement region 65
meshgrid3dx 135
meshgrid3dy 135
meshgrid3dz 136
meshgrid4d 136
meshgridx 134
meshgridy 135
message 288
min 168
mod 189
modulus 189
monitor 70
mouse mode 33
move 116, 229
moving windows 39
mu0 138
multiplication 150
multiply 169
mv 116
natural 165
negative 150
newmode 112
newproject 112
newwizard 289
newwizardpage 289
normal 190
not 152, 154, 155
num2str 175
object tree 37
Optimization 101
or 154
orbit 259
order 54
output 157
Particle Swarm Optimization 101
path 119
pause 120
permeability 138
permittivity 138
permute 170
phase 165
pi 138
pinch 167
plot 198
plotxy 199
polar 200
polar2 200
polarimage 201
polyand 186
polyarea 183
polydiff 186
polygrow 185
polyintersect 184
polyor 186
polyxor 187
power 151
priorities 54
product 168
PSO 101
pwd 115
quit 116
rand 190
randmatrix 133
random 190
randreset 191
readdata 122
real 164
redo 260
redraw 256
Index 299
© 2003 - 2013 Lumerical Solutions, Inc
redrawmode 257
redrawoff 257
redrawon 257
replace 177
replacestring 178
reshape 170
rm 114
rotations 60
round 189
run 118
runanalysis 270
runjobs 266
running a simulation 80
runparallel 265
runsetup 235
runsweep 267
runwizard 291
save 113, 121, 122
savedata 121
savedcard 122
screen 157
script 118
scripting editor prompt command line 38
seed 191
select 227
selectall 226, 227
selectfigure 204
selectpartial 228
set 231
seteigensolver 255
setglobalmonitor 232
setglobalsource 233
setmaterial 277
setnamed 232
setplot 204
setsourcesignal 252
setview 258
shiftselect 228
shiftselectpartial 229
sign 189
simulation 35
simulation region 65
sin 162
sine 162
single quote 156
size 59, 166
solar 191
speed of light 138
spline 172
sqrt 166
square root 166
str2num 176
string to number 176
strings 155, 156
structure 58
structures group 58
substring 176
subtraction 150
sum 167
switchtolayout 208
system 116
tan 162
tangent 162
time 116
time stamp 116
timestamp 116
toolbar 30
transparency 60
transpose 175
undo 260
unselectall 227
unwrap 165
updatemodes 253
updatesourcemode 251
variables with spaces 133
view 34
view ports perspective 36
visualize 203
Reference Guide300
© 2003 - 2013 Lumerical Solutions, Inc
which 119
wizarddata 290
wizardgetdata 291
wizardoption 292
wizardwidget 289
workspace 136
write 123
z-transform 183