# Meep Reference

(Difference between revisions)
 Revision as of 05:24, 7 November 2005 (edit)Stevenj (Talk | contribs) (→geometric-object)← Previous diff Revision as of 05:59, 7 November 2005 (edit)Stevenj (Talk | contribs) (→geometric-object)Next diff → Line 182: Line 182: (make block (center 1 2 3) (material mat) (size 1 1 1)) (make block (center 1 2 3) (material mat) (size 1 1 1)) (make sphere (center 1 2 3) (material air) (radius 0.2)))) (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 in Meep]]. + + ; symmetry + : A single symmetry to exploit. This is the base class of the specific 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 fields 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 fields and sources transform under.) + + The specific 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. $C_2$). Here, the direction is the axis of the rotation. + ; rotate2-sym + : A 90° (fourfold) rotational symmetry (a.k.a. $C_4$). 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 specification, which sets up one or more PML layers around the boundaries according to the following four 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 reflections 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 specifies PML on the $\pm 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 coefficient by. A strength of 2.0 will ''square'' the theoretical reflection coefficient of the PML (making it smaller), but will also increase numerical reflections.

## Revision as of 05:59, 7 November 2005

Here, we document the features exposed to the user by the Meep package. We do not document the Scheme language or the functions provided by libctl (see also the libctl User Reference section of the libctl manual).

This page is simply a compact listing of the functions exposed by the interface; for a gentler introduction, see the Meep tutorial. Also, we note that this page is not, and probably never will be, 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.

## 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 defined by libctl.)

geometry [list of geometric-object class]
Specifies 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]
Specifies the current sources to be present in the simulation; defaults to none.
symmetries [list of symmetry class]
Specifies 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 in Meep.
pml-layers [list of pml class]
Specifies the absorbing PML boundary layers to use; defaults to none.
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).
geometry-lattice [lattice class]
Specifies the the size of the unit cell (which is centered on the origin of the coordinate system). If any dimension of the lattice size is the special value no-size, then the dimension of the lattice is reduced (i.e. it becomes two- or one-dimensional) by default. Defaults to a cubic cell of unit size.
dimensions [integer]
Explicitly specifies 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 if possible when any of the geometry-lattice sizes are 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.
m [number]
For CYLINDRICAL simulations, specifies that the angular φ dependence of the fields is of the form eimφ (default is m=0). If the simulation cell includes the origin r = 0, then m must be an integer.
resolution [number or vector3]
Specifies the computational grid resolution, in pixels per distance unit. Defaults to 10.
ensure-periodicity [boolean]
k-point [false or vector3]
If false (the default), then the boundaries are perfect metallic (zero electric field). If a vector, then the boundaries are Bloch-periodic: the fields at one side are $\exp(i\mathbf{k}\cdot\mathbf{R})$ times the fields at the other side, separated by the lattice vector $\mathbf{R}$. The k-point vector is specified in Cartesian coordinates, in units of 2π/distance. (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 (the size of the computational cell).
force-complex-fields? [boolean]
By default, Meep runs its simulations with purely real fields whenever possible. It uses complex fields (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 fields. See also: Complex fields in Meep.
filename-prefix [string]
A string prepended to all output filenames. Defaults to the name of the current ctl file, with ".ctl" replaced by "-" (e.g. foo.ctl uses a "foo-" prefix).
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 Failed to parse (unknown error): 1/\sqrt{\textrm{# dimensions}}

, and in practice should be slightly smaller.

output-volume [meep::geometric_volume*]
Specifies 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.
progress-interval [number]
Time interval (seconds) after which Meep prints a progress message; default is 4 seconds.

The require a bit more understanding of the inner workings of Meep to use (see also the 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 fields 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/fields into (default 0); actual number is determined by number of processors, PML layers, etcetera. (Mainly useful for debugging.)

## Predefined Variables

Variables predefined for your convenience and amusement.

air, vacuum [material-type class]
Two aliases for a predefined material type with a dielectric constant of 1.
metal [material-type class]
A predefined material type corresponding to a perfectly conducting metal (in which the electric field is zero).
nothing [material-type class]
A material that, effectively, punches a hole through other objects to the background (default-material or epsilon-input-file).
infinity [number]
A big number (1.0e20) to use for "infinite" dimensions of objects.
pi [number]
π (3.14159...).

## 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 any place the superclass is expected. An object of a class is constructed with:

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


Meep defines 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 affine 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.

lattice
Properties:
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 Meep Introduction#Units in Meep.

### material-type

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.

dielectric
A uniform, isotropic, possibly nonlinear or dispersive, dielectric material; see also Dielectric materials in Meep. It has three properties:
epsilon [number]
The dielectric constant (must be positive). No default value. You can also use (index n) as a synonym for (epsilon (* n n)).
chi2[number]
The Kerr susceptibility \chi^{(2)}.
polarizations [list of polarizability class]
List of dispersive polarizabilities (see below) added to the dielectric constant, in order to model material dispersion; defaults to none.
perfect-metal
A perfectly conducting metal; this class has no properties and you normally just use the predefined metal object, above. (To model imperfect conductors, use a dispersive dielectric material.)
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; wild and crazy users could even return another material-function object (which would then have its function invoked in turn).

Dispersive dielectric materials, above, are specified via a list of objects of type polarizability, which is another class with four properties:

polarizability
Specifies a single dispersive polarizability of damped harmonic form (see Material dispersion), with the parameters:
omega [number]
The resonance frequency ωn.
gamma [number]
The resonance frequency γn.
sigma [number]
The scale factor σn.
energy-saturation [number]
See Saturable gain in Meep.

### 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 specified).
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 specified, 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 finite 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 [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 defines 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 defined:

; 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 in Meep.

symmetry
A single symmetry to exploit. This is the base class of the specific 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 fields 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 fields and sources transform under.)

The specific 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.
rotate2-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 specification, which sets up one or more PML layers around the boundaries according to the following four 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 reflections 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 specifies PML on the $\pm 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 coefficient by. A strength of 2.0 will square the theoretical reflection coefficient of the PML (making it smaller), but will also increase numerical reflections.