Species

Species

One of several different methods for modeling particles in Vorpal. Each Species block is defined by a kind parameter that corresponds to a particular Species algorithm, as well as parameters that describe characteristics of the Species block. Available kinds for Species blocks are discussed in documentation sections following the list of general Species Parameters. Vorpal represents macroparticles. See Macroparticles for more about macroparticles.

For some types of simulations, as discussed in the cellSpecies description, cellSpecies uses optimization algorithms that can result in performance surpassing that can be achieved using other species. Tech-X recommends using cellSpecies whenever your simulation data characterization can conform to functionality supported by cellSpecies.

Note

Vorpal considers the velocities of any non-relativistic particle kind to be velocity. All other particle kinds are \(\gamma v\).

Species Parameters

In addition to the name of the kind, which indicates the algorithm, Species parameters include:

kind (string)

Specifies the species algorithm to be used. See Species kinds in the sections following this list of general Species parameters.

charge (double)

Value describing the charge of a particle in the species.

mass (double)

Positive value describing the mass of a particle in the species.

emField (string)

User-defined combo EmField with which the particle species will interact.

bgEmField (string)

User-defined combo bgEmField used for particles of relBorisDF type.

fields (string vector)

User-defined Fields from a MultiField block with which particle Species will interact. The vector is of the form:

[Electric_Field Magnetic_Field],

where vector items require a space for separation. The order of these vector components is significant. This is used in a Multifields approach to define the electric and magnetic fields as an alternative to defining them through the combo emField.

bgElecField (string)

User-defined Field that explicitly specifies the background electric field via a Multifields Field. Used with particles of relBorisDF type and (in combination with bgMagField) as an alternative to bgEmField.

bgMagField (string)

User-defined Field that explicitly specifies the background magnetic field via Multifields Field. Used with particles of relBorisDF type and (in combination with bgElecfield) as an alternative to bgEmField.

chargeDeps (string)

User-defined ScalarDepositor that deposits charge into a MultiField’s depField.

currDeps (string vector)

User-defined VectorDepositor that deposits current into a MultiField’s depField. Where a complex electric and magnetic field has been used (see cmplxRelBorisDF) one would use currDeps to define both real and imaginary current depositors as follows:

[Real_Current_Depositor Imag_Current_Depositor]

nominalDensity (double)

Positive value suggesting the nominal density for the particles.

nomPtclsPerCell (double)

Positive value suggesting the nominal macro particles per cell in the simulation.

numPtclsInMacro (double)

Positive value setting the number of particles in a macro particle.

depositCurrentThoughFieldsNotUsed (boolean, default = true)

Whether a species should deposit current (to SumRhoJ) even if the species does not use the electric or magnetic fields. This option should be set to true with freeRel or freeRelVW species (which do not “see” EM fields) if the particles should deposit current (hence generate fields). If this option is not set to true, freeRel particles will have no effect on EM fields. Other (non-free) species will deposit current regardless of this option.

dumpPPC (boolean, default = false)

Whether the number of particles per cell should be dumped for this species. This is useful for load balancing using analyzers or custom python scripts.

overwriteTag (boolean, default = false)

Whether to regenerate the tag when adding a particle. This option takes effect only with tagged species. When this option is on, the tag is generated inside the species, rather than with the velocityGenerator. This allows generation of a unique tag when several particle sources are present in the species or if particles of this species can be generated by a MonteCarlo interaction. This option also guaranties that the tags are generated in a unique way after restore. If overwriteTag is not set or set to false, we cannot guarantee that Vorpal will generate unique tags after restore.

For example, the tag may be generated at the same time that a particle’s velocity is generated, but with overwriteTag, that tag will be overwritten by the <Species>.

useSequentialTags (boolean, default = false)

Whether to generate sequential tags for particles (this option only applies if overwriteTag = true); e.g., if there are 10 tagged particles in the simulation, they will have tags 0 through 9. In parallel simulations, communication between processors is required (at every time step that particles might be loaded or emitted) to generate sequential tags; this may significantly slow a simulation.

If tagged particles are loaded or emitted at only a few time steps, it is recommended to use applyTimes (or similar) within the <ParticleSource>; that will prevent any communication except during the valid applyTimes.

consolidatePtclGrps (integer)

An integer flag determining whether Vorpal should consolidate particle groups.

useSegmentedMove (integer, default = 1)

Used to speed up certain types of Vorpal simulations. useSegmentedMove can be set to 1 (default) or 0. This parameter is designed to allow simulations that do NOT need the segmented move decomposition (i.e. lwfa simulations (no gridBndry) with either absorbers or periodic boundaries) to accelerate. Those simulations that use more complex boundaries like gridBndry, reflectors, etc. should use the segmented move, i.e. do not put useSegmentedMove = 0 in your species blocks. If you choose not to use the segmented move, be aware that higher order particles will probably not work very well for the current deposition though the interpolation should be fine.

mode (integer)

Specifies a given mode number for which Vorpal should solve; mode number is from a specified mode expansion, for example, fields are assumed to be expressed as: \(E(x,y,z) = e^{i k z} E(x,y)\), given: \(E(x,y) = E_r(x,y) + i E_i(x,y)\). At present, this is only for the Species kind cmplxRelBorisDF.

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. E.g., 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.

labels (stringVector)

Specify labels for particle components. For example: labels = [x,y,z,Red,Green,Blue]. This is useful whenever relBorisTagged Species Kind, relBorisVWTagged Species Kind, or relBorisVWScale Species Kind is used, as these require special labeling for components 6-8 to display properly. See Velocities and Internal Variables of Particles for a table of the correct labels for each species kind.

dumpPeriodicity (integer, optional)

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.

For more dumping options, see the Dumping Fields, Particles and the “HDF5 Format Data Output Files” section in the User Guide manual.

Macroparticles

Since simulating all of the physical particles in a simulation would be computationally prohibitive, Vorpal makes use of the Particle-in-Cell (PIC) model which uses macroparticles to model a large group of physical particles. This allows a particle simulation to be completed in a reasonable amount of time while still capturing any kinetic effects from the particle distribution in space and time. Depending on the type of particle species used, the ratio of physical particles to macroparticles will be fixed or it can vary from macroparticle to macroparticle. This method does not require modification of the equations of motion since the charge-to-mass ratio of the macroparticles remains fixed.

The Vorpal macroparticle model is based on PIC algorithms from Hockney and Eastwood [HE88] and Birdsall and Langdon [BL91].

Delta-F

Some of the particle species in Vorpal make use of the Delta-F algorithm. The approximate phase-space density in a phase-space volume \(V_{ps}\) that can be found from the weights of delta-f particles using the formula

\[f = f_0 + \frac{V_{cell} \cdot \mathsf{nominalDensity}}{V_{cell} \cdot \mathsf{nomPtclsPerCell}},\]

where:

• \(\mathsf{nomPtclsPerCell}\) are the parameters of the block <Species …>

• \(V_{cell}\) is cell volume as defined by parameters of the block <Grid> at the top level of the Vorpal input file

The Equilibrium phase-space density, \(f_0\), is defined in the block <SVTFunc equilibDist> inside of the block <Species …> where in particular, the approximate density of the real particles in volume \(V\) can be approximated using the equation

\[\rho = \rho_0 + \frac{V_{cell} \cdot \mathsf{nominalDensity}}{V_{cell} \cdot \mathsf{nomPtclsPerCell}} \Sigma w_i,\]

where:

• the summation \(\Sigma w_i\) happens over all particles found in the volume

• \(\rho_0\) is the background density, which is the integral of \(f_0\) over all possible velocities