PmlRegionUsed to describe where (if any) PMLs exist in the simulation. For every
PmlRegion, the region will be divided into slabs; for each
slab two FieldMultiUpdaters will be created, a Faraday PML
updater, and an Ampere PML updater (each with three components). The
lowerBounds and upperBounds will be given to the
occurrences of FieldMultiUpdater, as well as the PML sigma
functions.
Vorpal first looks for an STFunc sigmaX (this is what the PML
updater wants in the end). If there isn’t one in the
PmlRegion input block, Vorpal looks for an STFunc
sigmaX1. If Vorpal doesn’t find an STFunc sigmaX1, it looks
for a sigmaFormX, from which it can create sigmaX1, using
sigmaFactorX if present. Otherwise, Vorpal looks for a
sigmaForm, from which it can create sigmaX1, using
sigmaFactorX at present. You can mix all three methods. The
resulting sigmaX1 is renamed sigmaX and put in the resulting PML
MultiUpdater.
As a rule of thumb, you should make the outer region the outer boundary of the PMLs, and the inner region the normal Maxwell update area; generally this will give the correct result. In typical simulations, the inner region may be specified to be the normal Yee update region, and the outer region to be the outer boundary of the PML. This rule applies also when the PML is only a single slab, or is only slabs on the right and left. Before setting itself up, the PML considers the inner region to be the intersection of the outer region with the input-file-specified inner region. Specifying the inner slab might seem a bit tricky in some cases. In Vorpal a PML slab can have a direction; and the simulation gets this direction from the relation between the inner and outer slabs. In the above, for instance, the slab from [105 10] to [110 210], on the right side of the simulation, attenuates waves only in the x direction; the PML algorithm can be computed more efficiently for it than for the upper-right corner [105 0] to [110 10]. Because of this, you must be careful while specifying the inner region when a PML does not surround it completely.
In the end, Vorpal will give an error if a PML updater does not have the sigmaWn STFuncs that it needs.
Note
instantiations of UniPmlUpdater are created for the
side slabs, and instantiations of PMLUpdater are
created for the corner regions.
The slabs specified in PmlRegion will be expanded and
contracted to and from the simulation boundary, depending on the
component and emType (Faraday or Ampere).
Note
PMLs fail to be reflectionless for some materials, including photonic crystals. It is recommended to use the Matched Absorbing Layer (MAL) instead. PMLs may also fail when combined with other active boundary conditions, including but not limited to; ports, particles at the boundary, or structures that are not normal to the boundary. See Perfectly Matched Layer in VsimReference.
faradayUpdaterName (string, required)Name of the Yee Faraday updater. (The PML Faraday updater will be put in the same update step.)
ampereUpdaterName (string, required)Name of the Yee Ampere updater.
eFieldName (string, required)Name of the Yee E field.
bFieldName (string, required)Name of the Yee B field.
eAuxFieldName (string, default = pmlEAuxField)Name of the PML auxiliary E field. The Field attribute will be created automatically if it needed.
bAuxFieldName (string, default = pmlBAuxField)Name of the PML auxiliary B field. The Field attribute will be created automatically if it needed.
rhoJFieldName (string)Name of the density-current field (current at components 1, 2, 3, density at 0).
rhoJmagFieldName (string)Name of the density-current field associated with “magnetic” current (untested).
useUniPml (optional, default = true)Indicates whether to use the more efficient uniaxial PML algorithm, for which only one sigmaW is non-zero, when possible.
sigmaForm (string)Function of w, meant to be a form for producing sigmaWn, the
conductivity profile. w is replaced by x, y, or z, depending on W given
by sigmaFactorW. It is multiplied by sigmaFactorW.
sigmaFormW (string)Function of w, meant to be a form for producing sigmaWn, the conductivity profile. w is replaced by x, y, or z, depending on W given by sigmaFactorW. A string that is multiplied by sigmaFactorW. (W is one of {X,Y,Z}).
sigmaFactorW (float vector, default = [1.0 1.0])(W is one of {X,Y,Z}). – components of sigmaFactor [sigmaFactorX1 sigmaFactorX2] are used to multiply the expressions of sigmaFormX or sigmaForm for the X1 and X2 slabs.
STFunc
Block can be used to specify the sigma function directly. The name of the block must correspond to sigmaW or sigmaWn where W is X,Y,Z and n is 0 or 1 (lower or upper). See below for examples.
Sigma may be specified through a combination of
sigmaForm, sigmaFormW and STFunc blocks.
Region (code blocks)PmlRegion requires the use of two Region blocks to give the inner and out bounds of the PML region. The inner region describes the region inside PML (usually the region describing the normal Maxwell update; can/may extend beyond the outer region). The outer region describes the region bounding PML (which will be slightly altered for each component).
Region block parameters include:
lowerBounds (integer vector, required)
Lower bounds of the region.
upperBounds (integer vector, required)
Upper bounds of the region.
energyWritePeriod (integer, default = 0)If non-zero, the energy absorbed by the PML every energyWritePeriod steps to the comms text file. If zero, the PML region does not keep track of absorbed energy.
The basic PML has an increasing conductivity, or imaginary part of the dielectric constant (uniaxial PML, see [Ged96]). While the PML is good at absorbing propagating waves, it is not very good at absorbing evanescent waves. The MPML (Modified PML, see [RGH02]) increases the real part of the dielectric constant along with the conductivity (imaginary part). This yields better absorption of evanescent waves; for example, it is a better absorber at the end of a waveguide.
For an MPML, choose kind=mpml in the <PmlRegion>. Then there
is an additional option to set:
relPermForm (string, required)Like relSigmaForm, but specifies the relative permeability
(real part of the dielectric constant), which typically should
increase from 1 at the MPML interface to some maximum
(perhaps 2 to 10) as a power law.
useSmallSigmaApproximation (boolean, default = false)Whether to use a time-advance algorithm that assumes \(\sigma \Delta t \ll 1\). An option for experts only.
addSigmaForm (string)Should be set to 0 (this is an experimental option).
This example demonstrates a two-dimensional block specifying a PML 5 cells thick on the left and right sides of the inner region, and 10 cells thick above and below the inner region. (The region will be divided into several slabs (rectangular regions) and updaters will be created for each region.)
<Region outer>
lowerBounds = [0 0]
upperbounds = [110 220]
</Region>
<Region inner>
lowerBounds = [5 10]
upperbounds = [105 210]
</Region>
This example demonstrates describing a slab on only the right hand side.
<Region outer>
lowerBounds = [105 0]
upperbounds = [110 220]
</Region>
<Region inner>
lowerBounds = [105 0]
upperbounds = [105 220]
</Region>
# inner slab is degenerate in the x direction,
# and on the left side of the outer slab,
# indicating that the wave will enter the PML from the left side
This is another example that demonstrates describing a slab on only the right hand side.
<Region outer>
lowerBounds = [105 0]
upperbounds = [110 220]
</Region>
<Region inner>
lowerBounds = [0 0]
upperbounds = [105 220]
</Region>
# Function is 0 zero at x-grid number 105,
# and increases as x increases.
# c is the speed of light and DX the cell-length
# in the x # direction.
<STFunc sigmaX2>
kind = expression
expression = 1.0 * c / DX * ( (x - 105*DX)/(5*DX) )\^{ }2
</STFunc>
# Conductivity for each slab is specified by
# an STFunc block
# Conductivity for each slab is specified by
# an STFunc block:
# sigmaX1 -x (left slab)
# sigmaX2 +x (the right slab)
# sigmaY1 -y (bottom slab)
# sigmaY2 +y (top slab)
# sigmaZ1 -z (back slab)
# sigmaZ2 +z (top slab)
<STFunc sigmaY1>
kind = expression
expression = 1.5 * c / DY * ( (210*DX - y)/(10*DX) )\^{ }2
</STFunc>
# You only need the above when there is a bottom slab.
# sigmaXn should depend only on x, and likewise for other
# directions.
# Not recommended - sigmaXn may be allowed to depend
# on x, y, z, and t
# specifying sigmaForm
sigmaForm = 1.5 * c/DX * w\^{ }2
sigmaFactorX = [ 2.0 0.5 ]
# from which Vorpal can make a sigmaWn by using:
<STFunc sigmaX1>
kind = expression
expression = 2.0 * (1.5 * c/ DX * ( (5*DX - x)/(5*DX) )\^{ }2 )
</STFunc>
<STFunc sigmaX2>
kind = expression
expression = 0.5 * (1.5 * c/ DX * ( (x - 105*DX)/(5*DX) )\^{ }2 )
</STFunc>
# Vorpal calculates the real coordinates of PML edge and PML
# thickness and replaces w with a linear function of x (or normal
# direction)that goes from 0 at the edge to 1 at the end
# then multiplies replacement value by factor paramVec
# sigmaFactorX.
#
#
# To have different functional forms in the X, Y, and Z
# directions specify a sigmaFormW where W is X, Y, or Z.
# Again, make sigmaFormX (e.g.) a function of the dummy
# variable w (w is recognized as the dummy variable if it is
# neither preceded followed by another letter, number, or
# underscore).
# Again, sigmaFactorX is used to allow different factors for
# sigmaX1 and sigmaX2.