PmlRegion

PmlRegion

Used 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.

PmlRegion Parameters

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.

MPML

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).

Example PMLslab Block

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>

Example PMLslab Block

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

Example PML slab Block

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>

Example Block Describing a Conductivity Function for Each Direction

# 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)

Example Block for Specifying When There is a Bottom 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

Example sigmaForm Block Reuse Conductivity Profile for Different Directions

#  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.