MEEP documentation » Scheme Interface » User Interface

Scheme User Interface

The Scheme user interface is documented in this page. We do not document the Scheme language or
the functions provided by libctl. See also the libctl User Reference.

This page is simply a compact listing of the functions exposed by the interface. For a gentler
introduction, see Tutorial/Basics. Also, we note that this page is not a complete listing of all
functions. In particular, because of the SWIG wrappers, every function in the C++ interface is
accessible from Scheme, but not all of these functions are documented or intended for end users.

See also the instructions for parallel Meep for MPI machines.

TABLE OF CONTENTS
Scheme User Interface
Input Variables
Prede�ned Variables
Constants (Enumerated Types)
Classes
lattice
material
geometric-object
symmetry
pml
absorber
source
�ux-region
Miscellaneous Functions
Geometry Utilities
Output File Names
Misc.
Field Computations
Reloading Parameters
Flux Spectra
Force Spectra
LDOS spectra
Near-to-Far-Field Spectra
Frequency-Domain Solver
Run and Step Functions
Run Functions
Prede�ned Step Functions
Output Functions
 Harminv
Step-Function Modi�ers
Miscellaneous Step-Function Modi�ers
Controlling When a Step Function Executes
Modifying HDF5 Output
Writing Your Own Step Functions
Low-Level Functions
Initializing the Structure and Fields
SWIG Wrappers

Input Variables
These are global variables that you can set to control various parameters of the Meep computation.
In brackets after each variable is the type of value that it should hold. The classes, complex
datatypes like geometric-object , are described in a later subsection. The basic datatypes, like
integer , boolean , cnumber , and vector3 , are de�ned by libctl.

geometry [ list of geometric-object class ]

           Speci�es the geometric objects making up the structure being simulated. When objects
overlap, later objects in the list take precedence. Defaults to no objects (empty list).

sources [ list of source class ]

           Speci�es the current sources to be present in the simulation. Defaults to none.

symmetries [ list of symmetry class ]

           Speci�es the spatial (mirror/rotation) symmetries to exploit in the simulation. Defaults to none.
The symmetries must be obeyed by both the structure and by the sources. See also Exploiting
Symmetry.

pml-layers [ list of pml class ]

           Speci�es the absorbing PML boundary layers to use; defaults to none.

geometry-lattice [ lattice class ]

           Speci�es the size of the unit cell which is centered on the origin of the coordinate system. Any
sizes of no-size imply a reduced-dimensionality calculation. A 2d calculation is especially
optimized. See dimensions below. Defaults to a cubic cell of unit size.

default-material [ material-type class ]

           Holds the default material that is used for points not in any object of the geometry list. Defaults
to air (ε of 1). See also epsilon-input-file below.

epsilon-input-file [ string ]
           If this string is not empty (the default), then it should be the name of an HDF5 �le whose
�rst/only dataset de�nes a scalar dielectric function over some discrete grid. Alternatively, the
dataset name can be speci�ed explicitly if the string is in the form "�lename:dataset". This dielectric
function is then used in place of the ε property of default-material (i.e. where there are no
geometry objects). The grid of the epsilon �le dataset need not match Meep's computational grid; it
is scaled and/or linearly interpolated as needed to map the �le onto the computational cell (which
warps the structure if the proportions of the grids do not match, however). Note: the �le contents
only override the ε property of the default-material , whereas other properties (μ, susceptibilities,
nonlinearities, etc.) of default-material are still used.

dimensions [ integer ]
           Explicitly speci�es the dimensionality of the simulation, if the value is less than 3. If the value is
3 (the default), then the dimensions are automatically reduced to 2 if possible when
geometry-lattice size in the z direction is no-size . If dimensions is the special value of

CYLINDRICAL , then cylindrical coordinates are used and the x and z dimensions are interpreted as r
and z , respectively. If dimensions is 1, then the cell must be along the z direction and only Ex and
Hy �eld components are permitted. If dimensions is 2, then the cell must be in the xy plane.

m [ number ]
           For CYLINDRICAL simulations, speci�es that the angular φ dependence of the �elds is of the
form e imϕ
(default is m=0 ). If the simulation cell includes the origin r = 0, then m must be an
integer.

accurate-fields-near-cylorigin? [ boolean ]
          For CYLINDRICAL simulations with |m| > 1, compute more accurate �elds near the origin r = 0
at the expense of requiring a smaller Courant factor. Empirically, when this option is set to true ,a
Courant factor of roughly min[0.5, 1/(|m| + 0.5)]or smaller seems to be needed. The default is
false , in which case the Dr , Dz , and Br �elds within |m| pixels of the origin are forced to zero,

which usually ensures stability with the default Courant factor of 0.5, at the expense of slowing
convergence of the �elds near r = 0.

resolution [ number ]
           Speci�es the computational grid resolution in pixels per distance unit. Defaults to 10.

k-point [ false or vector3 ]

           If false (the default), then the boundaries are perfect metallic (zero electric �eld). If a vector,
then the boundaries are Bloch-periodic: the �elds at one side are exp(ik ⋅ R) times the �elds at the
other side, separated by the lattice vector R. The k-point vector is speci�ed in Cartesian
coordinates in units of 2π/distance. Note: this is different from MPB, equivalent to taking MPB's
k-points through the function reciprocal->cartesian .

ensure-periodicity [ boolean ]
           If true (the default) and if the boundary conditions are periodic ( k-point is not false ), then
the geometric objects are automatically repeated periodically according to the lattice vectors which
de�ne the size of the computational cell.

eps-averaging? [ boolean ]
           If true (the default), then subpixel averaging is used when initializing the dielectric function.
See the reference publication. The input variables subpixel-maxeval (default 104) and subpixel-tol

(default 10-4) specify the maximum number of function evaluations and the integration tolerance for
subpixel averaging. Increasing/decreasing these, respectively, will cause a more accurate but slower
computation of the average ε with diminishing returns for the actual FDTD error.

force-complex-fields? [ boolean ]
           By default, Meep runs its simulations with purely real �elds whenever possible. It uses complex
�elds which require twice the memory and computation if the k-point is non-zero or if m is non-
zero. However, by setting force-complex-fields? to true , Meep will always use complex �elds.

filename-prefix [ string ]
           A string prepended to all output �lenames. If empty (the default), then Meep uses the name of
the current ctl �le, with ".ctl" replaced by "-" (e.g. foo.ctl uses a "foo-" pre�x). See also Output File
Names.

Courant [ number ]
           Specify the Courant factor S which relates the time step size to the spatial discretization:
cΔt = SΔx. Default is 0.5 . For numerical stability, the Courant factor must be at most
−−−−−−−−−−−
nmin /√# dimensions, where nmin is the minimum refractive index (usually 1), and in practice S
should be slightly smaller.

output-volume [ meep::geometric_volume* ]
           Speci�es the default region of space that is output by the HDF5 output functions (below); see
also the (volume ...) function to create meep::geometric_volume* objects. The default is '()
(null), which means that the whole computational cell is output. Normally, you should use the
(in-volume ...) function to modify the output volume instead of setting output-volume directly.

output-single-precision? [ boolean ]
           Meep performs its computations in double precision, and by default its output HDF5 �les are in
the same format. However, by setting this variable to true (default is false ) you can instead
output in single precision which saves a factor of two in space.

progress-interval [ number ]
           Time interval (seconds) after which Meep prints a progress message. Default is 4 seconds.

extra-materials [ list of material-type class ]

           By default, Meep turns off support for material dispersion, nonlinearities, and similar
properties if none of the objects in the geometry have materials with these properties—since they
are not needed, it is faster to omit their calculation. This doesn't work however if you use a
material-function : materials via a user-speci�ed function of position instead of just geometric

objects. If only your material function returns a nonlinear material, for example, Meep won't notice
this unless you tell it explicitly via extra-materials . extra-materials is a list of materials that Meep
should look for in the computational cell in addition to any materials that are speci�ed by geometric
objects. You should list any materials other than scalar dielectrics that are returned by
material-function s here.
The following require a bit more understanding of the inner workings of Meep to use. See also SWIG
wrappers.

structure [ meep::structure* ]
           Pointer to the current structure being simulated; initialized by (init-structure) which is
called automatically by (init-fields) which is called automatically by any of the (run) functions.

fields [ meep::fields* ]
           Pointer to the current �elds being simulated; initialized by (init-fields) which is called
automatically by any of the (run) functions.

num-chunks [ integer ]
           Minimum number of "chunks" (subarrays) to divide the structure/�elds into (default 0). Actual
number is determined by number of processors, PML layers, etcetera. Mainly useful for debugging.

Prede�ned Variables
air , vacuum [ material-type class ]
           Two aliases for a prede�ned material type with a dielectric constant of 1.

perfect-electric-conductor or metal [ material-type class ]

           A prede�ned material type corresponding to a perfect electric conductor at the boundary of
which the parallel electric �eld is zero. Technically, ε = −∞.

perfect-magnetic-conductor [ material-type class ]

           A prede�ned material type corresponding to a perfect magnetic conductor at the boundary of
which the parallel magnetic �eld is zero. Technically, μ = −∞.

nothing [ material-type class ]

           A material that, effectively, punches a hole through other objects to the background
( default-material ).

infinity [ number ]
          A big number (1.0e20) to use for "in�nite" dimensions of objects.

pi [ number ]
          π (3.14159...).

Constants (Enumerated Types)

Several of the functions/classes in Meep ask you to specify e.g. a �eld component or a direction in
the grid. These should be one of the following constants:

direction constants
           Specify a direction in the grid. One of X , Y , Z , R , P for x , y, z , r, ϕ, respectively.
boundary-side constants
           Specify particular boundary in some direction (e.g. +x or −x). One of Low or High .

component constants
           Specify a particular �eld or other component. One of Ex , Ey , Ez , Er , Ep , Hx , Hy , Hz , Hy ,
Hp , Hz , Bx , By , Bz , By , Bp , Bz , Dx , Dy , Dz , Dr , Dp , Dielectric , Permeability , for Ex , Ey ,
Ez , Er , Eϕ , Hx , Hy , Hz , Hr , Hϕ , Bx , By , Bz , Br , Bϕ , Dx , Dy , Dz , Dr , Dϕ , ε , μ, respectively.

derived-component constants
           These are additional components which are not actually stored by Meep but are computed as
needed, mainly for use in output functions. One of Sx , Sy , Sz , Sr , Sp , EnergyDensity ,
D-EnergyDensity , H-EnergyDensity for Sx , Sy , Sz , Sr , Sϕ (components of the Poynting vector
Re E × H), (E ⋅ D + H ⋅ B)/2, E∗ ⋅ D/2, H∗ ⋅ B/2, respectively.
∗ ∗ ∗

Classes
Classes are complex datatypes with various "properties" which may have default values. Classes can
be "subclasses" of other classes. Subclasses inherit all the properties of their superclass and can be
used in any place the superclass is expected. An object of a class is constructed with:

(make class (prop1 val1) (prop2 val2) ...)

See also the libctl manual.

Meep de�nes several types of classes, the most numerous of which are the various geometric object
classes which are the same as those used in MPB. You can also get a list of the available classes,
along with their property types and default values, at runtime with the (help) command.

lattice

The lattice class is normally used only for the geometry-lattice variable, which sets the size of the
computational cell. In MPB, you can use this to specify a variety of af�ne lattice structures. In Meep,
only rectangular Cartesian computational cells are supported, so the only property of lattice that
you should normally use is its size .

size [ vector3 ]
           The size of the computational cell. Defaults to unit lengths.

If any dimension has the special size no-size , then the dimensionality of the problem is essentially
reduced by one. Strictly speaking, the dielectric function is taken to be uniform along that
dimension.

Because Maxwell's equations are scale-invariant, you can use any units of distance you want to
specify the cell size: nanometers, inches, parsecs, whatever. However, it is usually convenient to pick
some characteristic lengthscale of your problem and set that length to 1. See also Units.
material

This class is used to specify the materials that geometric objects are made of. Currently, there are
three subclasses, dielectric , perfect-metal , and material-function .

medium

An electromagnetic medium which is possibly nonlinear and/or dispersive. See also Materials. For
backwards compatibility, a synonym for medium is dielectric . It has several properties:

epsilon [ number ]
          The frequency-independent isotropic relative permittivity or dielectric constant. Default is 1.
You can also use (index n) as a synonym for (epsilon (* n n)) ; note that this is not really the
refractive index if you also specify μ, since the true index is √−−.
με

Using (epsilon $\varepsilon$) is actually a synonym for

(epsilon-diag $\varepsilon$ $\varepsilon$ $\varepsilon$) .

epsilon-diag and epsilon-offdiag [ vector3 ]

           These properties allow you to specify ε as an arbitrary real-symmetric tensor by giving the
diagonal and offdiagonal parts. Specifying (epsilon-diag a b c) and/or (epsilon-offdiag u v

w) corresponds to a relative permittivity ε tensor

⎛a u v⎞
⎜u w⎟
⎝v c⎠
b
w

The default is the identity matrix (a = b = c = 1 and u = v = w = 0).

mu [ number ]
           The frequency-independent isotropic relative permeability μ. Default is 1. Using (mu $\mu$) is
actually a synonym for (mu-diag $\mu$ $\mu$ $\mu$) .

mu-diag and mu-offdiag [ vector3 ]

           These properties allow you to specify μ as an arbitrary real-symmetric tensor by giving the
diagonal and offdiagonal parts exactly as for ε above. Default is the identity matrix.

D-conductivity [ number ]
          The frequency-independent electric conductivity σD . Default is 0. You can also specify an
diagonal anisotropic conductivity tensor by using the property D-conductivity-diag [ vector3 ],
which takes three numbers or a [ vector3 ] to give the σD tensor diagonal. See also Conductivity.

B-conductivity [ number ]
          The (frequency-independent) magnetic conductivity σB . Default is 0. You can also specify an
diagonal anisotropic conductivity tensor by using the property B-conductivity-diag [vector3],
which takes three numbers or a [vector3] to give the σB tensor diagonal. See also Conductivity.
chi2 [ number ]
          The nonlinear (Pockels) susceptibility χ(2) . Default is 0. See also Nonlinearity.

chi3 [ number ]
          The nonlinear (Kerr) susceptibility χ(3) . Default is 0. See also Nonlinearity.

E-susceptibilities [ list of susceptibility class ]

          List of dispersive susceptibilities (see below) added to the dielectric constant ε in order to
model material dispersion. Defaults to none. See also Material Dispersion. For backwards
compatibility, synonyms of E-susceptibilities are E-polarizations and polarizations .

H-susceptibilities [ list of susceptibility class ]

          List of dispersive susceptibilities (see below) added to the permeability μ in order to model
material dispersion. Defaults to none. See also Material Dispersion. For backwards compatibility, a
synonym of H-susceptibilities is perfect-metal .

perfect-metal

A perfectly conducting metal. This class has no properties and you normally just use the prede�ned
metal object, above. To model imperfect conductors, use a dispersive dielectric material. See also

the prede�ned variables metal , perfect-electric-conductor , and perfect-magnetic-conductor

above.

material-function

This material type allows you to specify the material as an arbitrary function of position. It has one
property:

material-func [ function ]
          A function of one argument, the position vector3 , that returns the material at that point. Note
that the function you supply can return any material. It's even possible to return another
material-function object which would then have its function invoked in turn.

Instead of material-func , you can use epsilon-func : give it a function of position that returns the
dielectric constant at that point.

Important: If your material function returns nonlinear, dispersive (Lorentzian or conducting), or

magnetic materials, you should also include a list of these materials in the extra-materials input
variable (above) to let Meep know that it needs to support these material types in your simulation.
For dispersive materials, you need to include a material with the same γ n and μn values, so you can
only have a �nite number of these, whereas σ n can vary continuously if you want and a matching σ n
need not be speci�ed in extra-materials . For nonlinear or conductivity materials, your
extra-materials list need not match the actual values of σ or χ returned by your material function,
which can vary continuously if you want.

Complex ε and μ: you cannot specify a frequency-independent complex ε or μ in Meep where the
imaginary part is a frequency-independent loss but there is an alternative. That is because there are
only two important physical situations. First, if you only care about the loss in a narrow bandwidth
around some frequency, you can set the loss at that frequency via the conductivity (see
Conductivity). Second, if you care about a broad bandwidth, then all physical materials have a
frequency-dependent complex ε and/or μ, and you need to specify that frequency dependence by
�tting to Lorentzian and/or Drude resonances via the lorentzian-susceptibility or
drude-susceptibility classes below.

Dispersive dielectric and magnetic materials, above, are speci�ed via a list of objects that are
subclasses of type susceptibility .

susceptibility

Parent class for various dispersive susceptibility terms, parameterized by an anisotropic amplitude
σ . See Material Dispersion.

sigma [ number ]
          The scale factor σ . You can also specify an anisotropic σ tensor by using the property
sigma-diag [vector3], which takes three numbers or a [vector3] to give the σn tensor diagonal, and

sigma-offdiag [vector3] which speci�es the offdiagonal elements (defaults to 0). That is,
(sigma-diag a b c) and (sigma-offdiag u v w) corresponds to a σ tensor

⎛a u v⎞
⎜u w⎟
⎝v c⎠
b
w

lorentzian-susceptibility

Speci�es a single dispersive susceptibility of Lorentzian (damped harmonic oscillator) form. See
Material Dispersion, with the parameters (in addition to σ ):

frequency [ number ]
          The resonance frequency fn = ωn /2π.

gamma [ number ]
          The resonance loss rate γn /2π.

drude-susceptibility

Speci�es a single dispersive susceptibility of Drude form. See Material Dispersion, with the
parameters (in addition to σ ):

frequency [ number ]
          The frequency scale factor fn = ωn /2π which multiplies σ (not a resonance frequency).

gamma [ number ]
          The loss rate γn /2π.

Meep also supports a somewhat unusual polarizable medium, a Lorentzian susceptibility with a
random noise term added into the damped-oscillator equation at each point. This can be used to
directly model thermal radiation in both the far �eld and the near �eld. Note, however that it is more
ef�cient to compute far-�eld thermal radiation using Kirchhoff's law of radiation, which states that
emissivity equals absorptivity. Near-�eld thermal radiation can usually be computed more
ef�ciently using frequency domain techniques, e.g. via our SCUFF-EM code.

noisy-lorentzian-susceptibility or noisy-drude-susceptibility

Speci�es a single dispersive susceptibility of Lorentzian (damped harmonic oscillator) or Drude

form. See Material Dispersion, with the same σ, frequency , and gamma ) parameters, but with an
additional Gaussian random noise term (uncorrelated in space and time, zero mean) added to the P
damped-oscillator equation.

noise-amp [ number ]
          The noise has root-mean square amplitude σ⋅ noise-amp .

geometric-object

This class, and its descendants, are used to specify the solid geometric objects that form the
dielectric structure being simulated. The base class is:

geometric-object

Properties:

material [ material-type class ]

          The material that the object is made of (usually some sort of dielectric). No default value (must
be speci�ed).

center [ vector3 ]
          Center point of the object. No default value.

One normally does not create objects of type geometric-object directly, however; instead, you use
one of the following subclasses. Recall that subclasses inherit the properties of their superclass, so
these subclasses automatically have the material and center properties (which must be speci�ed,
since they have no default values).

In a two-dimensional calculation, only the intersections of the objects with the x-y plane are
considered.

sphere

A sphere. Properties:
radius [ number ]
          Radius of the sphere. No default value.

cylinder

A cylinder, with circular cross-section and �nite height. Properties:

radius [ number ]
          Radius of the cylinder's cross-section. No default value.

height [ number ]
          Length of the cylinder along its axis. No default value.

axis [ vector3 ]
          Direction of the cylinder's axis; the length of this vector is ignored. Defaults to point parallel to
the z axis.

cone

A cone, or possibly a truncated cone. This is actually a subclass of cylinder , and inherits all of the
same properties, with one additional property. The radius of the base of the cone is given by the
radius property inherited from cylinder , while the radius of the tip is given by the new property,

radius2 . The center of a cone is halfway between the two circular ends.

radius2 [ number ]
          Radius of the tip of the cone (i.e. the end of the cone pointed to by the axis vector). Defaults to
zero (a "sharp" cone).

block

A parallelepiped (i.e., a brick, possibly with non-orthogonal axes). Properties:

size [ vector3 ]
          The lengths of the block edges along each of its three axes. Not really a 3-vector, but it has three
components, each of which should be nonzero. No default value.

e1 , e2 , e3 [ vector3 ]
          The directions of the axes of the block; the lengths of these vectors are ignored. Must be
linearly independent. They default to the three lattice directions.

ellipsoid

An ellipsoid. This is actually a subclass of block , and inherits all the same properties, but de�nes an
ellipsoid inscribed inside the block.

Here are some examples of geometric objects created using the above classes, assuming mat is
some material we have de�ned:

; A cylinder of infinite radius and height 0.25 pointing along the x axis,
; centered at the origin:
(make cylinder (center 0 0 0) (material mat)
               (radius infinity) (height 0.25) (axis 1 0 0))

; An ellipsoid with its long axis pointing along (1,1,1), centered on
; the origin (the other two axes are orthogonal and have equal
; semi-axis lengths):
(make ellipsoid (center 0 0 0) (material mat)
                (size 0.8 0.2 0.2)
                (e1 1 1 1)
                (e2 0 1 -1)
                (e3 -2 1 1))

; A unit cube of material m with a spherical air hole of radius 0.2 at
; its center, the whole thing centered at (1,2,3):
(set! geometry (list
               (make block (center 1 2 3) (material mat) (size 1 1 1))
               (make sphere (center 1 2 3) (material air) (radius 0.2))))

symmetry

This class is used for the symmetries input variable to specify symmetries which must preserve both
the structure and the sources for Meep to exploit. Any number of symmetries can be exploited
simultaneously but there is no point in specifying redundant symmetries: the computational cell can
be reduced by at most a factor of 4 in 2d and 8 in 3d. See also Exploiting Symmetry.

symmetry

A single symmetry to exploit. This is the base class of the speci�c symmetries below, so normally you
don't create it directly. However, it has two properties which are shared by all symmetries:

direction [ direction constant ]

           The direction of the symmetry (the normal to a mirror plane or the axis for a rotational
symmetry). e.g. X , Y , ... (only Cartesian/grid directions are allowed). No default value.

phase [ cnumber ]
           An additional phase to multiply the �elds by when operating the symmetry on them; defaults to
1.0 . e.g. a phase of -1 for a mirror plane corresponds to an odd mirror. Technically, you are

essentially specifying the representation of the symmetry group that your �elds and sources
transform under.

The speci�c symmetry sub-classes are:

mirror-sym

           A mirror symmetry plane. Here, the direction is the direction normal to the mirror plane.
rotate2-sym

           A 180° (twofold) rotational symmetry (a.k.a. C2 ). Here, the direction is the axis of the
rotation.

rotate4-sym

           A 90° (fourfold) rotational symmetry (a.k.a. C4 ). Here, the direction is the axis of the rotation.

pml

This class is used for specifying the PML absorbing boundary layers around the cell, if any, via the
pml-layers input variable. See also Perfectly Matched Layers. pml-layers can be zero or more pml

objects, with multiple objects allowing you to specify different PML layers on different boundaries.

pml

A single PML layer speci�cation, which sets up one or more PML layers around the boundaries
according to the following properties.

thickness [ number ]
          The spatial thickness of the PML layer (which extends from the boundary towards the inside of
the computational cell). The thinner it is, the more numerical re�ections become a problem. No
default value.

direction [ direction constant ]

          Specify the direction of the boundaries to put the PML layers next to. e.g. if X , then speci�es
PML on the ±x boundaries (depending on the value of side , below). Default is the special value
ALL , which puts PML layers on the boundaries in all directions.

side [ boundary-side constant ]

          Specify which side, Low or High of the boundary or boundaries to put PML on. e.g. if side is
Low and direction is X , then a PML layer is added to the −x boundary. Default is the special value
ALL , which puts PML layers on both sides.

strength [ number ]
          A strength (default is 1.0 ) to multiply the PML absorption coef�cient by. A strength of 2.0 will
square the theoretical asymptotic re�ection coef�cient of the PML (making it smaller), but will also
increase numerical re�ections. Alternatively, you can change R-asymptotic , below.

R-asymptotic [ number ]
          The asymptotic re�ection in the limit of in�nite resolution or in�nite PML thickness, for
refections from air (an upper bound for other media with index > 1). (For a �nite resolution or
thickness, the re�ection will be much larger, due to the discretization of Maxwell's equation.) The
default value is 10−15, which should suf�ce for most purposes. (You want to set this to be small
enough so that waves propagating within the PML are attenuated suf�ciently, but making
R-asymptotic too small will increase the numerical re�ection due to discretization.)
pml-profile [ function ]
          By default, Meep turns on the PML conductivity quadratically within the PML layer—one
doesn't want to turn it on suddenly, because that exacerbates re�ections due to the discretization.
More generally, with pml-profile one can specify an arbitrary PML "pro�le" function f(u) that
determines the shape of the PML absorption pro�le up to an overall constant factor. u goes from 0 to
1 at the start and end of the PML, and the default is f(u)=u2. In some cases where a very thick PML is
required, such as in a periodic medium (where there is technically no such thing as a true PML, only a
pseudo-PML), it can be advantageous to turn on the PML absorption more smoothly (see Oskooi et
al., 2008). For example, one can use a cubic pro�le f(u)=u3 by specifying (pml-profile (lambda (u)
(* u u u))) .

absorber

Instead of a pml layer, there is an alternative class called absorber which is a drop-in replacement
for pml . For example, you can do (set! pml-layers (list (make absorber (thickness 2))))

instead of (set! pml-layers (list (make pml (thickness 2)))) . All the parameters are the
same as for pml , above. You can have a mix of pml on some boundaries and absorber on others.

The absorber class does not implement a perfectly matched layer (PML), however (except in 1d).
Instead, it is simply a scalar electric and magnetic conductivity that turns on gradually within the
layer according to the pml-profile (defaulting to quadratic). Such a scalar conductivity gradient is
only re�ectionless in the limit as the layer becomes suf�ciently thick.

The main reason to use absorber is if you have a case in which PML fails:

No true PML exists for periodic media, and a scalar absorber is cheaper and is generally just as
good. See Oskooi et al. (2008).
PML can lead to divergent �elds for certain waveguides with "backward-wave" modes; this can
easily happen in metallic with surface plasmons, and a scalar absorber is your only choice. See
Loh et al. (2009).
PML can fail if you have a waveguide hitting the edge of your computational cell at an angle. See
Oskooi et. al. (2011).

source

The source class is used to specify the current sources (via the sources input variable). Note that
all sources in Meep are separable in time and space, i.e. of the form J(x, t) = A(x) ⋅ f(t) for some
functions A and f . (Non-separable sources can be simulated, however, by modifying the sources
after each time step.) When real �elds are being used (which is the default in many cases...see the
force-complex-fields? input variable), only the real part of the current source is used by Meep.

Important note: These are current sources (J terms in Maxwell's equations), even though they are
labelled by electric/magnetic �eld components. They do not specify a particular electric/magnetic
�eld (which would be what is called a "hard" source in the FDTD literature). There is no �xed
relationship between the current source and the resulting �eld amplitudes; it depends on the
surrounding geometry, as described in the FAQ and in this book chapter.
source

The source class has the following properties:

src [ src-time class ]

          Specify the time-dependence of the source (see below). No default.

component [ component constant ]

          Specify the direction and type of the current component: e.g. Ex , Ey , etcetera for an electric-
charge current, and Hx , Hy , etcetera for a magnetic-charge current. Note that currents pointing in
an arbitrary direction are speci�ed simply as multiple current sources with the appropriate
amplitudes for each component. No default.

center [ vector3 ]
          The location of the center of the current source in the computational cell; no default.

size [ vector3 ]
          The size of the current distribution along each direction of the computational cell. The default is
(0,0,0): a point-dipole source.

amplitude [ cnumber ]
          An overall (complex) amplitude multiplying the the current source. Default is 1.0 .

amp-func [ function ]
          A Scheme function of a single argument, that takes a vector3 giving a position and returns a
(complex) current amplitude for that point. The position argument is relative to the center of the
current source, so that you can move your current around without changing your function. The
default is '() (null), meaning that a constant amplitude of 1.0 is used. Note that your amplitude
function (if any) is multiplied by the amplitude property, so both properties can be used
simultaneously.

As described in section 4.2 of this book chapter, it is also possible to supply a source that is designed
to couple exclusively into a single waveguide mode (or other mode of some cross section or periodic
region) at a single frequency, and which couples primarily into that mode as long as the bandwidth is
not too broad. This is possible if you have MPB installed: Meep will call MPB to compute the �eld
pro�le of the desired mode, and uses the �eld pro�le to produce an equivalent current source.
(Note: this feature does not work in cylindrical coordinates.) To do this, instead of a source you
should use an eigenmode-source :

eigenmode-source

This is a subclass of source and has all of the properties of source above. However, you normally
do not specify a component . Instead of component , the current source components and amplitude
pro�le are computed by calling MPB to compute the modes of the dielectric pro�le in the region
given by the size and center of the source, with the modes computed as if the source region were
repeated periodically in all directions. If an amplitude and/or amp-func are supplied, they are
multiplied by this current pro�le. The desired eigenmode and other features are speci�ed by the
following properties:

eig-band [ integer ]
          The index n (1,2,3,...) of the desired band ωn(k) to compute in MPB (1 denotes the lowest-
frequency band at a given k point, and so on).

direction [ X , Y , or Z; default AUTOMATIC ], eig-match-freq? [ boolean; default true ],

eig-kpoint [ vector3 ]
          By default (if eig-match-freq? is true ), Meep tries to �nd a mode with the same frequency
ωn(k) as the src property (above), by scanning k vectors in the given direction using MPB's �nd-k
functionality. Alternatively, if eig-kpoint is supplied, it is used as an initial guess and direction for k.
By default, direction is the direction normal to the source region, assuming size is d–1
dimensional in a d-dimensional simulation (e.g. a plane in 3d). Alternatively (if eig-match-freq? is
false ), you can specify a particular k vector of the desired mode with eig-kpoint (in Meep units of
2π/a).

eig-parity [ NO-PARITY (= default), EVEN-Z (= TE ), ODD-Z (= TM ), EVEN-Y , ODD-Y ]

          The parity (= polarization in 2d) of the mode to calculate, assuming the structure has z and/or y
mirror symmetry in the source region. If the structure has both y and z mirror symmetry, you can
combine more than one of these, e.g. EVEN-Z + ODD-Y . The default is NO-PARITY , in which case MPB
computes all of the bands which will still be even or odd if the structure has mirror symmetry, of
course. This is especially useful in 2d simulations to restrict yourself to a desired polarization.

eig-resolution [ integer , defaults to same as Meep resolution ]

          The spatial resolution to use in MPB for the eigenmode calculations. This defaults to the same
resolution as Meep, but you can use a higher resolution in which case the structure is linearly
interpolated from the Meep pixels.

eig-tolerance [ number , defaults to 10–7 ]

          The tolerance to use in the MPB eigensolver. MPB terminates when the eigenvalues stop
changing to less than this fractional tolerance.

component [as above, but defaults to ALL-COMPONENTS ]

          Once the MPB modes are computed, equivalent electric and magnetic sources are created
within Meep. By default, these sources include magnetic and electric currents in all transverse
directions within the source region, corresponding to the mode �elds as described in the book
chapter. If you specify a component property, however, you can include only one component of these
currents if you wish. Most people won't need this feature.

eig-lattice-size [ vector3 ], eig-lattice-center [ vector3 ]

          Normally, the MPB computational unit cell is the same as the source volume (given by the size

and center parameters). However, occasionally you want the unit cell to be larger than the source
volume. For example, to create an eigenmode source in a periodic medium (photonic crystal), you
need to pass MPB the entire unit cell of the periodic medium, but once the mode is computed then
the actual current sources need only lie on a cross section of that medium. To accomplish this, you
can specify the optional eig-lattice-size and eig-lattice-center , which de�ne a volume (which
must enclose size and center ) that is used for the unit cell in MPB with the dielectric function ε
taken from the corresponding region in the Meep simulation.

Note that MPB only supports dispersionless non-magnetic materials but it does support anisotropic
ε . Any nonlinearities, magnetic responses μ, conductivities σ , or dispersive polarizations in your
materials will be ignored when computing the eigenmode source. PML will also be ignored.

The src-time object, which speci�es the time dependence of the source, can be one of the following
three classes.

continuous-src

A continuous-wave source proportional to exp(−iωt), possibly with a smooth (exponential/tanh)

turn-on/turn-off. It has the properties:

frequency [ number ]
          The frequency f in units of c/distance (or ω in units of 2πc/distance). See: Units. No default
value. You can instead specify (wavelength x) or (period x) , which are both a synonym for
(frequency (/ 1 x)) ; i.e. 1/ω in these units is the vacuum wavelength or the temporal period.

start-time [ number ]
          The starting time for the source; default is 0 (turn on at t = 0).

end-time [ number ]
          The end time for the source; default is infinity (never turn off).

width [ number ]
          Roughly, the temporal width of the smoothing (technically, the inverse of the exponential rate at
which the current turns off and on). Default is 0 (no smoothing). You can instead specify (fwidth
x) , which is a synonym for (width (/ 1 x)) (i.e. the frequency width is proportional to the
inverse of the temporal width).

cutoff [ number ]
          How many width s the current decays for before we cut it off and set it to zero; the default is
3.0 . A larger value of cutoff will reduce the amount of high-frequency components that are
introduced by the start/stop of the source, but will of course lead to longer simulation times.

gaussian-src

A Gaussian-pulse source roughly proportional to exp(−iωt − (t − t0 )2 /2w2 ). Technically, the

"Gaussian" sources in Meep are the (discrete-time) derivative of a Gaussian, i.e. they are
∂
(−iω)−1 ∂t exp(−iωt − (t − t0 )2 /2w2 ), but the difference between this and a true Gaussian is
usually irrelevant. It has the properties:
frequency [ number ]
          The center frequency f in units of c/distance (or ω in units of 2π c/distance). See Units. No
default value. You can instead specify (wavelength x) or (period x) , which are both a synonym
for (frequency (/ 1 x)) ; i.e. 1/ω in these units is the vacuum wavelength or the temporal period.

width [ number ]
          The width w used in the Gaussian. No default value. You can instead specify (fwidth x) , which
is a synonym for (width (/ 1 x)) (i.e. the frequency width is proportional to the inverse of the
temporal width).

start-time [ number ]
          The starting time for the source; default is 0 (turn on at t = 0). Not the time of the peak! See
below.

cutoff [ number ]
          How many width s the current decays for before we cut it off and set it to zero—this applies for
both turn-on and turn-off of the pulse. The default is 5.0 . A larger value of cutoff will reduce the
amount of high-frequency components that are introduced by the start/stop of the source, but will
of course lead to longer simulation times. The peak of the gaussian is reached at the time
t0=  start-time  +  cutoff * width .

custom-src

           A user-speci�ed source function f(t). You can also specify start/end times (at which point your
current is set to zero whether or not your function is actually zero). These are optional, but you must
specify an end-time explicitly if you want functions like run-sources to work, since they need to
know when your source turns off.

src-func [ function ]
          The function f(t) specifying the time-dependence of the source. It should take one argument
(the time in Meep units) and return a complex number.

start-time [ number ]
          The starting time for the source. Default is (-infinity) : turn on at t = −∞). Note, however,
that the simulation normally starts at t = 0 with zero �elds as the initial condition, so there is
implicitly a sharp turn-on at t = 0 whether you specify it or not.

end-time [ number ]
          The end time for the source; default is infinity (never turn off).

�ux-region

A flux-region object is used with add-flux below to specify a region in which Meep should
accumulate the appropriate Fourier-transformed �elds in order to compute a �ux spectrum.

flux-region
           A region (volume, plane, line, or point) in which to compute the integral of the Poynting vector
of the Fourier-transformed �elds. Its properties are:

center [ vector3 ]
         The center of the �ux region (no default).

size [ vector3 ]
         The size of the �ux region along each of the coordinate axes; default is (0,0,0) (a single point).

direction [ direction constant ]

         The direction in which to compute the �ux (e.g. X , Y , etcetera). The default is AUTOMATIC , in
which the direction is determined by taking the normal direction if the �ux region is a plane (or a
line, in 2d). If the normal direction is ambiguous (e.g. for a point or volume), then you must specify
the direction explicitly (not doing so will lead to an error).

weight [ cnumber ]
         A weight factor to multiply the �ux by when it is computed; default is 1.0 .

Note that the �ux is always computed in the positive coordinate direction, although this can
effectively be �ipped by using a weight of -1.0 . This is useful, for example, if you want to compute
the outward �ux through a box, so that the sides of the box add instead of subtract!

Miscellaneous Functions
Here, we describe a number of miscellaneous useful functions provided by Meep.

See also the libctl manual which describes a number of useful functions.

Geometry Utilities

Some utility functions are provided to help you manipulate geometric objects:

(shift-geometric-object obj shift-vector)

          Translate obj by the 3-vector shift-vector .

(geometric-object-duplicates shift-vector min-multiple max-multiple obj)

          Return a list of duplicates of obj , shifted by various multiples of shift-vector from
min-multiple to max-multiple , inclusive, in steps of 1.

(geometric-objects-duplicates shift-vector min-multiple max-multiple obj-list)

          Same as geometric-object-duplicates , except operates on a list of objects, obj-list . If A

appears before B in the input list, then all the duplicates of A appear before all the duplicates of B in
the output list.

(geometric-objects-lattice-duplicates obj-list [ ux uy uz ])

          Duplicates the objects in obj-list by multiples of the Cartesian basis vectors, making all
possible shifts of the "primitive cell" (see below) that �t inside the lattice cell. The primitive cell to
duplicate is ux by uy by uz , in units of the Cartesian basis vectors. These three parameters are
optional; any that you do not specify are assumed to be 1 .

(point-in-object? point obj)

          Returns whether or not the given 3-vector point is inside the geometric object obj .

(point-in-periodic-object? point obj)

          As point-in-object? , but also checks translations of the given object by the lattice vectors.

(display-geometric-object-info indent-by obj)

          Outputs some information about the given obj , indented by indent-by spaces.

Output File Names

The output �le names used by Meep, e.g. for HDF5 �les, are automatically pre�xed by the input
variable filename-prefix . If filename-prefix is "" (the default), however, then Meep constructs a
default pre�x based on the current ctl �le name with ".ctl" replaced by "-" : e.g. tst.ctl implies
a pre�x of "tst-" . You can get this pre�x by running:

(get-filename-prefix)

          Return the current pre�x string that is prepended, by default, to all �le names.

If you don't want to use any pre�x, then you should set filename-prefix to false .

In addition to the �lename pre�x, you can also specify that all the output �les be written into a
newly-created directory (if it does not yet exist). This is done by running:

(use-output-directory [dirname])

          Put output in a subdirectory, which is created if necessary. If the optional argument dirname is
speci�ed, that is the name of the directory. Otherwise, the directory name is the current ctl �le name
with ".ctl" replaced by "-out" : e.g. tst.ctl implies a directory of "tst-out" .

Misc.

(volume (center ...) (size ...))

          Many Meep functions require you to specify a volume in space, corresponding to the C++ type
meep::geometric_volume . This function creates such a volume object, given the center and size

properties (just like e.g. a block object). If the size is not speci�ed, it defaults to (0,0,0), i.e. a single
point.

(meep-time)

          Return the current simulation time in simulation time units, not wall-clock time!. (e.g. during a
run function.)

Occasionally, e.g. for termination conditions of the form time < T?, it is desirable to round the time to
single precision in order to avoid small differences in roundoff error from making your results
different by one timestep from machine to machine (a difference much bigger than roundoff error);
in this case you can call (meep-round-time) instead, which returns the time rounded to single
precision.

Field Computations

Meep supports a large number of functions to perform computations on the �elds. Currently, most
of them are accessed via the lower-level C++/SWIG interface, but we are slowly adding simpler,
higher-level versions of them here.

(get-field-point c pt)

          Given a component or derived-component constant c and a vector3 pt , returns the value of
that component at that point.

(get-epsilon-point pt)

          Equivalent to (get-field-point Dielectric pt) .

(flux-in-box dir box)

          Given a direction constant, and a meep::volume* , returns the �ux (the integral of R[E∗ × H])
in that volume. Most commonly, you specify a volume that is a plane or a line, and a direction
perpendicular to it, e.g. (flux-in-box X (volume (center 0) (size 0 1 1))) .

(electric-energy-in-box box)

          Given a meep::volume* , returns the integral of the electric-�eld energy E∗ ⋅ D/2 in the given
volume. (If the volume has zero size along a dimension, a lower-dimensional integral is used.)

(magnetic-energy-in-box box)

          Given a meep::volume* , returns the integral of the magnetic-�eld energy H∗ ⋅ B/2in the given
volume. (If the volume has zero size along a dimension, a lower-dimensional integral is used.)

(field-energy-in-box box)

          Given a meep::volume* , returns the integral of the electric+magnetic-�eld energy

E∗ ⋅ D/2 + H∗ ⋅ B/2in the given volume. (If the volume has zero size along a dimension, a lower-
dimensional integral is used.)

Note that if you are at a �xed frequency and you use complex �elds (Bloch-periodic boundary
conditions or fields-complex?=true ), then one half of the �ux or energy integrals above corresponds
to the time-average of the �ux or energy for a simulation with real �elds.

Often, you want the integration box to be the entire computational cell. A useful function to return
this box, which you can then use for the box arguments above, is (meep-fields-total-volume
fields) , where fields is the global variable (above) holding the current meep::fields object.

One powerful feature is that you can supply an arbitrary function f(x, c1 , c2 , …) of position x and
various �eld components c1 , … and ask Meep to integrate it over a given volume, �nd its maximum,
or output it (via output-field-function , described later). This is done via the functions:

(integrate-field-function cs func [where] [fields-var])

          Returns the integral of the complex-valued function func over the meep::geometric_volume

speci�ed by where (defaults to entire computational cell) for the meep::fields speci�ed by
fields-var (defaults to fields ). func is a function of position (a vector3 , its �rst argument) and
zero or more �eld components speci�ed by cs : a list of component constants. func can be real- or
complex-valued.

If any dimension of where is zero, that dimension is not integrated over. In this way you can specify
one-, two-, or three-dimensional integrals.

(max-abs-field-function cs func [where] [fields-var])

          As integrate-field-function , but returns the maximum absolute value of func in the volume
where instead of its integral.

The integration is performed by summing over the grid points with a simple trapezoidal rule, and the
maximum is similarly over the grid points. See also Field Function Examples for illustrations of how
to call integrate-field-function and max-abs-field-function . See also Synchronizing the Magnetic
and Electric Fields if you want to do computations combining the electric and magnetic �elds.

Occasionally, one wants to compute an integral that combines �elds from two separate simulations
(e.g. for nonlinear coupled-mode calculations). This functionality is supported in Meep, as long as the
two simulations have the same computational cell, the same resolution, the same boundary
conditions and symmetries (if any), and the same PML layers (if any).

(integrate2-field-function fields2 cs1 cs2 func [where] [fields-var])

         Similar to integrate-field-function , but takes additional parameters fields2 and cs2 .

fields2 is a meep::fields* object similar to the global fields variable (see below) specifying the
�elds from another simulation. cs1 is a list of components to integrate with from fields-var

(defaults to fields ), as for integrate-field-function , while cs2 is a list of components to integrate

from fields2 . Similar to integrate-field-function , func is a function that returns an number
given arguments consisting of: the position vector, followed by the values of the components
speci�ed by cs1 (in order), followed by the values of the components speci�ed by cs2 (in order).

To get two �elds in memory at once for integrate2-field-function , the easiest way is to run one
simulation within a given .ctl �le, then save the results in another �elds variable, then run a second
simulation. This would look something like:

...set up and run first simulation...

(define fields2 fields) ; save the fields in a variable
(set! fields '()) ; prevent the fields from getting deallocated by reset-meep
(reset-meep)
...set up and run second simulation...

It is also possible to timestep both �elds simultaneously (e.g. doing one timestep of one simulation
then one timestep of another simulation, and so on, but this requires you to call much lower-level
functions like (meep-fields-step fields) .

Reloading Parameters

Once the �elds/simulation have been initialized, you can change the values of various parameters by
using the following functions:

(reset-meep)

           Reset all of Meep's parameters, deleting the �elds, structures, etcetera, from memory as if you
had not run any computations.

(restart-fields)

           Restart the �elds at time zero, with zero �elds. (Does not reset the Fourier transforms of the
�ux planes, which continue to be accumulated.)

(change-k-point! k)

           Change the k-point (the Bloch periodicity).

(change-sources! new-sources)

           Change the sources input variable to new-sources , and changes the sources used for the
current simulation.

Flux Spectra

Given a bunch of flux-region objects (see above), you can tell Meep to accumulate the Fourier
transforms of the �elds in those regions in order to compute �ux spectra. See also the Introduction
and Tutorial/Basics. The most important function is:

(add-flux fcen df nfreq flux-regions...)

           Add a bunch of flux-region s to the current simulation (initializing the �elds if they have not
yet been initialized), telling Meep to accumulate the appropriate �eld Fourier transforms for nfreq

equally spaced frequencies covering the frequency range fcen-df/2 to fcen+df/2 . Return a �ux
object, which you can pass to the functions below to get the �ux spectrum, etcetera.

As described in the tutorial, you normally use add-flux via statements like:

(define transmission (add-flux ...))

           to store the �ux object in a variable. add-flux initializes the �elds if necessary, just like calling
run , so you should only call it after setting up your geometry , sources , pml-layers , etcetera. You
can create as many �ux objects as you want, e.g. to look at powers �owing in different regions or in
different frequency ranges. Note, however, that Meep has to store (and update at every time step) a
number of Fourier components equal to the number of grid points intersecting the �ux region
multiplied by the number of electric and magnetic �eld components required to get the Poynting
vector multiplied by nfreq , so this can get quite expensive (in both memory and time) if you want a
lot of frequency points over large regions of space.
Once you have called add-flux , the Fourier transforms of the �elds are accumulated automatically
during time-stepping by the run functions. At any time, you can ask for Meep to print out the
current �ux spectrum via:

(display-fluxes fluxes...)

           Given a number of �ux objects, this displays a comma-separated table of frequencies and �ux
spectra, pre�xed by "�ux1:" or similar (where the number is incremented after each run). All of the
�uxes should be for the same fcen / df / nfreq . The �rst column are the frequencies, and
subsequent columns are the �ux spectra.

You might have to do something lower-level if you have multiple �ux regions corresponding to
different frequency ranges, or have other special needs. (display-fluxes f1 f2 f3) is actually
equivalent to (display-csv "flux" (get-flux-freqs f1) (get-fluxes f1) (get-fluxes f2)

(get-fluxes f3) , where display-csv takes a bunch of lists of numbers and prints them as a
comma-separated table, and we are calling two lower-level functions:

(get-flux-freqs flux)

           Given a �ux object, returns a list of the frequencies that it is computing the spectrum for.

(get-fluxes flux)

           Given a �ux object, returns a list of the current �ux spectrum that it has accumulated.

As described in Tutorial/Basics, for a re�ection spectrum you often want to save the Fourier-
transformed �elds from a "normalization" run and then load them into another run to be subtracted.
This can be done via:

(save-flux filename flux)

           Save the Fourier-transformed �elds corresponding to the given �ux object in an HDF5 �le of
the given name (without the ".h5" suf�x) (the current �lename-pre�x is prepended automatically).

(load-flux filename flux)

           Load the Fourier-transformed �elds into the given �ux object (replacing any values currently
there) from an HDF5 �le of the given name (without the ".h5" suf�x) (the current �lename-pre�x is
prepended automatically). You must load from a �le that was saved by save-flux in a simulation of
the same dimensions (for both the computational cell and the �ux regions) with the same number of
processors.

(load-minus-flux filename flux)

           As load-flux , but negates the Fourier-transformed �elds after they are loaded. This means
that they will be subtracted from any future �eld Fourier transforms that are accumulated.

(scale-flux-fields s flux)

           Scale the Fourier-transformed �elds in flux by the complex number s . e.g. load-minus-flux

is equivalent to load-flux followed by scale-flux-fields with s=-1 .

Force Spectra
Very similar to �ux spectra, you can also compute force spectra: forces on an object as a function of
frequency, computed by Fourier transforming the �elds and integrating the vacuum Maxwell stress
tensor

1
σij = Ei∗ Ej + Hi∗ Hj − δij (|E|2 + |H|2 )
2

over a surface S via F = ∫S σdA. We recommend that you normally only evaluate the stress
tensor over a surface lying in vacuum, as the interpretation and de�nition of the stress tensor in
arbitrary media is often problematic (the subject of extensive and controversial literature). It is �ne
if the surface encloses an object made of arbitrary materials, as long as the surface itself is in
vacuum.

See also Tutorial/Optical Forces.

Most commonly, you will want to normalize the force spectrum in some way, just as for �ux spectra.
Most simply, you could divide two different force spectra to compute the ratio of forces on two
objects. Often, you will divide a force spectrum by a �ux spectrum, to divide the force F by the
incident power P on an object, in order to compute the useful dimensionless ratio Fc/P where c=1 in
Meep units. For example, it is a simple exercise to show that the force F on a perfectly re�ecting
mirror with normal-incident power P satis�es Fc/P=2, and for a perfectly absorbing (black) surface
Fc/P=1.

The usage is similar to the �ux spectra: you de�ne a set of force-region objects telling Meep where
it should compute the Fourier-transformed �elds and stress tensors, and call add-force to add
these regions to the current simulation over a speci�ed frequency bandwidth, and then use
display-forces to display the force spectra at the end. There are also save-force , load-force , and

load-minus-force functions that you can use to subtract the �elds from two simulation, e.g. in order
to compute just the force from scattered �elds, similar to the �ux spectra. These types and functions
are de�ned as follows:

force-region

A region (volume, plane, line, or point) in which to compute the integral of the stress tensor of the
Fourier-transformed �elds. Its properties are:

center [ vector3 ]

           The center of the force region (no default).

size [ vector3 ]

           The size of the force region along each of the coordinate axes; default is (0,0,0) (a single point).

direction [ direction constant ]

           The direction of the force that you wish to compute (e.g. X , Y , etcetera). Unlike flux-region ,
you must specify this explicitly, because there is not generally any relationship between the
direction of the force and the orientation of the force region.
weight [ cnumber ]

           A weight factor to multiply the force by when it is computed; default is 1.0 .

In most circumstances, you should de�ne a set of force-region s whose union is a closed surface
lying in vacuum and enclosing the object that is experiencing the force.

(add-force fcen df nfreq force-regions...)

           Add a bunch of force-region s to the current simulation (initializing the �elds if they have not
yet been initialized), telling Meep to accumulate the appropriate �eld Fourier transforms for nfreq

equally spaced frequencies covering the frequency range fcen-df/2 to fcen+df/2 . Return a force
object, which you can pass to the functions below to get the force spectrum, etcetera.

As for �ux regions, you normally use add-force via statements like:

(define Fx (add-force ...))

to store the �ux object in a variable. add-force initializes the �elds if necessary, just like calling run ,
so you should only call it after setting up your geometry , sources , pml-layers , etcetera. You can
create as many force objects as you want, e.g. to look at forces on different objects, in different
directions, or in different frequency ranges. Note, however, that Meep has to store (and update at
every time step) a number of Fourier components equal to the number of grid points intersecting the
force region, multiplied by the number of electric and magnetic �eld components required to get the
stress vector, multiplied by nfreq , so this can get quite expensive (in both memory and time) if you
want a lot of frequency points over large regions of space.

Once you have called add-force , the Fourier transforms of the �elds are accumulated automatically
during time-stepping by the run functions. At any time, you can ask for Meep to print out the
current force spectrum via:

(display-forces forces...)

           Given a number of force objects, this displays a comma-separated table of frequencies and
force spectra, pre�xed by "force1:" or similar (where the number is incremented after each run). All
of the forces should be for the same fcen / df / nfreq . The �rst column are the frequencies, and
subsequent columns are the force spectra.

You might have to do something lower-level if you have multiple force regions corresponding to
different frequency ranges, or have other special needs. (display-forces f1 f2 f3) is actually
equivalent to (display-csv "force" (get-force-freqs f1) (get-forces f1) (get-forces f2)

(get-forces f3) , where display-csv takes a bunch of lists of numbers and prints them as a
comma-separated table, and we are calling two lower-level functions:

(get-force-freqs flux)

           Given a force object, returns a list of the frequencies that it is computing the spectrum for.

(get-forces flux)
           Given a force object, returns a list of the current force spectrum that it has accumulated.

As described in Tutorial/Basics, to compute the force from scattered �elds often want to save the
Fourier-transformed �elds from a "normalization" run and then load them into another run to be
subtracted. This can be done via:

(save-force filename force)

           Save the Fourier-transformed �elds corresponding to the given force object in an HDF5 �le of
the given name (without the ".h5" suf�x) (the current �lename-pre�x is prepended automatically).

(load-force filename force)

           Load the Fourier-transformed �elds into the given force object (replacing any values currently
there) from an HDF5 �le of the given name (without the ".h5" suf�x) (the current �lename-pre�x is
prepended automatically). You must load from a �le that was saved by save-force in a simulation of
the same dimensions (for both the computational cell and the force regions) with the same number
of processors.

(load-minus-force filename force)

           As load-force , but negates the Fourier-transformed �elds after they are loaded. This means
that they will be subtracted from any future �eld Fourier transforms that are accumulated.

LDOS spectra

Meep can also calculate the LDOS (local density of states) spectrum, as described in Tutorial/Local
Density of States. To do this, you simply pass the following step function to your run command:

(dft-ldos fcen df nfreq)

           Compute the power spectrum of the sources (usually a single point dipole source), normalized
to correspond to the LDOS, in a frequency bandwith df centered at fcen , at nfreq frequency
points.

The resulting spectrum is outputted as comma-delimited text, pre�xed by ldos:, , and is also stored
in the dft-ldos-data global variable after the run is complete.

Analytically, the per-polarization LDOS is exactly proportional to the power radiated by an

ℓ -oriented point-dipole current, p(t), at a given position in space. For a more mathematical
treatment of the theory behind the LDOS, we refer you to the relevant discussion in chapter 4 of
this book, but for now we simply give the de�nition:

2 Re[E^ℓ (x⃗ 0 , ω)p^(ω)∗ ]

⃗    
⃗
LDOSℓ (x0 , ω) = − ε(x0 )
π |p^(ω)|2

2
where the |p^(ω)| normalization is necessary for obtaining the power exerted by a unit-amplitude
dipole (assuming linear materials), and hats denote Fourier transforms. It is this quantity that is
computed by the dft-ldos command for a single dipole source. For a volumetric source, the
numerator and denominator are both integrated over the current volume, but "LDOS" computation
is less meaningful in this case.

Near-to-Far-Field Spectra

Meep can compute a "near-to-far-�eld transformation" in the frequency domain as described in

Tutorial/Near-to-Far Field Spectra: given the �elds on a "near" bounding surface inside the
computational cell, it can compute the �elds arbitrarily far away using an analytical transformation,
assuming that the "near" surface and the "far" region lie in a single homogeneous non-periodic 2d or
3d region. That is, in a simulation surrounded by PML that absorbs outgoing waves, the near-to-far-
�eld feature can compute the �elds outside the computational cell as if the outgoing waves had not
been absorbed (i.e. in the �ctitious in�nite open volume). Moreover, this operation is performed on
the Fourier-transformed �elds: like the �ux and force spectra above, you specify a set of desired
frequencies, Meep accumulates the Fourier transforms, and then Meep computes the �elds at each
frequency for the desired far-�eld points.

This is based on the principle of equivalence — given the Fourier-transformed tangential �elds on
the "near" surface, Meep computes equivalent currents and convolves them with the analytical
Green's functions in order to compute the �elds at any desired point in the "far" region.

There are three steps to using the near-to-far-�eld feature: �rst, de�ne the "near" surface(s) as a set
of surfaces capturing all outgoing radiation in the desired direction(s); second, run the simulation,
typically with a pulsed source, to allow Meep to accumulate the Fourier transforms on the near
surface(s); third, tell Meep to compute the far �elds at any desired points (optionally saving the far
�elds from a grid of points to an HDF5 �le). To de�ne the near surfaces, use:

(add-near2far fcen df nfreq near2far-regions...)

           Add a bunch of near2far-region s to the current simulation (initializing the �elds if they have
not yet been initialized), telling Meep to accumulate the appropriate �eld Fourier transforms for
nfreq equally spaced frequencies covering the frequency range fcen-df/2 to fcen+df/2 . Return a

near2far object, which you can pass to the functions below to get the far �elds.

Each near2far-region is identical to flux-region except for the name: in 3d, these give a set of
planes (important: all these "near surfaces" must lie in a single homogeneous material with isotropic
ε and μ — and they should not lie in the PML regions) surrounding the source(s) of outgoing
radiation that you want to capture and convert to a far �eld. Ideally, these should form a closed
surface, but in practice it is suf�cient for the near2far-region s to capture all of the radiation in the
direction of the far-�eld points. Important: as for �ux computations, each near2far-region should
be assigned a weight of ±1 indicating the direction of the outward normal relative to the
+coordinate direction. So, for example, if you have six regions de�ning the six faces of a cube, i.e. the
faces in the +x, -x, +y, -y, +z, and -z directions, then they should have weights +1, -1, +1, -1, +1, and -1
respectively. Note that, neglecting discretization errors, all near-�eld surfaces that enclose the same
outgoing �elds are equivalent and will yield the same far �elds (with a discretization-induced
difference that vanishes with increasing resolution etc.).

After the simulation run is complete, you can compute the far �elds. This is usually for a pulsed
source .so that the �elds have decayed away and the Fourier transforms have �nished accumulating.
 (get-farfield near2far x)

           Given a vector3 point x (which can lie anywhere outside the near-�eld surface, including
outside the computational cell) and a near2far object, returns the computed (Fourier-transformed)
"far" �elds at x as list of length 6 nfreq , consisting of �elds
(Ex1,Ey1,Ez1,Hx1,Hy1,Hz1,Ex2,Ey2,Ez2,Hx2,Hy2,Hz2,...) for the frequencies 1,2,…, nfreq .

(output-farfields near2far fname where resolution)

           Given an HDF5 �le name fname (does not include the .h5 suf�x), a volume given by where

(may be 0d, 1d, 2d, or 3d), and a resolution (in grids points / distance a), outputs the far �elds in
where (which may lie outside the computational cell) in a grid with the given resolution (which may
differ from the FDTD grid resolution) to the HDF5 �le as a set of twelve array datasets ex.r , ex.i ,
..., hz.r , hz.i , giving the real and imaginary parts of the Fourier-transformed E and H �elds on
this grid. Each dataset is an nx×ny×nz×nfreq 4-dimensional array of space×frequency (although
dimensions that =1 are omitted).

Note that far �elds have the same units and scaling as the Fourier transforms of the �elds, and hence
cannot be directly compared to time-domain �elds. In practice, it is easiest to use the far �elds in
computations where overall scaling (units) cancel out or are irrelevant, e.g. to compute the fraction
of the far �elds in one region vs. another region.

For a scattered-�eld computation, you often want to separate the scattered and incident �elds. Just
as is described in Tutorial/Basics for �ux computations, you can do this by saving the Fourier-
transformed incident from a "normalization" run and then load them into another run to be
subtracted. This can be done via:

(save-near2far filename near2far)

           Save the Fourier-transformed �elds corresponding to the given near2far object in an HDF5
�le of the given name (without the ".h5" suf�x). The current �lename-pre�x is prepended
automatically.

(load-near2far filename near2far)

           Load the Fourier-transformed �elds into the given near2far object (replacing any values
currently there) from an HDF5 �le of the given name (without the ".h5" suf�x) (the current �lename-
pre�x is prepended automatically). You must load from a �le that was saved by save-near2far in a
simulation of the same dimensions (for both the computational cell and the near2far regions) with
the same number of processors.

(load-minus-near2far filename near2far)

           As load-near2far , but negates the Fourier-transformed �elds after they are loaded. This
means that they will be subtracted from any future �eld Fourier transforms that are accumulated.

(scale-near2far-fields s near2far)

           Scale the Fourier-transformed �elds in near2far by the complex number s . e.g.
load-minus-near2far is equivalent to load-near2far followed by scale-near2far-fields with s=-1 .
Frequency-Domain Solver

Meep contains a frequency-domain solver that directly computes the �elds produced in a geometry
in response to a constant-frequency source, using an iterative linear solver instead of timestepping.
Preliminary tests have shown that in many instances, this solver converges much faster than simply
running an equivalent time domain simulation with a continuous wave source, timestepping until all
transient effects from the source turn-on have disappeared, especially if the �elds are desired to a
very high accuracy. To use it, simply de�ne a continuous-src with the desired frequency, initialize
the �elds and geometry via (init-fields) , and then:

(meep-fields-solve-cw fields tol maxiters L)

After the fields variable (a global variable pointing to the meep::fields* object initialized by
init-fields , see above), the next two parameters to the frequency-domaine solver are the
tolerance tol for the iterative solver (10−8, by default) and a maximum number of iterations
maxiters (104, by default). Finally, there is a parameter L that determines a tradeoff between
memory and work per step and convergence rate of the iterative algorithm biCGSTAB-(L) that is
used; larger values of L of will often lead to faster convergence at the expense of more memory and
more work per iteration. The default is L =2, and normally a value ≥ 2 should be used.

The frequency-domain solver supports arbitrary geometries, PML, boundary conditions,

symmetries, parallelism, conductors, and arbitrary nondispersive materials. Lorentz–Drude
dispersive materials are not currently supported in the frequency-domain solver, but since you are
solving at a known �xed frequency rather than timestepping, you should be able to pick
conductivities etcetera in order to obtain any desired complex ε and μ at that frequency.

The frequency-domain solver requires you to use complex-valued �elds, via

(set! force-complex-fields? true) .

After meep-fields-solve-cw completes, it should be as if you had just run the simulation for an
in�nite time with the source at that frequency. You can call the various �eld-output functions and so
on as usual at this point.

Run and Step Functions

The actual work in Meep is performed by run functions, which time-step the simulation for a given
amount of time or until a given condition is satis�ed.

The run functions, in turn, can be modi�ed by use of step functions: these are called at every time
step and can perform any arbitrary computation on the �elds, do outputs and I/O, or even modify
the simulation. The step functions can be transformed by many modi�er functions, like at-beginning,
during-sources, etcetera which cause them to only be called at certain times, etcetera, instead of at
every time step.

A common point of confusion is described in The Run Function Is Not A Loop. Please read this article
if you want to make Meep do some customized action on each time step, as many users make the
same mistake. What you really want to in that case is to write a step function, as described below.

Run Functions

The following run functions are available. You can also write your own, using the lower-level
C++/SWIG functions, but these should suf�ce for most needs.

(run-until cond?/time step-functions...)

           Run the simulation until a certain time or condition, calling the given step functions (if any) at
each timestep. The �rst argument is either a number, in which case it is an additional time (in Meep
units) to run for, or it is a function (of no arguments) which returns true when the simulation should
stop.

(run-sources step-functions...)

           Run the simulation until all sources have turned off, calling the given step functions (if any) at
each timestep. Note that this does not mean that the �elds will be zero at the end: in general, some
�elds will still be bouncing around that were excited by the sources.

(run-sources+ cond?/time step-functions...)

           As run-sources , but with an additional �rst argument: either a number, in which case it is an
additional time (in Meep units) to run for after the sources are off, or it is a function (of no
arguments). In the latter case, the simulation runs until the sources are off and (cond?) returns
true .

In particular, a useful �rst argument to run-sources+ or run-until is often given by as in

Tutorial/Basics:

(stop-when-fields-decayed dT c pt decay-by)

           Return a cond? function, suitable for passing to run-until / run-sources+ , that examines the
component c (e.g. Ex , etc.) at the point pt (a vector3 ) and keeps running until its absolute value
squared has decayed by at least decay-by from its maximum previous value. In particular, it keeps
incrementing the run time by dT (in Meep units) and checks the maximum value over that time
period—in this way, it won't be fooled just because the �eld happens to go through 0 at some instant.

Note that, if you make decay-by very small, you may need to increase the cutoff property of your
source(s), to decrease the amplitude of the small high-frequency components that are excited when
the source turns off. High frequencies near the Nyquist frequency of the grid have slow group
velocities and are absorbed poorly by PML.

Finally, another two run functions, useful for computing ω (k) band diagrams, are

(run-k-point T k)

           Given a vector3 k , runs a simulation for each k point (i.e. specifying Bloch-periodic boundary
conditions) and extracts the eigen-frequencies, and returns a list of the (complex) frequencies. In
particular, you should have speci�ed one or more Gaussian sources. It will run the simulation until
the sources are turned off plus an additional T time units. It will run harminv (see below) at the
same point/component as the �rst Gaussian source and look for modes in the union of the frequency
ranges for all sources.

(run-k-points T k-points)

           Given a list k-points of k vectors, runs run-k-point for each one, and returns a list of lists of
frequencies (one list of frequencies for each k). Also prints out a comma-delimited list of
frequencies, pre�xed by freqs: , and their imaginary parts, pre�xed by freqs-im: . See
Tutorial/Resonant Modes and Transmission in a Waveguide Cavity.

Prede�ned Step Functions

Several useful step functions are prede�ned for you by Meep.

Output Functions

The most common step function is an output function, which outputs some �eld component to an
HDF5 �le. Normally, you will want to modify this by one of the at- functions, below, as outputting a
�eld at every time step can get quite time- and storage-consuming.

Note that although the various �eld components are stored at different places in the Yee lattice,
when they are outputted they are all linearly interpolated to the same grid: to the points at the
centers of the Yee cells, i.e. (i + 0.5, j + 0.5, k + 0.5) ⋅ Δin 3d.

The prede�ned output functions are:

output-epsilon

           Output the dielectric function (relative permittivity) ε . Note that this only outputs the
frequency-independent part of ε (the ω → ∞ limit).

output-mu

           Output the relative permeability function μ. Note that this only outputs the frequency-
independent part of μ (the ω → ∞ limit).

output-hpwr

           Output the magnetic-�eld energy density H∗ ⋅ B/2

output-dpwr

           Output the electric-�eld energy density E∗ ⋅ D/2

output-tot-pwr

           Output the total electric and magnetic energy density. Note that you might want to wrap this
step function in synchronized-magnetic to compute it more accurately. See Synchronizing the
Magnetic and Electric Fields.

output-Xfield-x, output-Xfield-y, output-Xfield-z, output-Xfield-r, output-Xfield-p

           Output the x , y, z , r, or ϕ component respectively, of the �eld X, where X is either h , b , e , d ,

or s for the magnetic, electric, displacement, or Poynting �eld, respectively. If the �eld is complex,
outputs two datasets, e.g. ex.r and ex.i , within the same HDF5 �le for the real and imaginary
parts, respectively. Note that for outputting the Poynting �eld, you might want to wrap the step
function in synchronized-magnetic to compute it more accurately; see Synchronizing the magnetic
and electric �elds.

output-Xfield

           Outputs all the components of the �eld X, where X is either h , b , e , d , or s as above, to an
HDF5 �le. (That is, the different components are stored as different datasets within the same �le.)

(output-png component h5topng-options)

           Output the given �eld component (e.g. Ex , etc.) as a PNG image, by �rst outputting the HDF5
�le, then converting to PNG via h5topng, then deleting the HDF5 �le. The second argument is a
string giving options to pass to h5topng (e.g. "-Zc bluered" ). See also Tutorial/Basics.

It is often useful to use the h5topng -C or -A options to overlay the dielectric function when
outputting �elds. To do this, you need to know the name of the dielectric-function .h5 �le (which
must have been previously output by output-epsilon). To make this easier, a built-in shell variable
$EPS is provided which refers to the last-output dielectric-function .h5 �le. So, for example

(output-png Ez "-C $EPS") will output the Ez �eld and overlay the dielectric contours.

(output-png+h5 component h5topng-options)

           Like output-png , but also outputs the .h5 �le for the component. (In contrast, output-png

deletes the .h5 when it is done.)

More generally, it is possible to output an arbitrary function of position and zero or more �eld
components, similar to the integrate-field-function described above. This is done by:

(output-field-function name cs func)

           Output the �eld function func to an HDF5 �le in the datasets named name .r and name .i

(for the real and imaginary parts). Similar to integrate-field-function , func is a function of
position (a vector3 ) and the �eld components corresponding to cs : a list of component constants.

(output-real-field-function name cs func)

           As output-field-function , but only outputs the real part of func to the dataset given by the
string name .

See also Field Function Examples. See also Synchronizing the Magnetic and Electric Fields if you
want to do computations combining the electric and magnetic �elds.

Harminv

The following step function collects �eld data from a given point and runs Harminv on that data to
extract the frequencies, decay rates, and other information.
(harminv c pt fcen df [maxbands])

           Returns a step function that collects data from the �eld component c (e.g. Ex , etc.) at the
given point pt (a vector3 ). Then, at the end of the run, it uses Harminv to look for modes in the
given frequency range (center fcen and width df ), printing the results to standard output (pre�xed
by harminv: ) as comma-delimited text, and also storing them to the variable harminv-results . The
optional argument maxbands is the maximum number of modes to search for; defaults to 100 .

Important: normally, you should only use harminv to analyze data after the sources are off.
Wrapping it in (after-sources (harminv ...)) is suf�cient.

In particular, Harminv takes the time series f(t) corresponding to the given �eld component as a
function of time and decomposes it (within the speci�ed bandwidth) as:

f(t) = ∑ an e−iωn t
n

The results are stored in the list harminv-results , which is a list of tuples holding the frequency,
amplitude, and error of the modes. Given one of these tuples, you can extract its various
components with one of the accessor functions:

(harminv-freq result)

           Return the complex frequency ω (in the usual Meep 2πc units).

(harminv-freq-re result)

           Return the real part of the frequency ω .

(harminv-freq-im result)

           Return the imaginary part of the frequency ω .

(harminv-Q result)

           Return dimensionless lifetime, or "quality factor", Q , de�ned as −Re ω/2Im ω.

(harminv-amp result)

           Return the complex amplitude a .

(harminv-err result)

           A crude measure of the error in the frequency (both real and imaginary)...if the error is much
larger than the imaginary part, for example, then you can't trust the Q to be accurate. Note: this
error is only the uncertainty in the signal processing, and tells you nothing about the errors from
�nite resolution, �nite cell size, and so on!

For example, (map harminv-freq-re harminv-results) gives you a list of the real parts of the
frequencies, using the Scheme built-in map .

Step-Function Modi�ers
Rather than writing a brand-new step function every time we want to do something a bit different,
the following "modi�er" functions take a bunch of step functions and produce new step functions
with modi�ed behavior. See also Tutorial/Basics for examples.

Miscellaneous Step-Function Modi�ers

(combine-step-funcs step-functions...)

           Given zero or more step functions, return a new step function that (on each step) calls all of the
passed step functions.

(synchronized-magnetic step-functions...)

           Given zero or more step functions, return a new step function that (on each step) calls all of the
passed step functions with the magnetic �eld synchronized in time with the electric �eld. See
Synchronizing the Magnetic and Electric Fields.

Controlling When a Step Function Executes

(when-true cond? step-functions...)

           Given zero or more step functions and a condition function cond? (a function of no arguments),
evaluate the step functions whenever (cond?) returns true .

(when-false cond? step-functions...)

           Given zero or more step functions and a condition function cond? (a function of no arguments),
evaluate the step functions whenever (cond?) returns false .

(at-every dT step-functions...)

           Given zero or more step functions, evaluates them at every time interval of dT units (rounded
up to the next time step).

(after-time T step-functions...)

           Given zero or more step functions, evaluates them only for times after a T time units have
elapsed from the start of the run.

(before-time T step-functions...)

           Given zero or more step functions, evaluates them only for times before a T time units have
elapsed from the start of the run.

(at-time T step-functions...)

           Given zero or more step functions, evaluates them only once, after a T time units have elapsed
from the start of the run.

(after-sources step-functions...)

           Given zero or more step functions, evaluates them only for times after all of the sources have
turned off.

(after-sources+ T step-functions...)
           Given zero or more step functions, evaluates them only for times after all of the sources have
turned off, plus an additional T time units have elapsed.

(during-sources step-functions...)

           Given zero or more step functions, evaluates them only for times before all of the sources have
turned off.

(at-beginning step-functions...)

           Given zero or more step functions, evaluates them only once, at the beginning of the run.

(at-end step-functions...)

           Given zero or more step functions, evaluates them only once, at the end of the run.

Modifying HDF5 Output

(in-volume v step-functions...)

           Given zero or more step functions, modi�es any output functions among them to only output a
subset (or a superset) of the computational cell, corresponding to the meep::geometric_volume* v
(created by the volume function).

(in-point pt step-functions...)

           Given zero or more step functions, modi�es any output functions among them to only output a
single point of data, at pt (a vector3 ).

(to-appended filename step-functions...)

           Given zero or more step functions, modi�es any output functions among them to append their
data to datasets in a single newly-created �le named filename (plus an .h5 suf�x and the current
�lename pre�x). They append by adding an extra dimension to their datasets, corresponding to time.

(with-prefix prefix step-functions...)

           Given zero or more step functions, modi�es any output functions among them to prepend the
string prefix to the �le names (much like filename-prefix , above).

Writing Your Own Step Functions

A step function can take two forms. The simplest is just a function of no arguments, which is called at
every time step (unless modi�ed by one of the modi�er functions above). e.g.

(define (my-step) (print "Hello world!\n"))

If one then does (run-until 100 my-step) , Meep will run for 100 time units and print "Hello world!"
at every time step.

This suf�ces for most purposes. However, sometimes you need a step function that opens a �le, or
accumulates some computation, and you need to clean up (e.g. close the �le or print the results) at
the end of the run. For this case, you can write a step function of one argument: that argument will
either be 'step when it is called during time-stepping, or 'finish when it is called at the end of the
run.

Low-Level Functions
By default, Meep reads input functions like sources and geometry and creates global variables
structure and fields to store the corresponding C++ objects. Given these, you can then call
essentially any function in the C++ interface, because all of the C++ functions are automatically
made accessible to Scheme by a wrapper-generator program called SWIG.

Initializing the Structure and Fields

The structure and fields variables are automatically initialized when any of the run functions is
called, or by various other functions such as add-flux . To initialize them separately, you can call
(init-fields) manually, or (init-structure k-point) to just initialize the structure.

If you want to time step more than one �eld simultaneously, the easiest way is probably to do
something like:

(init-fields)
(define my-fields fields)
(set! fields '())
(reset-meep)

and then change the geometry etc. and re-run (init-fields) . Then you'll have two �eld objects in
memory.

SWIG Wrappers

If you look at a function in the C++ interface, then there are a few simple rules to infer the name of
the corresponding Scheme function.

First, all Meep functions (in the meep:: namespace) are pre�xed with meep- in the Scheme
interface.
Second, any method of a class is pre�xed with the name of the class and a hyphen. For example,
meep::fields::step , which is the function that performs a time-step, is exposed to Scheme as

meep-fields-step . Moreover, you pass the object as the �rst argument in the Scheme wrapper.
e.g. f.step() becomes (meep-fields-step f) .
To call the C++ constructor for a type, you use new- type . e.g. (new-meep-fields

...arguments...) returns a new meep::fields object. Conversely, to call the destructor and
deallocate an object, you use delete- type ; most of the time, this is not necessary because
objects are automatically garbage-collected.

Some argument type conversion is performed automatically, e.g. types like complex numbers are
converted to complex<double> , etcetera. vector3 vectors are converted to meep::vec , but to do this
we need to know the dimensionality of the problem in C++. The problem dimensions are
automatically initialized by init-structure , but if you want to pass vector arguments to C++ before
that time you should call (require-dimensions!) , which infers the dimensions from the
geometry-lattice , k-point , and dimensions variables.