Understanding Region Indices Used With the MultiField Updater¶
The region alteration flags facilitate description of the possibly different regions of the three components of an updater (such as a Yee Faraday updater). So far, Vorpal protocol has been to compute the magnetic field on simulation boundary faces, but not to compute the electric field on those boundaries (instead setting the electric field by a boundary condition). If the simulation has 10 x 10 x 10 cells, with lower and upper bounds [0 0 0] and [10 10 10] then typically the bounds of updaters for the various field components (in the Yee scheme) are:
\(E_x\): [0 1 1] and [10 10 10]
\(E_y\): [1 0 1] and [10 10 10]
\(E_z\): [1 1 0] and [10 10 10]
\(B_x\): [0 0 0] and [11 10 10]
\(B_y\): [0 0 0] and [10 11 10]
\(B_z\): [0 0 0] and [10 10 11]
The actual field components that are in the simulation volume (including the boundary) are:
\(E_x\): [0 0 0] and [10 11 11]
\(E_y\): [0 0 0] and [11 10 11]
\(E_z\): [0 0 0] and [11 11 10]
\(B_x\): [0 0 0] and [11 10 10]
\(B_y\): [0 0 0] and [10 11 10]
\(B_z\): [0 0 0] and [10 10 11]
To specify the update regions above, you can specify the bounds [0 0 0] and [10 10 10] for all updaters, and add the flag expandToTopInComponentDir = true for the magnetic field updaters, and contractFromBottomInNonComponentDir for the electric field updaters. If the region does not touch the global boundary of the simulation, no changes are made.
Note: Regarding updating beyond the domain, the options cellsToUpdateBelow/AboveDomain allow the updater to update beyond the domainRgn. The domainRgn is the region for which a particular processor is responsible (the main simulation region if running serial on one processor). However, in many cases a processor stores guard cells for a field – cells that technically belong to another processor; the main simulation region usually also has guard cells. Usually the guard cells are updated by that other processor, and the values sent (messaged) to other processors that need those values. Sometimes, when possible, it’s more efficient to calculate guard cell quantities than to receive the values from another processor. This option facilitates such transactions. To understand how to use the cellsToUpdateBelow/AboveDomain options, it helps to understand how an updater figures out which cells to update.
The updater finds the largest region which it is allowed to update; usually this is the local DomainRgn (for example, lowerBounds = [4 6 7], upperBounds = [10 12 14]), but it will be expanded according to the following rules:
If the DomainRgn is at the bottom of the simulation in direction d (and d is not a periodic direction), the updater will be allowed to write as far below the DomainRgn in direction d as it can without going beyond field data (Vorpal may incorrectly estimate how far this is). The top of the simulation is treated similarly. .. note:: Boundary conditions often update field values beyond the global DomainRgn; this feature allows that.
If the DomainRgn is not at the bottom of the simulation in direction d (or d is periodic), then the updater will be allowed to write below the DomainRgn by the number of cells given by (the dth element of) cellsToUpdateBelowDomain. For example, if cellsToUpdateBelowDomain = [1 2 2], the lowerBounds will be adjusted to [3 4 5] (that is, the largest allowed region will have lowerBounds = [3 4 5]).
The updater takes the intersection of the region specified in the input file with the largest allowed region for the particular processor, found in the previous step; this is the updater’s update region.
Note: In the case that direction d is periodic, the region specified in the input file is considered to include translations of itself in direction d. For example, consider a 1D simulation with N cells. If the updater bounds are specified in the input file as 0 to N, and cellsToUpdateBelowDomain = [1], then the allowed region will be -1 to N, and the updater will update cell -1 because cell -1 is equivalent to cell N-1, and cell N-1 is included in the updater bounds. In other words, the intersection of [-1,N] and [0,N] is [-1,]. However, if the update region had been [0,N-5], excluding cell N-1, then the updater would not update cell -1. Because this might be confounding, and Vorpal’s logic may not be perfect, this notion is implemented when the updater region (specified in the input file) is altered, before the updater is created. Vorpal will try to extend the updater bounds in periodic directions as it sees fit. In other words, [0,N] would be extended to [-1,N], and this would be the region that appears in MultiField’s attribute set, which it writes to the standard output, as well as to the per-rank streams. However, [0,N-5] would be unchanged. Then, a straightforward intersection is applied.
The updater then tries to make sure that the updater only needs field data that it can get (so that it doesn’t try to go past the array, causing a segfault).
The component/direction-specific options, such as cellsToExtendBelowDomainInComponentDir, alter the updater attribute set, before the updater is created, and add, say, cellsToExtendBelowDomain, as appropriate.