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 or EmField.

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, DomainDecomp, SumRhoJ, can appear only once in an input file, and are denoted as singletons. Every simulation must, without exception, contain a Grid and DomainDecomp 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 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.

DomainDecomp (singleton):

Determines the domain decomposition and periodicity. DomainDecomp 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.