globalvariables

Global Variables

floattype (string)

Variable that defines the precision of real numbers in the simulation. For greater precision, use the value double, otherwise use the option float. You must define floattype in an input file.

dimension (integer)

Variable that defines the dimensionality (1D, 2D, or 3D) of the simulation. The variable dimension indicates how many dimensions this simulation will use. The -dim command line parameter overrides this variable. You must define dimension in an input file or on the command line.

dt (real)

Step size to use in the simulation. When choosing the step size for your simulation, you must consider stability requirements. For example, for electromagnetic simulations, you should specify a step size that satisfies the Courant condition. You can override the dt variable using the -dt command line option. You must define dt in an input file.

nsteps (integer)

Number of steps to take. (In the case of a restart, nsteps is the number of additional steps.) This can be overridden with the -n command line parameter. You must define nsteps in an input file or on the command line.

dumpPeriod (integer)

How often to dump the data; indicates data is to be dumped whenever the time step has increased by this amount. The command line parameter -d overrides this variable. Must have this defined in an input file or on the command line.

dumpSteps (integer)

An alternative to dumpPeriod allowing an irregular specification of times steps in which to dump. Steps should be in increasing order, but do not need to be evenly spaced. If the simulation runs successfully, or is ended by clicking “Dump and Stop” a final dump will be written so that the simulation can be restarted from the final dump. If the simulation ends with a crash, dumpSteps will not write a final dump, and it will not be possible to restart the simulation from a previous dump.

This option can also be applied to individual field blocks to set the steps at which the particular field is dumped. If dumpSteps is used in this way, care must be taken when restarting the simulation from a previous dump.

dumpSteps (Expression)

Alternative to dumpPeriod in which an expression block of name dumpSteps is defined. Can be used to provide an expression for dumpsteps. For example:

<Expression dumpSteps>
  expression =  or(mod(n+1, VPMW_DUMP_PERIOD) == 1 , mod(n-1, VPMW_DUMP_PERIOD) == 1 ), mod(n, VPMW_DUMP_PERIOD) == 1)
</Expression>

Will dump at the specified VPMW_DUMP_PERIOD, as well as at timestep = VPMW_DUMP_PERIOD + 1 and VPMW_DUMP_PERIOD + 2

verbosity (integer)

Specifies the amount of text output from a simulation run. Increasing the value of verbosity may aid in debugging a simulation. The value can be \(2^N - 1\), with \(0 <= N <= 10\). The values, \(1 <= N <= 4\) are for severe problems that will stop the simulation. The values, \(N >= 8\) are for increasing levels of debug information. The other levels are:

  • verbosity=0, \(N=0\), NONE, no messages output.

  • verbosity=31, \(N=5\), WARNING, include warnings in the output, which should be examined by the user in order to fix any errors that could be affecting the simulation.

  • verbosity=63, \(N=6\), NOTICE, include notices in the output, which are not necessarily issues that need to be fixed, but should still be examined by the user.

  • verbosity=127, \(N=7\), INFO, normal output for informing the user of simulation progress.

randomSeeding (string, default seedDeterministicallyByDefault)

Specifies how Vorpal seeds the (pseudo) random number generators use, e.g., to determine initial particle velocities or whether a Monte Carlo collision occurs.

The recommended option, seedDeterministicallyByDefault allows different random number generators to be used for different input blocks, with the seeds chosen deterministically based on the input block (fully qualified…i.e., including names of parent blocks) name and randomSeed. Another option, seedRandomlyByDefault generates seeds from a separate random number generator, which is itself seeded according to the current time; if run twice (with enough time separation to be resolved by the internal timer), a simulation will use different random number sequences. For these options, each MPI rank in a parallel simulation uses a different seed. If random seeds are explicitly specified in an input file block, the specified seeds are used. The seedGlobalRng option (deprecated) uses the same random number generator for many (but not all) objects.

randomSeed (integer, between -1 and 2147483647, default 1)

A seed for generating (pseudo) random numbers. If randomSeeding = seedDeterministicallyByDefault, then changing this value will change the seeds for all random number generators used in a simulation. If this is set to -1 (the recommended option), then a randomSeed will be chosen based on the current time. This option has a similar effect for randomSeeding = seedGlobalRng, except it affects only the global random number generator (excluding input blocks that take seed or randomSeed options). This option has no effect for randomSeeding = seedRandomlyByDefault.

useGridBndryRestore (boolean)

Switch to control the method for obtaining grid boundary information on restarts. The default (true) is to input boundary information from the dump files. Setting this switch to false means that the grid boundary information is re-calculated, which can be computationally more intensive.

useHistoryRestore (boolean)

The default(true), restores histories so that the dump and restart yields the same result as simply continuing simulation (also important for feedback); if false, treat history dump file as if empty, and append data only with no regard for previous data

copyHistoryAtEachDump (boolean)

The default(true), copies the History file at each dump in a HistoryOld file before appending the new history data. This is a safety measure in case the history file gets corrupted. If false, the data is simply appended to the History file, without creating a back up (or copied) file.

stepPrintPeriodicity (integer)

How often to print out the “Taking step n at clock time…” message as the simulation runs. By default, this option is 1 and the message is printed every step. If this option is 0, the message will never be printed. If this option is 10, the message will be printed for every tenth step. This option is useful for reducing the amount of output of simulations that run many time steps.

timingAnalysisPeriodicity (integer)

How often to calculate (and print) rough timing diagnostics to evaluate the speed of a simulation. This is useful for analyzing load-balancing and parallel scaling or for charactarizing the computational performance of simulations.

By default, this option is -1, and no timings are calculated; if 0, timings are printed out for the entire simulation. If a positive integer, timings will be printed out periodically. For example, if this option is 1000, the timing for each set of 1000 time-steps will be printed out (as well as a summary for the entire simulation).

The output is repeated in a single-line format that can be converted into a .csv (comma separated values) file using the command line utility grep. For example, to extract the output of timingAnalysisPeriodicity from mySimulation.out into a new file timingAnalysis.csv that can be opened by most spreadsheet software, one would execute grep -oP '(?<=timingAnalysis:,).*' mySimulation.out > timingAnalysis.csv.

Timings are calculated from wallclock-time and will be affected by other activity. The timing resolution varies from system to system. Short times (much less than one second) may be inaccurate.

Global Variables Specific To Moving Windows

The two global parameters downShiftDir and downShiftPos apply to Vorpal’s moving window feature. The moving window feature allows the simulation window to move at the speed of light in the chosen direction. This feature is used to reduce the size of the simulation box while following the physics phenomenon of interest such as a laser pulse or a particle beam propagating at a velocity close to the speed of light.

downShiftDir (integer)

Control variable for the moving window option that sets the direction of the moving window. If the downShiftDir parameter is not specified or set to -1 for, Vorpal does not use the moving window. Set to a number between 0 and dimension to cause a down shift (moving window) in that direction.

downShiftDir Parameter Values

  • null (If no value specified, Vorpal does not use the moving window.)

  • -1 (If -1 is specified, Vorpal does not use the moving window)

  • 0 (x direction)

  • 1 (y direction)

  • 2 (z direction)

downShiftPos (real)

Distance at which Vorpal should activate the moving window feature. Vorpal calculates the time equal to this distance divided by the speed of light to determine when to turn on the moving window. The downShiftPos parameter may be set to a variable such as DSHFTPOS, which has been assigned a real number value such as 0.95**LX*, where LX is the length of the grid along the x axis.

OAFunc shiftSpeed (block)

Function (of one variable) that returns the velocity of the moving window (in m.s -1) as a function of time. When using kind = expression in an OAFunc block x is the default variable, to use t instead, specify variable = t in the OAFunc block [see expression (OAFunc)]. You can still use x but be aware that x represents the time in this case.

Example Moving Window Code

# Moving window
# Shift along direction 0
downShiftDir  = 0
# Start shifting at t = DSHFTPOS/(speed of light)
downShiftPos  = DSHFTPOS

<OAFunc shiftSpeed>
   kind = expression
   expression = LIGHTSPEED *(BETA - ALPHA *t)
   variable = t
</OAFunc>

Global Variables Specific to Particles

maxcellxing (integer)

In particle simulations in which the particles could ordinarily cross more than one cell in a time step and cause out-of-bounds memory access (such as can happen in electrostatic simulations with non-relativistic dynamics), you can impose a velocity limit to prevent the out-of-bounds memory access from occurring by using the maxcellxing variable. For example, maxcellxing = 1 will limit the particle velocity so that the particle cannot cross more than one cell per step. That is, if for any direction i, velocity_i * dt > dx_i, then the velocity is reduced in magnitude so that velocity_i * dt<= dx_i for all i. Since imposing a velocity limit introduces error into the simulation, for cases in which you must use the velocity limit for a significant number of particles, you should lower the time step for the simulation.

sortPtcls (boolean, default = true)

Specifies whether or not you want Vorpal to sort the particles based on an algorithm that intelligently selects the time step at which to sort. This can affect performance and may be a parameter that you want to examine on your own for its effect on performance.

dnSortMin (integer)

This parameter is used to instruct Vorpal what is the minimum number of time steps before sorting of the particles. This allows sorting to be deterministic and thus repeatable.

dnSortMax (integer)

This parameter is used to instruct Vorpal what is the maximum number of time steps before sorting of the particles. This allows sorting to be deterministic and thus repeatable.