History

History

Top-level block for recording data from a Vorpal simulation. You can use History blocks for Vorpal to calculate and record data about fields and particles in a simulation.

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

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

Throughout a simulation run, Vorpal 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, Vorpal looks for an existing History file. If Vorpal finds a History file, Vorpal appends data to contents of that existing file. If Vorpal does not find a History file, Vorpal creates a new file.

You can create tagged particles that can then be used to generate particle position data by using a History block. Once you have created a tagged species, you can use History blocks to follow particle trajectories based on tag values. Learn how to tag particle species in the speciesTrackTag.

You can use Feedback History blocks to adjust parameters based on measured time dependent quantities. For example, you could automatically adjust the current in a simulation to generate a desired voltage. Learn how to use Feedback History blocks in historyAsSTFunc.

All Tensor Histories can also be used for feedback, in conjuction with UserFuncs of kind=historyFunc (see historyFunc).

When Histories Collect Data

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

However, histories can also collect data after the initialization of Vorpal objects (just before the first time step). Some histories do not do this; all Tensor Histories do collect data just after initialization by default. 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

Particle History

History Operation Histories

Feedback Histories

Scalar Histories

Tensor Histories

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.