Blocks¶
Input blocks are used to create simulation objects. The block is enclosed by opening and closing tags, such as:
<Grid globalGrid>
.
.
.
</Grid>
The tag determines the following:
Object type: Begins with a capital letter and is in "camelCase". For example,
Grid
orEmField
.Object name: Indicated with a lower case letter and is in "camelCase". For example,
globalGrid
.
You use the object name to refer to the object in other input blocks. For example, in the input block for a particle object, you may refer to the name of the electromagnetic field object.
Input blocks can be nested. For example, input blocks for boundary conditions are nested within the input block for an electromagnetic field.
Implementation Kind¶
Most Vorpal blocks, including both top level and nested blocks, have several algorithms from which
you may choose by specifying a parameter named kind
. For example, an EMField may be
modeled as a Yee field, a direct sum field, a constant field, or any of several other types. You
use the kind
parameter to select a particular implementation. Each block description in this
manual lists the available kind
parameter settings for that block.
Note
If you don’t see the implementation kind you need for a given field block, you may wish to
consider learning to use the MultiField
blocks to define your own implementation. In
addition, Tech-X Professional Services is available on a contractual basis to create custom
implementations and simulations. Contact Tech-X at sales@txcorp.com to discuss consulting options.
Example blocks specifying kinds
:
<EmField myExternalField>
kind = funcEmField
<STFunc E0>
kind = expression
expression = EX_1 * cos(K_PE * x) * H(DRIVE_TIME - t)
</STFunc>
</EmField>
Top Level Blocks¶
Blocks that appear at the top level of the input block hierarchy define the basic characteristics for the simulation as a whole and for other blocks that will be used in the simulation. Some top level blocks, such as Grid, Decomp, SumRhoJ, can appear only once in an input file, and are denoted as singletons. Every simulation must, without exception, contain a Grid and Decomp block.
Other blocks, such as Species, can be used as many times as needed in the input file. You will find detailed descriptions of blocks in the Text Setup section of VSim Reference.
Top level blocks include:
- Grid (singleton):
Determines the simulation size and relationship of physical coordinates to cell indices.
Grid
is required in every input file block.- Decomp (singleton):
Determines the domain decomposition and periodicity.
Decomp
is required in every input file block.- SumRhoJ (singleton):
Defines the properties of the charge and current density 4-vector field.
- GridBoundary:
Defines any embedded boundaries.
- EmField:
Defines any electromagnetic fields.
- ComboEmField:
Defines any combinations of electromagnetic fields.
- Fluid:
Defines any fluids.
- Species:
Defines any particles.
- MonteCarloInteractions:
Defines any random processes that may occur between different objects in the simulation, such as collisions or ionization processes.
- MultiField:
Defines general field blocks whose parameter and variable values may be adjusted during the simulation.
- ScalarDepositor:
Alternate method to deposit charge from charged particles in a simulation into a
depField
.- VectorDepositor:
Alternate method to deposit current from charged particles in a simulation into a
depField
.- History:
Used to record data from a simulation over time.
For more details, please refer to the respective sections in VSim Reference.
Nested Blocks¶
While top level blocks are used at the top of the input file hierarchy, nested blocks are included within other code blocks. For example, a Vorpal Species block can contain a ParticleSource block that describes how that species is inserted into the simulation. The ParticleSource code block is, therefore, said to be nested within the species block. Nested blocks are noted in the descriptions of those blocks that can contain them.
A nested block applies only to the block that contains it. For example, you can use a BoundaryCondition block to affect an EmField. You could then specify different boundary conditions for a second EmField block.
Particle species can also contain other objects. For example, you can use
ParticleSource and ParticleSink blocks in Species to describe
where particles are to be placed into and removed from the simulation. By using these blocks’
kind
parameters, you describe how the emission or absorption is to be accomplished. You are
not limited to defining blocks using a single level of nesting. The ParticleSources
contained inside a particle species like <Species electrons>
also contain a Vorpal
STFunc block. Taken all together, these blocks denote the space-time function used
to describe particle emission.
Example of nested blocks:
<Species electrons>
kind = relBoris
charge = -1.6e-19
mass = 9.109e-31
emField = myEmField
# Nominal density and particles per cell at that density
nominalDensity = 4.41204859999e+22
nomPtclsPerCell = 2.
# Particles loaded in a ramp
<ParticleSource stepSrc1>
kind = bitRevDensSrc
density = 4.41204859999e+22
lowerBounds = [2.5e-07 -2.5e-05 -2.5e-05]
upperBounds = [5e-06 2.5e-05 2.5e-05]
doShiftLoad = 1
vbar = [0. 0. 0.]
vsig = [0. 0. 0.]
# Unit probability
<STFunc macroDensFunc>
kind = constantFunc
amplitude = 1.
</STFunc>
</ParticleSource>
<ParticleSource stepSrc2>
kind = bitRevDensSrc
density = 4.41204859999e+22
lowerBounds = [5e-07 -2.5e-05 -2.5e-05]
upperBounds = [5e-06 2.5e-05 2.5e-05]
doShiftLoad = 1
vbar = [0. 0. 0.]
vsig = [0. 0. 0.]
# Unit probability
<STFunc macroDensFunc>
kind = constantFunc
amplitude = 1
</STFunc>
</ParticleSource>
# Particles out left are removed
<ParticleSink leftAbsorber>
kind = absorber
minDim = 1
lowerBounds = [-1 -1 -1]
upperBounds = [0 21 21]
</ParticleSink>
# Particles out right are removed
<ParticleSink rightAbsorber>
kind = absorber
minDim = 1
lowerBounds = [40 -1 -1]
upperBounds = [41 21 21]
</ParticleSink>
</Species>
Notice that adequate comments are provided to explain what is going on in each nested block.
Note
Tech-X recommends that when you nest input blocks, use an appropriate amount of indentation to improve the readability of the input file.