These macros will be mostly used by the framework, but the user may want to import and use them (especially like the mathphys macro), so they are docemented here.

All utility macros are available to all packages.

listUtilities.mac

This macro file can be imported to an input file with

$ import listUtilities

Macros available in listUtilities are used to append blocks and lists.

logicals.mac

This macro file can be imported to an input file with

$ import logicals

This macros file simply defines the logical variables: true, TRUE, false, and FALSE.

mathphys.mac

This macro file can be imported to an input file with

$ import mathphys

In many of the input file examples that are supplied in VSimComposer, you will see macros from mathphys invoked. Macros available in mathphys define a series of physical and mathematical constants that are commonly used in simulations. The constants defined in this macro file are:

# Math constants
$ PI = math.pi
$ PIO2 = 0.5*PI
$ TWOPI = 2.*PI

# Physical constants from http://physics.nist.gov/cuu/Constants/index.html
$ LIGHTSPEED = 2.99792458e8     # m/s
$ C2 = LIGHTSPEED*LIGHTSPEED
$ MU0 = 4e-7*PI
$ EPSILON0 = 1/(MU0 * C2)
$ ELECMASS = 9.10938215e-31     # kG
$ PROTMASS = 1.672621637e-27    # kG
$ MUONMASS = 1.88353130e-28     # kg
$ ELEMCHARGE = 1.602176487e-19  # C
$ KB = 1.3806504e-23 # J/K

# gyromagnetic anomaly of the proton (CODATA 2014)
$ PROTON_GMA = 1.7928473508        # (85), dimensionless
# gyromagnetic anomaly of the electron (CODATA 2014)
$ ELECTRON_GMA = 1.15965218091e-3  # (26), dimensionless

# Secondary parameters
$ ELECCHARGE = -ELEMCHARGE      # C
$ ELECMASSEV = ELECMASS*C2/ELEMCHARGE   # eV

timing.mac

This macro file can be imported to an input file with

$ import timing

It is imported by VSim.mac. This macro file defines time-related parameters and makes them global variables.

Public Macros

setTimingData()

In the typical use case, VPM_DT, VPM_NSTEPS, VPM_DUMP_PERIOD, VPM_DMFRAC, and VPM_CFL_NUMBER are set before entry. This macro then computes VPM_SIMULATION_TIME, and VPM_NUM_DUMPS. VPM_DT is respected if not zero. Otherwise it is computed from the VPM_CFL_NUMBER and the minimum CFL time steps from electromagnetics (if an electromagnetic simulation) and (if there are particles present) the plasma frequency and the thermal electron cell crossing time computed from VPM_MAX_ELECTRON_DENSITY and VPM_MAX_ELECTRON_TEMP_EV.

units.mac

This macro file can be imported to an input file with

$ import units

This macro file contains conversions factors for units to SI units.

utilities.mac

This macro file can be imported to an input file with

$ import utilities

This macro file contains various utilities for testing equality, converting coords, and the like.

Public Macros

isEqualString(aString, bString)

The isEqualString macro tests if two strings are equal. It returns True or False.

Parameters

  • aString – The first of two strings to compare.

  • bString – The second of two strings to compare.

isNotEqualInt(i, j)

The isNotEqualInt macro tests if two integers are not equal. It returns True or False.

Parameters

  • i – The first of two integers to compare.

  • j – The second of two integers to compare.

entryToBool(pd)

The entryToBool macro converts an array of 0/1’s to booleans True/False.

Parameters

pd – An array of integers representing booleans, e.g. periodicity.

verbosity.mac

This macro file can be imported to an input file with

$ import verbosity

This macro file contains the constants used in setting the level of output in a simulation.

After importing, it can be used by setting the verbosity to the desired level, e.g. verbosity = VPM_NOTICE.

The verbosity levels are as follows:

$ VPM_EMERGENCY
$ VPM_ALERT
$ VPM_CRITICAL
$ VPM_ERROR
$ VPM_WARNING
$ VPM_NOTICE
$ VPM_INFO
$ VPM_DEBUG
$ VPM_DEBUG2
$ VPM_DEBUG3

vputilities.mac

This macro file can be imported to an input file with

$ import vputilities

It is imported by VSim.mac. This macro file defines vsim-specific utility macros.

Public Macros

writeIndicesFromCoords(coordBounds)

Convert coordinates to the corresponding indices.

Parameters

coordBounds – The coordinates to be converted. A float array of length VPM_NDIM.

write1CellVolume(p, outwardNormal, dl0, dl1, dl2, l0, l1, l2, st0, st1, st2)

Create a 1-cell slab from in (x,y,z) tuple and a direction outwardNormal. It is a tuple that points in the direction of the outward normal to the surface.

Parameters

  • p – A value that gives the position to place the slab.

  • outwardNormal – Array of integers specifying the outward normals.

  • dl0 – Cell length in the zeroth direction, e.g. VPM_DX.

  • dl1 – Cell length in the first direction, e.g. VPM_DY.

  • dl2 – Cell length in the second direction, e.g. VPM_DZ.

  • l0 – Length of the domain in the zeroth direction, e.g. VPM_LX.

  • l1 – Length of the domain in the first direction, e.g. VPM_LY.

  • l2 – Length of the domain in the second direction, e.g. VPM_LZ.

  • st0 – Starting point in the zeroth direction, e.g. VPM_BGNX.

  • st1 – Starting point in the first direction, e.g. VPM_BGNY.

  • st2 – Starting point in the second direction, e.g. VPM_BGNZ.

getBoundaryOffsets(location)

Apply offsets to our bounds if a boundary condition has already been set to an orthogonal face.

Parameters

location – The boundary location, one of lower/upper[X,Y,Z].