Input Files

A set of classes for specifying input parameters for the Ember solver.

Create a Config object to be passed to run() or multirun(). Sane defaults are given for most input parameters. Create a customized configuration by passing Options objects to the constructor for Config:

conf = Config(
    Paths(outputDir="somewhere"),
    InitialCondition(equivalenceRatio=0.9))

Configuration Options

class ember.input.Paths(**kwargs)

Directories for input and output files

outputDir = 'run/test1'

Relative path to the directory where output files (outNNNNNN.h5, profNNNNNN.h5) will be stored. Automatically created if it doesn’t already exist.

logFile = None

File to use for log messages. If None, write output to stdout

class ember.input.General(**kwargs)

High-level configuration options

fixedBurnedVal = None

True if the temperature and mass fractions on the burned gas side of the flame should be held constant. Applicable only to premixed flames. The default is True for twin or curved flames with burned gas at x=0, and False otherwise.

fixedLeftLocation = False

True if the position of the leftmost grid point should be held constant. Should usually be True for Twin and Curved flame configurations.

flameGeometry = 'planar'

Geometry specification for the flame. Options are: ‘planar’, ‘cylindrical’, and ‘disc.’

twinFlame = False

True if solving a planar flame that is symmetric about the x = 0 plane.

interpFile = None

Input file (HDF5 format) containing the interpolation data needed for the quasi2d mode. Contains:

• vector r (length N)

• vector z (length M)

• Temperature array T (size N x M)

• radial velocity array vr (size N x M)

• axial velocity array vz (size N x M)

unburnedLeft = True

True if the unburned fuel/air mixture should be used as the left boundary condition. Applicable only to premixed flames.

fuelLeft = True

True if the fuel mixture should be used as the left boundary condition. Applicable only to diffusion flames.

continuityBC = 'fixedLeft'

Method for setting the boundary condition for the continuity equation Valid options are: fixedLeft, fixedRight, fixedQdot, fixedTemperature, and stagnationPoint. The fixedTemperature condition holds the location where the midpoint temperature is reached constant, while the other options fix the value of V at the specified point.

chemistryIntegrator = 'qss'

Integrator to use for the chemical source terms. Choices are qss (explicit, quasi-steady state) and cvode (implicit, variable-order BDF).

splittingMethod = 'balanced'

Method to use for splitting the convection / diffusion / reaction terms. Options are strang and balanced.

errorStopCount = 100

Number of integration failures to tolerate in the chemistry integrator before aborting.

nThreads = 1

Number of threads to use for evaluating terms in parallel

chebyshevOrder = 5

Order of Chebyshev polynomial to use in approximating input functions over a single global time step.

class ember.input.Chemistry(**kwargs)

Settings pertaining to the Cantera mechanism file

mechanismFile = 'gri30.yaml'

Path to the Cantera mechanism file in XML format

phaseID = ''

ID of the phase to use in the mechanism file. Found on a line that looks like:

<phase dim="3" id="gas">

in the mechanism file. This is always “gas” for mechanisms converted using ck2cti and cti2ctml. This option only needs to be specified if the desired phase is not the first phase defined in the input file.

transportModel = 'Approx'

Transport model to use. Valid options are Mix, Multi, UnityLewis, and Approx

kineticsModel = 'interp'

Kinetics model to use. Valid options are standard and interp.

threshold = 1e-05

Mole fraction threshold for including species with transportModel = "Approx"

rateMultiplierFunction = None

Set a scalar multiplier for the reaction rate term as a function time

class ember.input.Grid(**kwargs)

Parameters controlling the adaptive grid

vtol = 0.12

Maximum relative scalar variation of each state vector component between consecutive grid points. For high accuracy, vtol = 0.08; For minimal accuracy, vtol = 0.20.

dvtol = 0.2

Maximum relative variation of the gradient of each state vector component between consecutive grid points. For high accuracy, dvtol = 0.12; For minimal accuracy, dvtol = 0.4.

rmTol = 0.6

Relative tolerance (compared to vtol and dvtol) for grid point removal.

dampConst = 7

Parameter to limit numerical diffusion in regions with high convective velocities.

gridMin = 5e-07

Minimum grid spacing [m]

gridMax = 0.0002

Maximum grid spacing [m]

uniformityTol = 2.5

Maximum ratio of the distances between adjacent pairs of grid points.

\[\frac{1}{\tt uniformityTol} < \frac{x_{j+1}-x_j}{x_j-x_{j-1}} < {\tt uniformityTol}\]

absvtol = 1e-08

State vector components smaller than this value are not considered whether to add or remove a grid point.

boundaryTol = 5e-05

Tolerance for each state vector component for extending the domain to satisfy zero-gradient conditions at the left and right boundaries.

boundaryTolRm = 1e-05

Tolerance for removing points at the boundary. Must be smaller than boundaryTol.

unstrainedDownstreamWidth = 5

For unstrained flames, number of flame thicknesses (based on reaction zone width) downstream of the flame to keep the right edge of the domain.

addPointCount = 3

Number of points to add when extending a boundary to satisfy boundaryTol.

centerGridMin = 0.0001

For curved or twin flames, the minimum position of the first grid point past x = 0.

class ember.input.InitialCondition(**kwargs)

Settings controlling the initial condition for the integrator. If no restartFile is specified, an initial profile is created based on the specified fuel and oxidizer compositions.

If an input file is specified, then setting fuel and oxidizer compositions will cause new values to be used only at the boundaries of the domain.

The grid parameters are only used if no restart file is specified.

restartFile = None

Read initial profiles from the specified file, or if ‘None’, create a new initial profile.

flameType = 'premixed'

“premixed”, “diffusion”, or “quasi2d”

Tu = 300

Temperature of the unburned fuel/air mixture for premixed flames [K].

Tfuel = 300

Temperature of the fuel mixture for diffusion flames [K].

Toxidizer = 300

Temperature of the oxidizer mixture for diffusion flames [K].

fuel = 'CH4:1.0'

Molar composition of the fuel mixture.

oxidizer = 'N2:3.76, O2:1.0'

Molar composition of the oxidizer mixture.

equivalenceRatio = 0.75

Equivalence ratio of the fuel/air mixture for premixed flames.

reactants = None

Molar composition of the fuel + oxidizer mixture. Specify as an alternative to providing fuel and oxidizer compositions and equivalence ratio.

counterflow = None

Molar composition of the flow opposite the premixed reactant stream, if different from the equilibrium composition

Tcounterflow = None

Temperature of the flow opposite the premixed reactant stream, if different from the equilibrium temperature

equilibrateCounterflow = 'TP'

Adjust the composition of the counterflow stream so that the components are at equilibrium. This option specifies the property pair to hold constant during equilibration, or False to skip equilibration. The boundary condition is not consistent if this mixture has reactions that are proceeding at finite rates. For diffusion flames, this option is applied to the state of the oxidizer stream.

pressure = 101325

Thermodynamic pressure [Pa]

nPoints = 100

Number of points in the initial uniform grid.

xLeft = -0.002

Position of the leftmost point of the initial grid.

xRight = 0.002

Position of the rightmost point of the initial grid.

centerWidth = 0.001

The width of the central plateau in the initial profile [m]. For premixed flames, this mixture is composed of equilibrium products. For diffusion flames, this mixture is composed of a stoichiometric fuel/air brought to equilibrium at constant enthalpy and pressure.

slopeWidth = 0.0005

The width of the slope away from the central plateau in the initial profile [m]. Recommended value for premixed flames: 5e-4. Recommended value for diffusion flames: 1e-3.

smoothCount = 4

Number of times to run the generated profile through a low pass filter before starting the simulation.

haveProfiles = False

True if initial profiles for x,T,U,V and Y are given

x = None

Initial grid used if haveProfiles is set to True

T = None

Initial temperature profile used if haveProfiles is set to True

U = None

Initial tangential velocity gradient profile used if haveProfiles is set to True

Y = None

Initial mass fraction profiles used if haveProfiles is set to True

V = None

Initial mass flux profile used if haveProfiles is set to True

class ember.input.WallFlux(**kwargs)

Tinf = 300

Reference temperature for the wall heat flux

Kwall = 100

Conductance of the wall [W/m^2-K]

class ember.input.Ignition(**kwargs)

Parameters for an artificial heat release rate function which can be used to simulate ignition. The heat release rate is a step function in time with a Gaussian spatial distribution.

tStart = 0

Beginning of the external heat release rate pulse [s].

duration = 0.001

Duration of the external heat release rate pulse [s].

energy = 0

Integral amplitude of the pulse [W/m^2].

center = 0

Location of the center of the pulse [m].

stddev = 0.0001

Characteristic width (standard deviation) of the pulse [m].

class ember.input.StrainParameters(**kwargs)

Parameters defining the strain rate as a function of time.

The strain rate changes linearly from initial to final over a period of dt seconds, starting at tStart.

initial = 400

Initial strain rate [1/s]

final = 400

final strain rate [1/s]

tStart = 0.0

time at which strain rate starts to change [s]

dt = 0.002

time period over which strain rate changes [s]

rates = None

A list of strain rates to use for a series of sequential integration periods (see multirun()), with steady-state profiles generated for each strain rate before proceeding to the next. A typical list of strain rates to use:

rates = [9216, 7680, 6144, 4608, 3840, 3072, 2304, 1920, 1536,
         1152, 960, 768, 576, 480, 384, 288, 240, 192, 144, 120,
         96, 72, 60, 48, 36, 30, 24, 18, 15, 12]

class ember.input.PositionControl(**kwargs)

Parameters defining the position of the flame as a function of time (for twin / curved flames).

These parameters are used to adjust the mass flux at r = 0 to move the flame toward the desired location. The flame moves from xInitial to xFinal over dt seconds, starting at tStart.

The feedback controller which determines the mass flux uses the distance between the current flame location and the desired flame location with the gains specified by proportionalGain and integralGain.

xInitial = 0.0025

xFinal = 0.0025

dt = 0.01

tStart = 0

proportionalGain = 10

integralGain = 800

class ember.input.Times(**kwargs)

Paremeters controlling integrator timesteps and frequency of output profiles.

tStart = 0

Integrator start time.

globalTimestep = 2e-05

Timestep used for operator splitting.

diffusionTimestepMultiplier = 10

Control for timestep used by the diffusion integrator. Actual timestep will be this multiplier times the stability limit an explicit integrator.

regridTimeInterval = 100

Maximum amount of time before regridding / adaptation.

regridStepInterval = 20

Maximum number of timesteps before regridding / adaptation.

outputStepInterval = 1

Maximum number of steps between storing integral flame properties.

outputTimeInterval = 1e-05

Maximum time between storing integral flame properties.

profileStepInterval = 1000

Maximum number of timesteps before writing flame profiles.

profileTimeInterval = 0.001

Maximum time between writing flame profiles.

currentStateStepInterval = 20

Number of timesteps between writing profNow.h5

terminateStepInterval = 10

Number of timesteps between checks of the steady-state termination conditions.

class ember.input.CvodeTolerances(**kwargs)

Tolerances for the CVODE chemistry integrator

relativeTolerance = 1e-06

Relative tolerance for each state variable

momentumAbsTol = 1e-07

Absolute tolerance for U velocity

energyAbsTol = 1e-08

Absolute tolerance for T

speciesAbsTol = 1e-13

Absolute tolerance for species mass fractions.

minimumTimestep = 1e-18

Minimum internal timestep

class ember.input.QssTolerances(**kwargs)

Tolerances for the QSS chemistry integrator

epsmin = 0.02

Accuracy parameter for determining the next timestep.

epsmax = 10.0

Accuracy parameter for repeating timesteps

dtmin = 1e-16

Minimum internal timestep

dtmax = 1e-06

Maximum internal timestep

iterationCount = 1

Number of corrector iterations per timestep.

abstol = 1e-11

Absolute threshold for including each component in the accuracy tests.

minval = 1e-60

Lower limit on the value of each state vector component.

stabilityCheck = False

Enable convergence-based stability check on timestep. Not enabled unless iterationCount >= 3.

class ember.input.Debug(**kwargs)

Control of verbose debugging output

adaptation = False

Addition / removal of internal grid points.

regridding = True

Addition / removal of boundary grid points.

timesteps = True

Print current time after each global timestep.

veryVerbose = False

Enable extensive timestep debugging output. Automatically enabled for debug builds.

flameRadiusControl = False

Print information about the flame radius feedback controller.

sourcePoint = -1

Grid point to print debugging information about at sourceTime.

sourceTime = 0.0

Time at which to print extensive debugging information about the source term at j = sourcePoint, then terminate.

startTime = 0.0

Time at which to start saving intermediate integrator profiles when OutputFiles.debugIntegratorStages is True

stopTime = 100.0

Time at which to stop saving intermediate integrator profiles when OutputFiles.debugIntegratorStages is True

class ember.input.OutputFiles(**kwargs)

Control the contents of the periodic output files

fileExtension = 'npz'

File extension of the output files. ‘h5’ for HDF5 files, which require the ‘h5py’ Python module and can be read by other programs, or ‘npz’ for a compressed NumPy data structure.

heatReleaseRate = True

Include the heat release rate as a function of space

timeDerivatives = True

Include the reaction / diffusion / convection contributions to the net time derivative of each state variable

extraVariables = False

Include variables such as transport properties and grid parameters that can be recomputed from the state variables.

auxiliaryVariables = False

Include other miscellaneous variables

firstFileNumber = 0

Used to generate a continuous sequence of output files after restarting the code.

saveProfiles = True

Generate profNNNNNN.h5 files

debugIntegratorStages = False

Write profiles after each stage of the split integrator.

stateWriter = <class 'ember.output.StateWriter'>

Class used to write periodic output files (e.g. profNNNNNN.h5)

timeSeriesWriter = <class 'ember.output.TimeSeriesWriter'>

Class used to write time-series files (e.g. out.h5)

class ember.input.TerminationCondition(**kwargs)

Integrate until either tEnd is reached or a criterion based on measurement is satisfied. The measurement-based check is not enabled until tMin is reached.

• If measurement == None, integration will proceed to tEnd.

• If measurement == 'Q', integration will terminate when the the heat release rate reaches a steady-state value to within tolerance (RMS) over a time period of steadyPeriod, or the mean heat release rate over steadyPeriod is less than abstol.

• If measurement == 'dTdt', integration will terminate when ||1/T * dT/dt|| / sqrt(nPoints) is less than dTdtTol.

tEnd = 0.8

measurement = 'Q'

tolerance = 0.0001

abstol = 0.5

steadyPeriod = 0.002

tMin = 0.0

dTdtTol = 10.0

Implementation Classes

These classes are used to define configurable options.

class ember.input.Options(**kwargs)

Base class for elements of Config

isSet(option)

Returns True if the named option has a user-specified value

class ember.input.Config(*args)

An object consisting of a set of Options objects which define a complete set of configuration options needed to run the flame solver.

checkRateConstants(gas, T)

A function for finding reactions with suspiciously high rate constants at low temperatures.

run(command=None)

Run the simulation using the parameters set in this Config.

If a list strain rates is provided by the field strainParameters.rates, a sequence of flame simulations at the given strain rates will be run. Otherwise, a single simulation will be run.

If the script which calls this function is passed the argument validate, then the configuration will be checked for errors and the script will exit without running the simulation.

runESR(command=None)

Run an extinction strain rate simulation using the parameters set in this Config.

The strain rate parameter will be increased until a steady burning flame can no longer be achieved.

If the script which calls this function is passed the argument validate, then the configuration will be checked for errors and the script will exit without running the simulation.

class ember.input.Option(default, choices=None, min=None, max=None, nullable=False, label=None, level=0, filter=None)

Instances of this class are used as class members of descendants of class Options to represent a single configurable value. When a user-specified value for an option is specified (as a keyword argument to the constructor of a class derived from Options), that value is stored in this object and validated to make sure it satisfies any applicable constraints.

Parameters:

• default – The default value for this option

• choices – A sequence of valid values for this option, e.g. ['Mix', 'Multi']. The default choice is automatically included in choices.

• min – The minimum valid value for this option

• max – The maximum valid value for this option

• nullable – Set to True if None is a valid value for this option, regardless of any other restrictions. Automatically set to True if default is None.

• label – A human readable label to be used in the GUI in place of the attribute name to which this Option is assigned.

• level – A number from 0-3 indicating the obscurity level of this option. Used to selectively hide advanced options in the GUI. 0 is always shown. 3 is never shown.

• filter – A function that takes a Config object as an argument and returns True if this option should be enabled

Requiring values of a particular type is done by using one of the derived classes: StringOption, BoolOption, IntegerOption, FloatOption.

class ember.input.StringOption(default, choices=None, min=None, max=None, nullable=False, label=None, level=0, filter=None)

An option whose value must be a string.

class ember.input.BoolOption(default, choices=None, min=None, max=None, nullable=False, label=None, level=0, filter=None)

An option whose value must be a boolean value.

class ember.input.IntegerOption(default, choices=None, min=None, max=None, nullable=False, label=None, level=0, filter=None)

An option whose value must be a integer.

class ember.input.FloatOption(default, choices=None, min=None, max=None, nullable=False, label=None, level=0, filter=None)

An option whose value must be a floating point number.