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:

\[E^i_{b_i}(x,y,z,t+\Delta t) = \sum_j A_{ij} F^j_{b'_j}(x+m_j \Delta x, y+n_j \Delta y, z+p_j \Delta z,t)\]

\[E^i_{b_i}(x,y,z,t+\Delta t) = E^i_{b_i}(x,y,z,t)+\sum_j A_{ij} F^j_{b'_j}(x+m_j \Delta x, y+n_j \Delta y, z+p_j \Delta z,t)\]

\[E^i_{b_i}(x,y,z,t+\Delta t) = E^i_{b_i}(x,y,z,t)\sum_j A_{ij} F^j_{b'_j}(x+m_j \Delta x, y+n_j \Delta y, z+p_j \Delta z,t)\]

\[E^i_{b_i}(x,y,z,t+\Delta t) = \frac{E^i_{b_i}(x,y,z,t)}{\sum_j A_{ij} F^j_{b'_j}(x+m_j \Delta x, y+n_j \Delta y, z+p_j \Delta z,t)}\]

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 jth readFields 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 jth writeFields 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>