Particles

In order to define particles in your simulation, you will need to add each type of particle in its own Species block, which will in turn include nested blocks that describe the particles’ sources and sinks.

Species Block

The Species block begins by stating the kind of the particle, which takes into account the anticipated dynamic behavior of the particle (relativistic or non-relativistic, for example) as well as the simulation environment it will live in (Cartesian vs. cylindrical coordinate system, electromagnetic vs. electrostatic, etc.). More information on the types of particle kinds can be found in the Species section of VSim Reference.

Also included in the basic Species block are parameters that describe the general characteristics of the particle, such as mass and charge, as well as the parameters that will be used for calculation of macroparticles (nominalDensity and nomPtclsPerCell).

For a more thorough description of the Species block, please visit VSim Reference: Species.

Macroparticles

  • macroPtclWeight used in VSim but not present in .pre file; determines particle resolution in simulation
  • ParticleSource block: VSim determines # of macro particles to try and load in
    each cell, each time step. May be << 1
  • applyTimes parameter of said block sets an interval in seconds. VSim tries to
    load # of macros ^^ into each cell, each time step, for every time step falling w/in applyTimes
  • can use applySteps instead of applyTimes

VSim uses macroparticles to model the kinetics of physical particles. The relationship between the physical density one wishes to model and the density of macroparticles used in the simulation takes the form:

\[numPtclsInMacro = \frac{nominalDensity \times cellVolume}{nomPtclsPerCell}\]

where

  • numPtclsInMacro = number of physical particles in a macroparticle
  • nominalDensity = nominal density of physical particles
  • cellVolume = volume of a simulation grid cell (or average volume over all cells, if nonuniform)
  • nomPtclsPerCell = number of macroparticles in a simulation grid cell

The number of physical particles in a macroparticle can be set directly by including the following in the Species block:

numPtclsInMacro = (float or integer value)

It can also be determined by setting both of the following parameters in the Species block:

nomPtclsPerCell = (float or integer value)
nominalDensity = (float value)

The sole purpose of the nominalDensity and nomPtclsPerCell parameters in the top level of a Species block is to calculate the number of particles in a macroparticle of that species, according to the relation given above.

Alternatively, one can define this quantity directly using the numPtclsInMacro parameter. With the number of particles in a macroparticle thus determined, one can then load the macroparticles into the simulation domain using one or more ParticleSource blocks (a sub-block within the Species block); these blocks should be configured to load macroparticles in a manner consistent with the desired physical particle density.

Many types (kinds) of ParticleSource can be used within VSim; the complete list is given in the ParticleSource section of VSim Reference.

Use of STFunc blocks to modify density

A number of STFunc input blocks can be used to control or modify the density of physical particles represented by the simulation. Not all ParticleSource kinds permit the use of such blocks.

For more information, please visit the section on xvLoaderEmitter in VSim Reference.

Particle Sources

ParticleSource blocks must be nested in the Species block of the particle you’d like to load or emit.

  • certain blocks like xvLoaderEmitter will have sub-blocks (PositionGenerator and PositionGenerator)
  • certain blocks can add in STFunc blocks (nested) for density functions over time, etc

Particle Sinks

Full Species Block Example

Below is an example of a Species block that includes nested ParticleSource and ParticleSink blocks. For more blocks that are available for nesting under the Species block, please visit VSim Reference.

<Species electrons>
  kind = nonRelES
  charge = ELECCHARGE
  mass = ELECMASS
  nominalDensity = 1.0e12
  nomPtclsPerCell = 10
  fields = [esField]

  <ParticleSource electronSource>
    kind = xvLoaderEmitter

    # Loading particles uniformly across entire grid
    <PositionGenerator initialPosition>
      kind = gridPosGen
      <Slab initSlab>
        lowerBounds = [0 0 0]
        upperBounds = [NX1 NY1 NZ1]
      </Slab>
    </PositionGenerator>

    # Simple velocity generator, with VEL as velocity variable
    <VelocityGenerator initialVelocity>
      kind = beamVelocityGen
      vbar = [VEL 0. 0.]
      vsig = [0. 0. 0.]
    </VelocityGenerator>
  </ParticleSource>

  # Removing particles at upper y-boundary but saving them for use by other code components
  <ParticleSink electronSink>
    kind = absAndSav
    minDim = 1
    lowerBounds = [-1 NY -1]
    upperBounds = [NX1 NY1 NZ1]
  </ParticleSink>

</Species>

For more details on the xvLoaderEmitter particle source, or any other particle source options, please visit the Particle Sources in VSim Reference.

Particle Tracking

Since VSim is a particle-in-cell code, the position of a specific particle in the particle data structure will vary as the simulation proceeds due to sorting and the creation and/or deletion of particles. Before you can track a particle, you must identify the particle by tagging it.

Note

To track an individual particle, you must use a kind of particle species that enables tagging of individual particles. Creating a species with the kind parameter set to one of the following kinds enables you to create tagged particles that you can then use to generate particle position data for all tags (indicating up to some maximum tag value) by using History.

Before particles can be tracked they must be tagged. There are four ways to tag particles.

  • By setting the tags manually with the manualSrc.
  • By using the tagGen STFunc in the funcVelGen VelocityGenerator. See VelocityGenerator in VSim Reference.
  • By using the fieldScaleVelGen VelocityGenerator. This should only be used with relBorisVWScale particles.
  • By using the overwriteTag in the Species block. When this flag is set to true the species takes reponsibility for generating the flags. This is the only option that will work with restore.

If the tags are set manually then the user must insure that the tags are unique or errors will occur tracking the particles.

Example of Using manualSrc to Tag Particles

<Species electrons>
    kind = relBorisTagged
    # constants defined previously
    charge = ELECCHARGE
    mass = ELECMASS
    # Place a single particle in the macroparticle
    emField = constMag
    numPtclsInMacro = 1.
    #
    # If the manual source is used to create
    # tagged particles, the tag must be a unique
    # integer or the particle tracking will not
    # work.
    #
    <ParticleSource SingleParticleSrc>
        applyPeriod = 0
        kind = manualSrc
        # manual particle loaders always require
        # AT LEAST 3 velocity components regardless
        # of NDIM; in this case, NDIM=2
        p1 = [R_GYRO 0. 0. V_GYRO V_Z 0.]
        p2 = [0. R_GYRO -V_GYRO 0. V_Z 1.]
        p3 = [-R_GYRO 0. 0. -V_GYRO V_Z 2.]
        p4 = [0. -R_GYRO V_GYRO 0. V_Z 3.]
    </ParticleSource>
</Species>

Example of Using tagGen to Tag Particles

<VelocityGenerator velGen>
    kind = funcVelGen

    # This sets the tags to be unique integers so they
    # can be tracked by the tagged particle tracking
    # history
    <STFunc component3>
    kind = tagGen
    </STFunc>
</VelocityGenerator>

After you have tagged those particles you would like to track using you can record the particles position and/or velocities (or other internal variables such as the weight) by using the speciesTrackTag History.

Example History Block Used to Record Data from Tagged Particles

#  Tagged particle trajectory history.
<History trajectory>
  kind = speciesTrackTag
  # Any particle with a tag greater than or  equal to
  # the maximum tag will not be tracked.
  maximumTag = 4
  xComponents = all
  species = [electrons]
</History>

For more information on histories, please visit the History section in VSim Reference.