VSim Histories

History

Top-level block for recording data from a VSim simulation. You can use History blocks for VSim to calculate and record data at every time step during a simulation.

History uses the kind parameter to determine which specific data to collect.

History data is useful for diagnostics, as well as determining the basis for performing current and field parameter adjustment during the simulation.

Throughout a simulation run, VSim writes the History data to a separate HDF5 file. The History data file has the file name suffix _History.h5

When a simulation is started or restarted, VSim looks for an existing History file. If VSim finds a History file, VSim appends data to contents of that existing file. If VSim does not find a History file, VSim creates a new file.

When Histories Collect Data

Generally, histories collect data at the end of each time step, after all other VSim objects have been updated.

However, histories can also collect data after the initialization of VSim objects (just before the first time step).

Some histories do not do this. To avoid collecting data after initialization, simply add the following to the <History> block:

<Expression applySteps>
  expression = (n > 0)
</Expression>

History Parameters

History block parameters might include:

kind (string or string vector): Determines type of Field or Species data to be collected in the History data file during the simulation run. The available field and particle species kinds are detailed in descriptions in the following pages. In addition to specifying the kind, for each History block you must also specify one of the field, fields, or species keywords (see below).

keyword (string or string vector): Indicates species or field(s) for use with specified History kind.

field (string): Indicates the field for a History kind that reports data for a single field. Specify a field reference in a History block by using the name of the EmField followed by a dot (.) then the name of the field subobject. Example: field = multiField.elecField

fields (string vector): Indicates the fields for a History kind that reports data for multiple fields. Specify references to fields in a History block by using the name of the EmField followed by a dot (.) then the name of the field subobject. Example: fields = [multiField.elecField multiField.magField]

species (string vector): Indicates particle species type for a History kind that reports data for particle species. Example: species = [electrons]

Field History

acceleratingVoltage

bLoop

EMfieldEnergy

fieldAtCoords

fieldAverage

fieldAtIndices

fieldEnergy

fieldOnSemiCircle

fieldOnMovingPlane

fieldOnLine

fieldPoyn

fieldSlab

integratedSurfaceFieldSquared

kirchhoffSurfaceIntegral

jDotE

peakSurfaceFieldMagnitude

pseudoPotential

timeAverage

Particle History

speciesAbsPtclData

speciesCurrAbs

speciesCurrEmit

speciesDiag

speciesEnergy

speciesEngyAbs

speciesMomen

speciesNumberOf

speciesNumPhysical

speciesRmsDistToAxis

speciesRmsMomen

speciesRmsPosition

speciesTrackTag

speciesDataOnPlane

History Operation Histories

binaryOperation

Feedback Histories

feedbackDesired

feedbackMeasured

Scalar Histories

scalarValue

Tensor Histories

fieldArray

cellFuncHist

functionOfTime

ptclSumData

speciesAbsPtclData2

speciesBinning

Tensor Histories are somewhat different from other Histories. They comprise select Histories that store records as a tensor (or multi-dimensional array). A record is a single tensor (array), and the tensor history is a 1D array of records. A record could be the value of a field at a certain time, or a sub-array of a field at a certain time, or the properties of a particle absorbed, etc.

The values stored in Tensor Histories can be accessed (during a simulation) through UserFuncs (see historyFunc) to provide feedback or to perform further calculations from the results of Tensor Histories.

Briefly, kinds of tensor histories are:

fieldArray: Stores a subarray of a field (at desired time-steps).
functionOfTime: Stores a function of time; generally this function involves the values of other tensor histories. For example, it might multiply two histories together.
cellFuncHist: Calculates line, surface, and volume integrals, as well as finding field maxima, etc.
speciesAbsPtclData2: Records data for particles absorbed on a boundary – either data for each particle, or statistics (averages, etc.). This history is similar to speciesAbsPtclData, but stores multiple data per particle in a single history.
speciesBinning: Creates an array of bins, with each binning holding a vector, and for each particle, adds an amount to a bin chosen according to the particle properties. This history allows general particle distributions (e.g., velocity distributions) to be stored.

Besides the attribute specific to each kind, they take the following attributes (which should mostly be ignored):

syncPeriod (non-negative integer, optional, default = 0):
Reduces memory use (for parallel simulations with multiple processes per node) by telling the processors to communicate their local histories (to form the global history) every syncPeriod updates. (E.g., if applyPeriod = 10, so the history adds a record every 10 time-steps, and syncPeriod = 3, then the the processors will communicate every 3 updates, which is every 30 time-steps.) With the default value (0), processors will communicate only when necessary, as at dump time.

This option may reduce memory use in parallel simulations with multiple processes on a single node. Roughly, it reduces memory use by a factor a bit less than the number of processes per node. For example, if there are 12 processes per node (all of which share the same memory), and the simulation runs out of memory after 100 history updates, then setting syncPeriod to a number less than 100 will allow approximately 1000 updates (a bit less than 100 times 12). After this, the only way to avoid running out of memory is to dump the data (by increasing the simulation’s dumpPeriod), which removes most past history records from memory.

Communication takes time, even in the limiting case of very little data, so one generally wants to avoid communicating small amounts of data at every time step. Histories that update at every time step should use a larger syncPeriod. On the other hand, large histories that update infrequently should use a small syncPeriod, perhaps 1 to 10.

maxMemChunkSize (integer, optional):
This option should be rarely used. When used, it should be set to a rough size (in bytes) of an amount of memory that will always be available. The history will use chunking to try to avoid temporary use of chunks of memory much larger (a few times) than maxMemChunkSize. For example, when the history is dumped to disk (for which it must create a temporary array to store the history), it will dump the data in chunks of size (on the order of) maxMemChunkSize. This also affects temporary memory use when communicating histories among different ranks in a parallel simulation. Probably this should be at least 100 MB, and at least 1 kB times the number of processors in a parallel simulation.

minRecordsToKeep (integer, optional):
This option should usually not be needed, since Vorpal can almost almost always figure it out. This option can be set to a minimum number of history records that Vorpal will keep (e.g., for HistoryFuncs of kind=historyFunc). In particular, Vorpal deletes history records that have been saved to disk (to save memory), but will retain at least minRecordsToKeep, and upon restart, Vorpal does not reload the entire history, but only minRecordsToKeep records. A situation that might require specification of minRecordsToKeep: If a simulation is run (with no HistoryFunc) and dumped, the input file is modified to add a HistoryFunc, and then the simulation is restarted from the dump. In this case, Vorpal could not figure out from the first run, how many past records the second run would require.