- linIterUpdater
linIterUpdater¶
Works with VSimBase, VSimEM, VSimPD, VSimPA, and VSimVE licenses.
General translation-invariant linear Multifield updater. Depending on the specified parameter operation, linIterUpdater can perform the following updates for multiple fields: \({\bf E^1}, ..., {\bf E^N}\) simultaneously, where:
In each case, \(b_i\) is the user-chosen component of the field \({\bf E^i}\),
\(b'_j\) is the user-chosen component of the field \({\bf F^j}\),
\(m_j\), \(n_j\), and \(p_j\) correspond to the
cellOffset StencilElement
parameter (see StencilElement), and
\(\Delta x\), \(\Delta y\), and \(\Delta z\) are the dimensions of the cell.
linIterUpdater updates cell-by-cell, based on an internal
iterator approach (hence the name iter). linIterUpdater
evaluates the right-hand-side of the equation (as shown above) for a
cell, applies the updates to the left-hand-side of the equation for a
cell, and then proceeds to the next cell. This is important to remember
if a field is both a readFields
and a writeFields
.
The matrix \(\mathbb{A}\) is described in the input file in such a way as to be compatible with other matrix solvers in Vorpal. There are a few differences, however, because with the linIterUpdater, the full matrix is never created, so the linIterUpdater can perform some extra operations to modify matrix elements at each time-step with negligible computation. Vorpal performs multiplication and division cell-by-cell, not using matrix multiplication.
You can choose to modify the matrix coefficients at each time-step. In many updates, for instance, you may prefer to multiply the coefficients by the time-step at each time-step, allowing for (usually only very slightly) varying time-steps. You are likely to find that this operation is too costly to implement in matrix updaters that construct the entire matrix. (Of course, such updaters can use matrices that are not translationally invariant, while the linIterUpdater cannot.)
linIterUpdater cannot perform matrix solves, so
rowFieldIndex
always refers to writeFieldIndex
,
but you must use the rowFieldIndex
attribute.
.columnFieldIndex
refers to .readFieldIndex
, meaning
the index of fields in the writeFields and
readFields lists. For example, if readFields =
[elecField elecField elecField SumRhoJ SumRhoJ SumRhoJ] and
readComponents = [0 1 2 0 1 2]
then columnFieldIndex = 3
refers
to SumRhoJ_0
.
linIterUpdater Parameters¶
The linIterUpdater
takes the lowerBounds
and
upperBounds
parameters of FieldUpdater, as well as
the following parameters:
- operation (required string)
One of:
set
: See Equation 1.add
: See Equation 2.multiply
: See Equation 3.divide
: See Equation 4.
- readFields (required string vector)
A vector containing the names of fields to read. If multiple components of a field are read, then the field name must be repeated once for each component.
- readComponents (required integer vector)
For each
readFields
, a component; the jth component of this vector is used for the jthreadFields
specified.
- writeFields (required string vector)
A vector containing the names of fields to update. If multiple components of a field are written, then the field name must be repeated once for each component.
- writeComponents (required integer vector)
For each
writeFields
, a component; the jth component of this vector is used for the jthwriteFields
specified.
- dtCoefficients (optional float vector, default = [1.0 0.0])
Two components [\(c_0\) \(c_1\)]. The matrix coefficients will be multiplied by \((c_0 + c_1 \Delta t)\) where \(\Delta t\) is the current time step. If \(c_1\) is not specified it is assumed to be zero.
- FieldMatrix (required parameter block)
Describes matrix \(\mathbb{A}\). It must contain only StencilElement code blocks, each of which is used to describe an element of matrix \(\mathbb{A}\).
Example linIterUpdater Block¶
<FieldUpdater ampereLinIterVec>
kind = linIterUpdater
operation = add
lowerBounds = [0 0 0]
upperBounds = [NX NY NZ]
dtCoefficients = [0. 1.]
readFields = [Binit Binit Binit SumRhoJ SumRhoJ SumRhoJ]
readComponents = [0 1 2 1 2 3]
writeFields = [EcalcLinIterVec EcalcLinIterVec EcalcLinIterVec]
writeComponents = [0 1 2]
<FieldMatrix dEdt>
# dEx / dt
<StencilElement ExBz0>
minDim = 2
value = $LIGHTSPEED**2/DY$
cellOffset = [0 0 0]
columnFieldIndex = 2
rowFieldIndex = 0
</StencilElement>
...
</FieldMatrix>
</FieldUpdater>