USim Reference Manual

Introduction

USim Reference is a quick-reference manual for USim users to look up specific USim features and code block syntax for use in editing a USim input file. To learn about the complete USim simulation process, including details regarding input file format and the USim tutorials, or see examples of using USim to simulate real-world physics models, please refer to USim In Depth.

Macros

Grid

Defines the simulation grid for USim. An example Grid block is shown below:

<Grid domain>
   kind = cart1d
   ghostLayers = 2
   lower = [0.0]
   upper = [1.0]
   cells = [512]
</Grid>

The common parameters accepted by this updater block are listed below:

kind (string)

All Grid blocks take a string kind that species the type of USim simulation grid. The different kinds of grid available in USim are:

DataStruct

Basic data structure of USim. Updaters perform operations on DataStructs and write out to DataStructs. An example DataStruct block is shown below:

<DataStruct q>
  kind = nodalArray
  onGrid = domain
  numComponents = 9
</DataStruct>

The parameters accepted by this updater block are listed below:

onGrid (string)
All data structures take a string that tells the data structure which grid it is defined on.
writeOut (boolean)
Tells USim whether to write out data from the DataStruct or not.
kind (string)

All DataStruct blocks take a string kind that specifies the type of DataStruct. The different kinds of DataStruct available in USim are:

DataStructAlias

DataStructAlias is a pointer to a DataStruct. The DataStructAlias can be used everywhere a DataStruct can be used. An example DataStructAlias block is shown below:

<DataStructAlias electronDensity>
  kind = nodalArray
  target = q
  componentRange = [0,1]
  writeOut = false
</DataStructAlias>

The parameters accepted by this updater block are listed below:

kind (string)
The kind of DataStruct. This must be nodalArray.
target (string)
The DataStruct that the DataStructAlias is pointing to. DataStructAlias only works with DataStruct of kind = nodalArray
componentRange (integer vector)

The vector must have 2 components. The first component specifies the starting index of DataStruct that the DataStructAlias points to. The second value is the upper limit that the DataStructAlias points to - DataStructAlias can access up to, but not included the index of the second component.

An example follows. Suppose we have the DataStruct

<DataStruct q>
  kind = nodalArray
  onGrid = domain
  numComponents = 9
</DataStruct>

with DataStructAlias

<DataStructAlias electronDensity>
  kind = nodalArray
  target = q
  componentRange = [3,5]
  writeOut = false
</DataStructAlias>

The DataStructAlias points to element 3, 4 of DataStruct.

writeOut (boolean)
Tells USim whether to write out data from the DataStructAlias or not.

UpdateStep

Defines an update step. An update step is a sequence of updaters with a possible synchronization that occurs at the end of the update steps. Synchronization is used in parallel runs for updating ghost cell values along the specified domains. An example UpdateStep code block is given below:

<UpdateStep bcStep>
  updaters = [bcLeft, bcRight, bcTop, bcBottomIon, bcBottomElectron, bcBottomEm]
  syncVars = [qnew]
</UpdateStep>

In this code block all the boundary condition updaters are called then “qnew” is synchronized across MPI barriers. The parameters for this UpdateStep have the following meanings:

updaters (string vector, required)
Defines the list of updaters called in this update step. The updaters are called in the order they are presented in the list.
syncVars (string vector, optional)
Defines a list of nodalArrays that are synchronized accross MPI boundaries at the completion of the update step.
operation (string, optional)
Used in combination with multiUpdater (1d, 2d, 3d) and implicitMultiUpdater (1d, 2d, 3d). Accepted values are integrate or operate. When integrate is used, integration is performed imediately after it is called. When operate is called an operation is performed on the newly integrated values (for each sub step of the runge-kutta method). If operation is not used then the updaters are simply evaluated.

UpdateSequence

Update sequence takes a series of update steps and processes them in order. An example UpdateSequence is shown below:

<UpdateSequence sequence>
  startOnly = [initStep]
  restartOnly = [restoreStep]
  loop = [restrictions, hyperStep, correctionStep, bcStep, copyStep]
  writeOnly = [pressureStep]
</UpdateSequence>

The parameters for this UpdateSequence have the following meanings:

startOnly (string vector)
Defines a list of UpdateSteps to apply only at the beginning of the simulation.
restartOnly (string vector)
Defines a list of UpdateSteps to apply only in the restore phase of a restarted simulation.
loop (string vector)
Defines a list of UpdateSteps that are continually looped over until the simulation completes.
writeOnly (string vector)
Defines a list of UpdateSteps to apply only at data output time.

Updater

Updaters are the fundamental computation infrastructure in USim. Given a set of input data structures, in, an Updater computes a set of output data structures out according to a set of rules defined by the kind of Updater. A simple updater based on a combiner (1d, 2d, 3d) Updater for computing the gas and magnetic pressure of a magnetohydrodynamic plasma is given below:

 <Updater pressCalc>
   kind = combiner1d

   onGrid = domain
# input array
   in = [q]

# ouput data-structures
   out = [pressure]

# labels for components in the input q array
   indVars_q = ["rho", "rhou", "rhov", "rhow", "Er","bx","by","bz", "psi"]

# Adiabatic index, or ratio of specific heats
   gasGamma = $GAS_GAMMA$
# Permeability of free space
   mu0 = $MU0$
   preExprs = ["pr = (gasGamma-1)*(Er - (0.5*(rhou^2+rhov^2+rhow^2)/rho)-\
                     (0.5/mu0)*(bx*bx+by*by+bz*bz))", \
               "pm = (0.5/mu0)*(bx*bx+by*by+bz*bz)" ]
   exprs = ["pr", "pm"]
 </Updater>

The following parameters are common to all Updater blocks:

onGrid (string, required)
All updaters take a string that says which grid the updater is applied to. This grid corresponds to that which the input nodalArray is defined on
kind (string, required)

All updater blocks take a string kind that species the type of updater block.

The following Updater kind attributes can be specified to perform simple operations (initialize, copy, transform) on nodalArray and dynVector data structures:

The following Updater kind attributes can be specified to perform more advanced operations based on pre-defined USim capabilities:

The following Updater kind attributes can be specified to compute finite volume discretizations of a range of vector calculus operators:

The following Updater kind attributes can be specified can be used to compute finite volume discretizations of Navier-Stokes and RANS viscous operators:

The following Updater kind attributes can be specified can be used to compute the generalized Ohm’s law for an ionized plasma:

The following Updater kind attributes can be specified to perform operations related to time advance (time integration, time step restrictions):

The following Updater kind attributes can be specified to perform operations on the grid:

The following Updater kind attributes can be specified to compute output diagnostics from a simulation:

The following Updater kind attributes can be specified to fix unphysical behaviour (e.g. NaN, negative density, pressures) in a simulation:

Time Integrator

Time integrators in USim allow updaters such as multiUpdater (1d, 2d, 3d) and implicitMultiUpdater (1d, 2d, 3d) to discretize partial differential equations in time. USim provides support for total variation diminsighing explicit Runge-Kutta schemes at up to fourth order; super-time-step schemes at first and second order, subcycling methods and implicit discretizations at up to second order.

An example demonstrating an explicit third order Runge-Kutta scheme is below:

<TimeIntegrator rkIntegrator>
  kind = rungeKutta1d
  ongrid = domain
  scheme = third
</TimeIntegrator>

The following parameters are common to all TimeIntegrator blocks:

kind (string, required)

Specifies the time-integration scheme to use: Available options are:

rungeKutta(1d,2d,3d) Specifices explicit Runge Kutta integration methods in 1, 2 or 3 dimensions. Appropriate for hyperbolic problems.

superTimeStep(1d,2d,3d) Specifices explicit super time step integration methods in 1, 2 or 3 dimensions. Appropriate for diffusion problems.

implicit(1d,2d,3d) Specifices implicit integration methods in 1, 2 or 3 dimensions.

onGrid (string, required)
The Grid the time integration is performed on.
scheme (string, required)

The order of the time integration method to use. Available options are:

None Do not integrate in time. Only available for kind = implicit(1d,2d,3d). Used for solving problems that are not discretized in time, e.g. Poisson’s equation.

theta Only available for kind = implicit(1d,2d,3d). Provides an implicit discretization of the form

\[\notag \begin{align} \mathbf{q}^{n+1} - \mathbf{q}^{n} - \Delta t \theta \left[ \nabla\cdot \mathcal{F} \left( \mathbf{w}^{n+1} \right) - \mathcal{S} \left( \mathbf{w}^{n+1} \right) \right] -\Delta t \left[1 - \theta \right] \left[ \nabla\cdot \mathcal{F} \left( \mathbf{w}^{n} \right) - \mathcal{S} \left( \mathbf{w}^{n} \right) \right]` \end{align}\]

Here, \(\theta = 1\) corresponds to backwards Euler, \(\theta = 1/2\) corresponds to Crank-Nicholson and \(\theta = 0\) corresponds to forward Euler. I

zeroth First order subcycling scheme. Only available for kind = superTimeStep(1d,2d,3d).

first First order accurate schemes. Only available for kind = rungeKutta(1d,2d,3d), kind = superTimeStep(1d,2d,3d).

second Second order accurate schemes. Only available for kind = rungeKutta(1d,2d,3d), kind = superTimeStep(1d,2d,3d).

third Third order accurate schemes. Only available for kind = rungeKutta(1d,2d,3d).

fourth Fourth order accurate schemes. Only available for kind = rungeKutta(1d,2d,3d).

timeStepRestrictions (string vector, optional)
List of dynVector that holds the timestep associated with the diffusion operator that forms the right-hand side of the equation. Required if kind = superTimeStep(1d,2d,3d).
theta (float, optional)
Specifies \(\theta\) for implicit discretizations. Required if kind = implicit(1d,2d,3d) and scheme = theta.

Preconditioner

Preconditioner blocks are used in combination with implicitMultiUpdater (1d, 2d, 3d). They allow USim to solve linear systems in an efficient, scalable fashion. An example Preconditioner block is given below

<Preconditioner myPreconditioner>
 preconditioner = ML # None/ML/AztecOO/Ifpack/New Ifpack
 computePreconditioningMatrix = 1 # if 0, use a FD preconditioner
 writePreconditioningMatrixToFile = 0 # write out the preconditioning matrix at startup
 linearMaxPrecAge = 10 # maximum age of preconditioner in outer Newton steps
 linearReusePolicy = Reuse # rebuild, reuse or recompute preconditioner
 stencilUpdater = [computeNablaPhi]
 mlStrategy=classicSA # SA/DD
</Preconditioner>

The following parameters are common to all Preconditioner blocks.

kind (string, required)

Specify the method for computing the matrix for preconditioning the linear system. Available options are:

preconditioner(1,2,3)d With this choice, USim computes the matrix through the stencil supplied by a single updater specied by the stencilUpdater parameter. This option is useful when the operator to be solved has a simple signature (e.g. the Laplacian \(\nabla^2\))

autoPreconditioner(1,2,3)d With this choice, USim uses an efficient finite difference method to compute the matrix for the system of equations specified by the UpdateSequence block in the implicitMultiUpdater (1d, 2d, 3d). This option is useful for systems that solve multiphysics problems.

preconditioner (string, required)
Options are None, ML, AztecOO, Ifpack and New Ifpack. ML (Multi-Level) preconditioners are the preferred option for USim due to the highly anisotropic nature of the matrix produced by USim operators. These preconditioner are based on the ML package (https://trilinos.org/packages/ml/). Other options include preconditioners based on the AztecOO package (https://trilinos.org/packages/aztecoo/) and Ifpack (https://trilinos.org/packages/ifpack/)
computePreconditioningMatrix (int, required)
If computePreconditioningMatrix = 1, then compute a matrix based on a user-specified updater (if kind = preconditioner(1,2,3)d) or using an efficient finite difference method (if kind = autoPreconditioner(1,2,3)d. If computePreconditioningMatrix = 0, then the matrix is determined using a (slow) finite-difference computation. This latter option, allows for debugging the system of equations.
writePreconditioningMatrixToFile (int, required)
If writePreconditioningMatrixToFile = 1, then the matrix used to precondition the non-linear problem is written out each time it is filled in Matrix Market format. This option is expensive, both in terms of simulation time and storage space and so it is recommended that writePreconditioningMatrixToFile = 0 except if needing to debug the simulation.
stencilUpdater (string vector, optional)
Tell the solver which updater to compute the matrix to use as a preconditioner. Required if kind = preconditioner(1,2,3)d and computePreconditioningMatrix = 1. Currently, only accepts one entry.
linearMaxPrecAge (int, required)
The number of outer Newton steps to take between each update of the preconditioner. Determining this value is problem dependent and requires careful experimentation by the user.

The following options are available if preconditioner = ML:

testPreconditioner (bool)
Test the ability of the preconditioner to invert the matrix
testSmoother (bool)
Test the ability of the range of smoothers available in ML to invert the matrix.
mlStrategy (string)

Determines whether or not to use smoothed aggregation or domain decomposition for the multi-level solver. Available options are:

SA Specify smoothed aggregation methods.

DD Specify domain decomposition methods.

classicSA Specify smoothed aggregation methods appropriate for diffusion-type problems.

classicDD Specify domain decomposition methods appropriate for diffusion-type problems.

mlSmoother (string)

Specify the smoother strategy used to compute the ML hierarcy when Options include:

Jacobi

block Gauss-Seidel

symmetric Gauss-Seidel

BSGS-A

BSGS-E

The choice of smoother is best determined for a given problem by first running the problem with testPreconditioner = true and testSmoother = true. This combination of options will provide information about the ability of the different mlSmoother options to solve the matrix. The mlSmoother option can then be set appropriately and the testPreconditioner, testSmoother options can be set to false in order to improve efficiency.

mlNumPDE (int, optional)
Specify the number of PDE’s represented in the matrix. Typically, this option should match the number of components for the input nodalArray input to the implicitMultiUpdater (1d, 2d, 3d).

The following subblocks can be supplied to the preconditioner:

ParameterList
A ParameterList block can be supplied to any preconditioner block. The ParameterList block should contain options accepted by the Trilinos preconditioner specified by the preconditioner string parameter, documented at https://trilinos.org/packages/ml/, https://trilinos.org/packages/aztecoo/) and https://trilinos.org/packages/ifpack/

Hyperbolic Equations

An Equation block that describes a hyperbolic conservation law of the form:

\[\notag \begin{align} \frac{\partial \mathbf{q}}{\partial t} + \nabla\cdot\left[ \mathcal{F} \left( \mathbf{w} \right) \right] = 0 \end{align}\]

where \(\mathbf{q}\) is a vector of conserved variables (e.g. density, momentum, total energy), \(\mathcal{F}\left( \mathbf{w} \right)\) is a non-linear flux tensor computed from a vector of primitive variables, (e.g. density, velocity, pressure), \(\mathbf{w} = \mathbf{w}(\mathbf{q})\). The choice of hyperbolic equation defines \(\mathbf{q}\), \(\mathcal{F}\left( \mathbf{w} \right)\), \(\mathbf{w} =\mathbf{w}(\mathbf{q})\), along with the eigensystem associated with \(\mathcal{F}\left( \mathbf{w} \right)\).

An Equation block is owned by an updater (e.g. classicMusclUpdater (1d, 2d, 3d)). The updater that owns the Equation sets the input, output and any additional data structures that are required by the Equation system.

The following parameters are common to all Equation blocks:

kind (string)

All Equation blocks take a string kind that species the type of hyperbolic equation. The following equations can be used to simulate neutral plasmas:

The following equations can be used to simulate ionized, quasi-neutral plasmas in the magnetohydrodynamic limit:

The following equations can be used to simulate Maxwell’s equations and non-neutral plasmas:

The following equation can be used to implement a hyperbolic equation system at the input file level:

Algebraic Equations

A Source or Equation block in USim that defines a local non-linear algebraic transformation of a set of input nodalArrays, \(\mathbf{q}_\mathrm{Input}\) into a single output nodalArray through:

\[\notag \begin{align} \mathbf{q}_\mathrm{Output} = \mathcal{S} \left( \mathbf{q}_\mathrm{Input}, x, y, z, t \right) \end{align}\]

where \(\mathcal{S} \left( \mathbf{q}_\mathrm{Input}, x, y, z, t \right)\) represents a non-linear algebraic transformation that is applied locally, i.e. \(\mathcal{S} \left( \mathbf{q}_\mathrm{Input}, x, y, z, t \right)\) only depends on the data in an indiviudal element in the Grid and not on elements adjacent to that element.

Source and Equation blocks can be used for a range of purposes in USim. One particular example is the addition of terms to the right-hand side of a hyperbolic equation system

\[\notag \begin{align} \frac{\partial \mathbf{q}}{\partial t} + \nabla\cdot\left[ \mathcal{F} \left( \mathbf{w} \right) \right] = \mathcal{S} \left( \mathbf{w}, x, y, z, t \right) \end{align}\]

A specific example of a source block that can be used in this way is the exprHyperSrc to apply a gravitational acceleration to a neutral fluid:

<Source gravity>
  kind = exprHyperSrc
  gravity = GRAVITY
  indVars = ["rho", "rhou", "rhov", "rhow", "Er"]
  exprs = ["0.0", "0.0", "-rho*gravity", "0.0", "-gravity*rhov"]
</Source>

Note

Any kind listed below can be used as an Equation block in the localOdeIntegrator (1d, 2d, 3d) Updater or the equation (1d, 2d, 3d) Updater.

Note

The firstOrderMusclUpdater (1d, 2d, 3d), classicMusclUpdater (1d, 2d, 3d), unstructMusclUpdater (1d, 2d, 3d), and thirdOrderMusclUpdater (1d, 2d, 3d) Updaters are the only updaters that use the following kinds as Source blocks.

Note

None of the kinds listed below can be used as Equation blocks in the muscl updaters. The Equation blocks in the muscle updaters are Hyperbolic Equations

The following parameters are common to all Source blocks:

kind (string)

All Source and Equation blocks take a string kind that specifies the type of source.

The following kinds can be combined with Hyperbolic Equations to enable the use of curvilinear coordinates for hyperbolic problems:

The following kinds can be combined with Hyperbolic Equations to enable additional physics in hyperbolic problems:

The following kinds can be used to couple fluid models with equations of state:

The following kinds can be used to couple fluid models with radiation models:

The following kinds can be used to couple fluid systems with electromagnetic systems:

The following kinds can be used to control divergence errors in electromagnetic problems:

The following kinds can be used for coupling together multi-species fluid models:

Boundary Conditions

Defines an Updater block that is only applied to the boundary of the domain. Modified boundary values are stored in out. An example boundary condition updater block is given below:

<Updater Bc>
   kind = copy2d
   onGrid = domain
   entity = ghost
   out = [q]
</Updater>

The following parameters are common to all Boundary Condition blocks:

in (string vector)
All boundary conditions have the option to take a string vector of input DataStruct. These DataStructs may or may not be used by the boundary condition
out (string vector)
All boundary conditions take an output dataStruct.
onGrid (string)
All boundary conditions take a string that tells the boundary condition which grid it is applied to
entity (string)

All boundary conditions (except the periodicBc) take an entity that tells the updater what boundary the boundary condition will be applied to.

the entity ghost represents all boundaries for all USim grid types

the entities left (lower x boundary) right (upper x boundary) bottom (lower y boundary) top (upper y boundary) back (lower z boundary) front (upper z boundary) are defined for ntBodyFitted and cart grids.

kind (string)

All boundary condition blocks take a string kind that species the type of boundary condtion. The different kinds of boundary condition available in USim are:

Time Step Restriction

Computes a minimum time step based on physical quantities, grid quantities and time. It could be used to determine the maximum explicitly stable time step based on wave speeds, or the maximum time step based on oscillations like the electron plasma oscillation. The TimeStepRestriction is used in conjunction with timeStepRestrictionUpdater (1d, 2d, 3d). An example TimeStepRestriction is shown below:

<TimeStepRestriction wpe>
  kind = plasmaFrequency
  speciesCharge = ELECTRON_CHARGE
  speciesMass = ELECTRON_MASS
  epsilon0 = 1.0
  massDensityIndex = 0
</TimeStepRestriction>

The following parameters are common to all TimeStepRestriction blocks:

in (string vector, optional)
Specifies the nodalArrays within the in attribute for the timeStepRestrictionUpdater (1d, 2d, 3d) that should be used for computing this time step restriction.
includeInTimeStep (bool, optional)
Whether to include this time step restriction in the time step returned by the timeStepRestrictionUpdater (1d, 2d, 3d). Default true.
storeTimeStep (bool, optional)
Whether to store this time step restriction in the timeSteps dynVector specified in the timeStepRestrictionUpdater (1d, 2d, 3d). Default: true.
storeWaveSpeed (bool, optional)
Whether to store the wave speed associated with this in the waveSpeeds dynVector specified in the timeStepRestrictionUpdater (1d, 2d, 3d). Default: true.
applyCFLRestriction (bool, optional)
Whether to apply the CFL condition specified in the timeStepRestrictionUpdater (1d, 2d, 3d) to the time step computed in this restriction. Default: true.
kind (string, required)

All TimeStepRestriction blocks take a string kind that species the type of time step restriction. The remainder of this section describes the different options for this parameter that are available in USim.

Multi-Species Data Files

Multi-species data such as reaction rate constants, specific heats, atomic data etc can be supplied to USim using an ASCII text file. Each data file can contain the following options:

REACTIONS chemical reactions

CP specific heat at constant pressure

EOF standard energy of formation

MOLECULARWEIGHT molecular weight

MOLECULARDIA molecular diameter

DOF degrees of freedom of a gas molecule

Not all properties need to be included with every file. Data associated with each property is enclosed between lines labelled ‘<PROPERTY> START’ and ‘<PROPERTY> END’, where <PROPERTY> is replaced with one of the above list.

Multi-Species Chemical Reactions

An example multi-species reaction block that demonstrates a range of reaction types for mult-species chemistry is given below:

REACTIONS START
SPECIES N2 N O2 O NO
2 2 F 1.0E-8 0.0 N2 O2 NO NO
2 2 A 300.0 11000.0 6.43E-18  1.0E+0  3.16E+4 1.58E-8 1.0E+0 1.64E+5  N O2 NO O
2 2 E 300.0 12000.0 4.0E-9 0.0 0.0 2.0 5 0.0 0.0 0.0 0.0 0.0 N2 O NO N
REACTIONS END

This reactions block demonstrates chemical reactions involving 5 species: N2 N O2 O NO, denoted by the second line in the example: SPECIES N2 N O2 O NO. Note that each specie is delimited by a space. The next three lines of the example (lines 3 - 5) describe the chemical reactions involving these species, one chemical reaction per line. Data describing the chemical reaction is space delimited. All chemical reactions supported by USim use the following pattern on one line to describe the reaction properties

Num_LHS Num_RHS Type Parameters LHS_Species RHS_Species

where

  • Num_LHS = Number of species on LHS
  • Num_RHS = Number of species on RHS
  • Type = Reaction Type
  • Parameters = Reaction Parameters
  • LHS_Species = LHS species list
  • RHS_Species = RHS species list

In the example above, each reaction has

Num_LHS = 2
Num_RHS = 2

The third parameter, Type = F,A,E denotes the type of chemical reaction and determines what entries are necessary in Parameters. The final two entiries on the line list the species on the left-hand side and right-hand sides of the reaction respectively. The above example demonstrates the three types of chemical reactions that it is possible to include in a USim simulation, which are:

Fixed rate reactions; Type = F

Fixed rate reactions are demonstrated on line 3 of the example. In this case, we are demonstrating the system:

Reaction: \(N_2 + O_2 \rightleftharpoons 2NO\);

Foward Rate Constant: \(k_{f} = 10^{-8}\);

Backward Rate Constant: \(k_{b} = 0.0\)

The data format for fixed rate reactions is as follows (on one line):

Num_LHS Num_RHS Type Forward_A Backward_A LHS_Species RHS_Species

In the example above these are set as:

Num_LHS = 2
Num_RHS = 2
Type = F
Forward_A = 1.0E-8
Backward_A = 0.0
LHS_Species = N2 O2
RHS_Species = NO NO
Arrhenius-type Chemical Reactions; Type = A;

Arrhenius-type reactions are demonstrated on line 4 of the example. In this case, we are demonstrating the system:

Reaction: \(N + O_2 \rightleftharpoons NO + O\);

Forward Rate Constant: \(k_{f} = A \left(\frac{T}{298} \right)^n e^{\left(\frac{-E_{a}}{RT}\right)}\);

Backward Rate Constant: \(k_{b} = A \left(\frac{T}{298} \right)^n e^{\left(\frac{-E_{a}}{RT}\right)}\)

Arrhenius-type reactions are valid over a temperature range, \(T_{min} < T < T_{max}\) which must be specified. The data format for Arrhenius-type reactions is as follows (on one line):

Num_LHS Num_RHS Type T_min T_max \
  Forward_A Forward_n Forward_Ea \
  Backward_A Backward_n Backward_Ez \
  LHS_Species RHS_Species

In the example above, these are set as:

Num_LHS = 2
Num_RHS = 2
Type = A
T_min = 300.0
T_max = 11000.0
Forward_A = 6.43E-18
Forward_n = 1.0E+0
Forward_Ea = 3.16E+4
Backward_A = 1.58E-8
Backward_n = 1.0E+0
Backward_Ea = 1.64E+5
LHS_Species = N2 O
RHS_Species = NO N
Arrhenius-type Chemical Reactions with Equilibriation; Type = E

Arrhenius-type reactions with equilibriation are demonstrated on line 5 of the example. In this case, we are demonstrating the system:

\(N_2 + O \rightleftharpoons NO + N\)

Forward Rate Constant \(k_{f} = A \left(\frac{T}{298} \right)^n e^{\left(\frac{-Ea}{RT}\right)}\)

Equilibrium Rate Constant \(k_{e} = B e^{\left(\sum\limits_{i=1}^{m} c_{i}\left(\frac{10000}{T}\right)^i\right)}\)

Backward Rate Constant \(k_{b} = k_{f}/k_{e}\)

This system of reactions are valid over a temperature range, \(T_{min} < T < T_{max}\) which must be specified. USim automatically derives the backward rate constant based on the forward and equilibrium rate constants. The data format for Arrhenius-type reactions with equilibriation is as follows (on one line):

Num_LHS Num_RHS Type T_min T_max \
   Forward_A Forward_n Forward_Ea \
   Equilib_B Equilib_m Equilib_c1 Equilib_c2 ... Equilib_cm \
   LHS_Species RHS_Species

Note that Equilib_m sets the number of entries Equilib_c1 .... Equilib_cm. In the example above, these are set as:

Num_LHS = 2
Num_RHS = 2
Type = E
T_min = 300.0
T_max = 12000.0
Forward_A = 4.0E-9
Forward_n = 0.0E+0
Forward_Ea = 0.0E0
Equilib_B = 2.0
Equilib_m = 5
Equilib_c1 = 0.0
Equilib_c2 = 0.0
Equilib_c3 = 0.0
Equilib_c4 = 0.0
Equilib_c5 = 0.0
LHS_Species = N O2
RHS_Species = NO O

Multi-Species Specific Heat At Constant Pressure

An example multi-species specific heat at constant pressure block is given below:

CP START
SPECIES N2 N O2 O NO
1 100.0 500.0 5 28.98641 1.853978 -9.647459 16.63537 0.000117
1 298.0 6000.0 5 21.13 -0.388 0.04 0.02 -0.025
3 100.0 700.0 5 31.32 -20.23 57.86 -36.50 -0.0073 700.0 2000.0 5 30.0 8.77 -3.988 \
                         0.788 -0.7415 2000.0 6000.0 5 20.91 10.72 -2.02 0.14 9.2
1 298.0 6000.0 5 21.13 -0.388 0.04 0.02 -0.025
2 298.0 1200.0 5 23.83 12.58 -1.139 -1.497 0.214 1200.0 6000.0 5 35.99 0.95 -0.148 \
                                                                       0.0099 -3.0
CP END

This block demonstrates specific heat at constant pressure for 5 species: N2 N O2 O NO, denoted by the second line in the example: SPECIES N2 N O2 O NO. Note that each specie is delimited by a space. The specific heat data of each of the species is entered in a separate line in the same order as that of the species list. Data for each species should be entered on a single line, but has been formatted here for ease of viewing. USim species the specific heat at constant pressure using Shomate polynomials defined in multiple temperature ranges according to:

\(C_p = a_0 + a_1 t + a_2 t^2 + a_3 t^3 + \frac{a_4}{t^2}\), where \(t = T/1000\).

The polynomials are specified through the data format:

<Number-of-polynomials> {Polynomial1-parameters} {Polynomial2-parameters} .... \
                                                      {PolynomialN-parameters}

where each of the N <Number-of-polynomals> are specified through {PolynomialN-parameters}:

<Temperature-range-lower-limitN> <Temperature-range-upper-limitN> \
  <Number-coefficients-in-polynomialN> <polynomialN-coefficients>

In line 3 of the above example, \(C_{p,N_2}\) is specified using a single polynomial in the temperature range [100,500] K using

<Number-of-polynomials> = 1
<Temperature-range-lower-limit> = 100.0
<Temperature-range-upper-limit> = 500.0
<Number-coefficients-in-polynomial1> = 5
<polynomial1-coefficient1> = 28.98641
<polynomial1-coefficient2> = 1.853978
<polynomial1-coefficient3> = -9.647459
<polynomial1-coefficient4> = 16.63537
<polynomial1-coefficient5> = 0.000117

In line 7 of the above example, \(C_{p,NO}\) is specified using two polynomials in the temperature ranges [298,1200] and (1200,6000] K using:

<Number-of-polynomials> = 2
<Temperature-range-lower-limit1> = 298.0
<Temperature-range-upper-limit1> = 1200.0
<Number-coefficients-in-polynomial1> = 5
<polynomial1-coefficient1> = 23.83
<polynomial1-coefficient2> = 12.58
<polynomial1-coefficient3> = -1.139
<polynomial1-coefficient4> = -1.497
<polynomial1-coefficient5> = 0.214
<Temperature-range-lower-limit2> = 1200.0
<Temperature-range-upper-limit2> = 6000.0
<Number-coefficients-in-polynomial2> = 5
<polynomial2-coefficient1> = 35.99
<polynomial2-coefficient2> = 0.95
<polynomial2-coefficient3> = -0.148
<polynomial2-coefficient4> = 0.0099
<polynomial1-coefficient5> = -3.0

Multi-Species Energy of Formation, Molecular Weight, Molecular Diameter and Degrees of Freedom

Each of the above mentioned properties are constant and hence share the same block format with the corresponding starting and ending lines. The example below is for molecular weight data. Block header ‘MOLECULARWEIGHT START’ is followed by list of species ‘SPECIES N2 N O2 O NO’. Each of the species is delimited by space. The next line has the molecular weights entered in the same order as that of the species list. The block is closed with ‘MOLECULARWEIGHT END’.

MOLECULARWEIGHT START
SPECIES N2 N O2 O NO
28.0 14.0 32.0 16.0 30.0
MOLECULARWEIGHT END