speciesBinning

speciesBinning

A History that bins or sums particle data into an array according to a user-specified function; for example, the velocity distribution of a species can be recorded at every time step.

This history creates a multidimensional array of bins, with each bin contaning a vector; at every time step, a new array is created, and for each particle, a (vector) value is added to a particular bin; the bin is chosen based on the particle’s properties.

Data is recorded for all particles in a simulation belonging to one of a list of specified species, or alternatively, for all particles absorbed by a list of specified particle absorbers.

To use the history, one must decide the dimensions of the array of bins, as well as the length of the vectors located at every array index. One then writes a Expression that, based on particle properties requested in ptclAttributes, determines an index (of the array), and a vector-value (to add to the bin with that index).

speciesBinning Parameters

species (vector of strings, required)

A list of Species for which data will be recorded.

If the ptclAbsorbers attribute is not given, then data for all the particles in these species will be recorded; otherwise, data will be recorded only for species absorbed by the specified absorbers (in this case, there should be one Species listed for each ptclAbsorber).

ptclAbsorbers (vector of strings, optional, default = [])

A list of ParticleSinks (of kind=absAndSav or similar, see absStairStep Parameters) for which this history will record data. If this attribute is given, only data for absorbed particles will be recorded. There must be, listed in the species attribute, one species for each absorber.

ptclSources (vector of strings, optional, default = [])

A list of ParticleSources (with recordParticleData=true) for which this history will record data. There must be, listed in the ptclSourceSpecies attribute, one species for each source.

ptclSourceSpecies (vector of strings, optional, default = [])

A list of species, one for each ParticleSource in ptclSources, indicating the emitted species (note that some ParticleSources can emit multiple species).

binDims (vector of positive integers, required)

The dimensions of the “array of bins” (the array of vectors) or equivalently, the dimensions of each history record not counting the last dimension (which is given by arrayComponents).

For example, to bin by velocity direction, one might choose to have 40 divisions in longitude and 20 division in latitude, hence binDims = [40, 20].

binDimDescriptions (vector of strings, optional)

A list of descriptions or labels for each array dimension. For example, when recording velocity angular distributions, the bin dimensions might represent the \(\phi\) and \(\theta\) coordinates, and so binDimDescriptions might be ["phi (radians, 40 divisions)"  "theta (radians, 20 divisions)"], or whatever descriptions might be helpful for someone examining the output file.

binComponents (positive integer, required)

The length of the vector in each bin, or equivalently, the length of the last dimension of each history record.

binComponentDescriptions (vector of strings, required)

A list of descriptions or labels for each of the binComponents. For example, binComponents = 2 and the 2 components are the total weight of particles and the number of macroparticles (in each bin), then one might use binComponentDescriptions = ["total ptcl weight" "number of macroparticles"].

indexAndResult (code block, required)

An Expression <Expression indexAndResult> that takes as many scalar arguments as elements in ptclAttributes, and returns \(n_d + n_c\) values, where \(n_d\) is the number of “bin” dimensions (the number of elements in binDims), and n_c is binComponents. See expression.

The first \(n_d\) values must be integers; moreover, they must be a valid index in arrayDims (in the expression, the funtions int(x), floor(x), and ceil(x) may be useful for creating integers from floats).

warningLevel (integer, optional, default = 2)

Specifies behavior if <Expression indexAndResult> produces an index that does not correspond to a bin (i.e., that is out of range).

• 0: ignore completely

• 1: warn the first time this happens (and ignore particle)

• 2: warn every time this happens (and ignore the particle)

• 3: halt the simulation when this happpens

DatasetAttrib (vector of floats)

<DatasetAttrib> contains a vector of floats to be added to attributes in the History’s dataset stored on disc (code block, optional). The DatasetAttrib takes a single attribute, value. For example:

<DatasetAttrib binEdgesInJoules>
  value = [0. 4e-19 8e-19 1.2e-18 1.6e-18 2e-18]
</DatasetAttrib>

will store the above list of values under an attribute named binEdgesInJoules. (One can specify as many <DatasetAttrib> objects as desired.)

This may be useful in, e.g., the following situation. Suppose one is binning particles by energy, with 5 bins, from 0 to 2e-18 J. For post-simulation analysis, it might be useful if the history dataset also described the bins. By adding the above <DatasetAttrib>, that information gets stored along with the history dataset; someone analyzing the history dataset can then understand how the data is binned, without having to look in the input file.

ptclAttributes (vector of strings, required)

A list of the particle attributes that should be recorded by this history. The following strings are allowed.

one:

The number one. This is useful, e.g., for History of kind speciesAbsPtclData2, where one might want to count the number of macroparticles—e.g., summing the number 1 for each macroparticle.

ndim:

The simulation spatial dimensionality.

nIntVars:

The number of internal variables per particle (e.g., velocity components, plus weight, plus tag, etc.)

iVarRole0, iVarRole1, etc.:

The role of an internal variable, such as velocity or weight, expressed an an integer.

time:

The time (e.g., at which the particle was absorbed), is seconds.

weight:

The particle weight (always 1 except for variable-weight particles); usually numPtclsInMacro is the quantity desired for physical results, rather than weight, because the weight is relative to the macroparticle, not the physical particle. E.g., if each standard macro particle has 100 electrons, then a macro-particle with weight 1 is equivalent to 100 electrons, and weight 0.1 is equivalent to 10 electrons.

tag:

The particle tag (or, if the species is untagged, returns -1.).

numPtcls:

The number of physical particles in the macroparticle, or physical weight (i.e., the macro-particle’s weight times the species’s number of physical particles per macroparticle).

mass:

The mass (in kg) of the macroparticle.

pMass:

The mass (in kg) of a physical particle.

charge:

The charge (in Coulombs) of the macroparticle.

pCharge:

The charge (in Coulombs) of a physical particle.

cell0, cell1, cell2:

The global index of the cell containing the particle.

pos0, pos1, pos2:

The position of the particle, (e.g., in Cartesian geometry, position_0 is x, position_1 in y, etc., in meters). If the particle was absorbed or emitted, this is the location at or from which it was absorbed or emitted.

vel0, vel1, vel2:

Components of velocity (m/s).

gVel0, gVel1, gVel2:

Components of gamma times velocity (m/s).

gamma:

\(1/\sqrt{1-v^2/c^2}\)

velMag:

The magnitude of the particle velocity (m/s)

gVelMag:

The magnitude of gamma times the particle velocity (m/s)

physEnergy:

The (relativistic) kinetic energy of a physical particle in the macroparticle (in Joules)

energy:

The (relativistic) kinetic energy of the macroparticle (in Joules)

pNonRelEnergy:

The non-relativistic kinetic energy (\(mv^2/2\)) of a physical particle in the macroparticle (in Joules) Note: this assumes that the species is non-relativistic (in the sense that its internal variables store the 3-velocity and not the 4-velocity; a relativistic species will calculate, meaninglessly, \(0.5mv^2/(1-v^2/c^2)\)).

nonRelEnergy:

The non-relativistic kinetic energy (\(mv^2/2\)) of the macroparticle (in Joules). Note: this assumes that the species is non-relativistic (see physNonRelativisticKineticEnergy).

rank:

The rank (in a parallel simulation) on which the particle was absorbed

baseNumPtcls:

The default number of physical particles per macroparticle (e.g., in a macroparticle with weight 1.)

sWtIndex:

The component of the internal variables containing the weight (or -1 for species that don’t have variable weight).

sTagIndex:

The component of the internal variables containing the tag (or -1 for species that aren’t tagged).

sRel:

1 if the species is relativistic, 0 if not (currently this is not very trustworthy; the criteria for being relativistic are not consistent across all species; ideally, it should indicate whether a species stores the 4-velocity or the 3-velocity in its internal variables).

current:

The current associated with the macroparticle charge (in A), i.e., the charge divided by the time-step

spIndex:

The index of the species of the particle; i.e., if multiple species are collected.

abIndex:

The index of the absorber that absorbed the particle, if particles are collected from multiple absorbers.

sourceIndex:

The index of the source that emitted the particle, if particles are collected from multiple sources.

Particles that are collected from absorbers or emitters can have additional attributes:

normAbs0, normAbs1, normAbs2:

The unit surface normal pointing into the absorber (or away from the direction of emission); this can be the zero vector in cases where the normal is not known (which can sometimes happen in pathological cases)

sTanA0, sTanA1, sTanA2:

A vector tangent to the (absorption or emission) surface and in the plane of the particle’s velocity (with a positive scalar product between the two).

sTanB0, sTanB1, sTanB2:

A vector tangent to the (absorption or emission) surface, perpendicular to the normal and surfaceTangentA; The vectors (-surfaceNormalIntoAbsorber, surfaceTangentA, surfaceTangentB) should form a right-handed orthonormal basis (i.e., with the normal pointing away from the absorber, which is convenient for an emission-velocity basis).

iAng:

The angle (in radians) of incidence relative to the surface normal into absorber. An angle of 0 indicates a velocity pointing directly into the absorber.

cosIAng:

The cosine of the angle of incidence.

speciesBinning History Example

<History gammaDist>
 kind = speciesBinning
 species = [electrons]
 ptclAttributes = [numPtcls gamma]
 $ NUMBINS = 200
 $ G_MIN = 1.
 $ G_MAX = 30.
 binDims = [NUMBINS]
 binDimDescriptions = ["relativisticGamma"]
 binComponents = 1
 binComponentDescriptions = ["number of physical particles in bin"]
<Expression indexAndResult>
 kind = expression
 $ g = relativisticGamma
 $ INDEX = min(NUMBINS-1, int(0.5 + (NUMBINS-1)*(g-G_MIN)/(G_MAX-G_MIN)))
 expression = vector(INDEX, numPtcls)
</Expression>
 # to explicate hdf5 dataset
 $ GAMMA_BIN_EDGES = [ G_MIN + n*(G_MAX-G_MIN)/NUMBINS for n in range(NUMBINS+1)]
<DatasetAttrib gammaBinEdges>
 value = GAMMA_BIN_EDGES
</DatasetAttrib>
</History>