importFromFileUpdater

importFromFileUpdater

Works with VSimBase, VSimEM, VSimPD, VSimPA, and VSimVE licenses.

Updates a field from a file (e.g,. an hdf5 file). This updater sets the values of a field from a dataset in an appropriate file (e.g., a Vorpal field dump file).

importFromFileUpdater Parameters

The importFromFileUpdater takes the lowerBounds and upperBounds parameters of FieldUpdater, as well as the following parameters:

writeFields (required string vector)

A single element, the field to update with the imported data.

fileName (required string)

Name of the HDF5 file containing the data to read.

dataset (required string)

Name of the HDF5 dataset to read from the file.

component (optional integer, default = 0)

The component to read, if reading a single component. Either this parameter or writeComponents must be given, but not both.

writeComponents (optional integer vector)

The components of the writeField to be set from the file. If given, the vector must have at least one element, and elements must be in sequence, e.g., [0 1 2] or [2 3], not [0 2], not [3 2]. If writeComponents is not given, the updater will update only the component corresponding to the component parameter. Either component or writeComponents must be given, but not both.

datasetLowerBounds (optional integer vector)

See datasetUpperBounds.

datasetUpperBounds (optional integer vector)

With datasetLowerBounds, the bounds describing the subset of the file’s dataset (array) to be copied to the field; the region of cells includes the lower bound, but excludes the upper (as usual for lowerBounds and upperBounds in Vorpal). These bounds are specified by grid index, and must be of the same size as the upper/lowerBounds provided. So for example to import the first 10 cells of a 3 component field

lowerBounds = [0 0 0] upperBounds = [10 10 10] dataSetLowerBounds = [0 0 0 0] datasetUpperBounds = [10 10 10 3]

If you wanted to import the first 10 cells of a 3 component field into cells 10-20 of the destination field it would look like lowerBounds = [10 10 10] upperBounds = [20 20 20] dataSetLowerBounds = [0 0 0 0] datasetUpperBounds = [10 10 10 3]

The length in each dimension must correspond to the length in a spatial dimension (of the volume described by lower/upperBounds), in order. For example, if the updater updates a box in space of size \(10\times 12\times 20\), then then the subset of the file’s dataset may be \(10\times 1\times 12\times 20\) or \(1\times 10\times 1\times 12\times 1\times 12\times 1\), but it may not be \(12\times 10\times 20\) or \(12\times 12\times 20\).

(In a serial simulation, the above correspondence is relaxed if the allowDatasetReshapeInSerial option is true.)

The compatibility of bounds is slightly altered if copyUniformInDir is set; in this case, the length of the dataset dimension corresponding to the direction specified by copyUniformInDir must be one, rather than the same as the length of the updater’s bounds in that direction.

Default:

include entire simulation domain + 1 in each dimension, and all components of the writeField (because that corresponds to Vorpal’s field dump-files)

copyUniformInDir (optional integer)

Allows a (lower-dimensional) file dataset to be copied to a field slice, after which those values are copied into adjacent field slices. For example, if a file contains a 2D dataset representing a function \(f(x, y)\), setting copyUniformDir = 2 would allow setting a 3D field \(F(x,y,z) = f(x,y)\) for every \(z\). When copyUniformInDir is specified, the dataset dimensions must correspond to the updater’s bounds after the updater’s bounds have been modified to have length 1 in the direction of copyUniformDir.

For example, suppose we have a 1D dataset with length 4 and values [10,20,30,40], and a 2+1-dimensional field with dimensions \(4\times 3\times 1\) (a \(4\times 3\) scalar field in 2D). If the dataset bounds are dataSetLowerBounds=[0] and datasetUpperBounds=[4], and the field bounds are lowerBounds=[0,1] and upperBounds=[4,2] (and writeComponents=[0], the only choice for this scalar field), then the field will be set to:

0  0  0  0
10 20 30 40
0  0  0  0

(where the first dimension is horizontal, and the second vertical) but if field bounds are [0,1] and [4,3] and copyUniformDir = 1, then the field will be set to:

0  0  0  0
10 20 30 40
10 20 30 40

allowDatasetReshapeInSerial (optional integer, default = 0 (false))

This option, available only for serial simulations, allows the datasetBounds to be reshaped to match the updater’s bounds; for example, a 1D dataset with 12 elements might be used to update a \(4\times 3\) sub-array of the writeField. Use of this option is discouraged.

Example importFromFileUpdater Block

<FieldUpdater readB>
  kind = importFromFileUpdater
  fileName = sourceSim_B_5.h5
  dataset = "B"
  writeFields = [B]
  writeComponents = [0 1 2]
  lowerBounds = [0 0 0]
  upperBounds = [$NX+1$ $NY+1$ $NZ+1$]
</FieldUpdater>