ptclSumData

ptclSumData

Records data as a simple sum over particles (typically emitted or absorbed by a source or sink). This TensorHistory is meant to be lightweight, so it does not offer much flexibility.

The History of kind=ptclSumData is a tensor history that records the number of particles, the total weight of particles, the sum of particle positions, and the sum of particle internal variables (i.e., velocity, weight, etc.) – for particles emitted by a ParticleSource, or absorbed by a ParticleSink, in each timestep.

These quantities can be calculated very easily, and don’t take much memory (compared with storing individual particle data, as in speciesAbsPtclData2). This history is an easy way to calculate, e.g, the total charge (hence current) emitted by a ParticleSource, or the average velocity, or average positon, etc. (More complicated quantities like average energy absorbed need to be calculated with, e.g., speciesAbsPtclData2.)

Simply recording data should not reduce simulation speed. However, if the recorded data is used at each timestep (e.g., in a historyFunc), then the data must be summed over all MPI ranks (in a parallel simulation) at each timestep. This communication can potentially slow down a simulation; however, in many simulations, this communication will be hardly noticeable.

If this History is used to record data for multiple species, they must all have the same IDIM – i.e., the same number of internal variables. For instance, a constant weight species and a variable weight species cannot be recorded in the same ptclSumData history.

The resulting History will be a 2D array: a 1D array of length NDIM+IDIM+2 for each timestep. The 1D array will contain (in this order):

  • component 0: the sum (over particles) of macroparticle ‘weight’ (see note below) times x-position (or whatever the first spatial dimension is)

  • (if NDIM > 1) component 1: the sum of particle weight times y-position

  • (if NDIM > 2) component 2: the sum of particle weight times z-position

  • component NDIM: the sum of particle weight times component zero of the particle’s internal variables (i.e., usually the weighted sum of x-velocity)

  • components NDIM+1 through NDIM+IDIM-1: weighted sums of the rest of the internal variables

  • component NDIM+IDIM: the sum of particle weight (all the above quantities can be divided by this to get average position, velocity, etc.)

  • component NDIM+IDIM+1: the number of macroparticles

  • Note: here, macroparticle ‘weight’ is the actual number of physical particles in the macroparticle.

ptclSumData Parameters

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

A list of ParticleSink objects that record summed data over particles. (The attribute recordParticleSumStats=true may need to be added to the <ParticleSink> blocks.) These should be qualified by the species name: e.g., electrons.cathodeAbsorber.

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

A list of ParticleSource objects that record summed data over particles. (The attribute recordParticleSumStats=true may need to be added to the <ParticleSource> blocks.) These names should be qualified by the species name: e.g., electrons.cathodeEmitter.

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

A list of species, one for each ParticleSource in ptclSources. This list must be specified (only) if one of the ParticleSources emits more than one species.

ptclSumData History Example

# This history records the sum over emitted particles from
# two ParticleSources in species electrons.
<History absobedPtclSums>
  kind = ptclSumData
  ptclAbsorbers = [ electrons.cathodeAbsorber1 electrons.cathodeAbsorber2 ]
</History>

<History emittedPtclSums>
  kind = ptclSumData
  ptclSources = [ electrons.cathodeEmitter electrons.secondaryEmitter ]
  ptclSourceSpecies = [ electrons electrons ]
</History>

It may be helpful to use a functionOfTime History with a historyFunc to convert the ptclSumData to desired quantities.

# This history converts the above ptclSums History to current.
# To do this, you have to know the timestep DT and the number of
# physical particles per species electron macroparticle of weight 1
# (and also the electron charge).
<History emittedCurrent>
  kind = functionOfTime
  <UserFunc weightEmitted>
    kind  = historyFunc
    history = emittedPtclSums
    index = [$NDIM+IDIM$]
  </UserFunc>
  expression = -ELEMCHARGE * ELECTRON_MACRONUMBER * weightEmitted(0)/DT
</History>

# This history converts the above ptclSums History to average x-velocity.
<History avgVelocity0>
  kind = functionOfTime
  <UserFunc sumWtVel0>
    kind  = historyFunc
    history = emittedPtclSums
    index = [$NDIM+0$]
  </UserFunc>
  <UserFunc sumWt>
    kind  = historyFunc
    history = emittedPtclSums
    index = [$NDIM+IDIM$]
  </UserFunc>
  expression = sumWtVel0(0) / sumWt(0)
</History>