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 ineach cell, each time step. May be << 1
applyTimes
parameter of said block sets an interval in seconds. VSim tries toload # of macros ^^ into each cell, each time step, for every time step falling w/in
applyTimes
can use
applySteps
instead ofapplyTimes
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:
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 withrelBorisVWScale
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.