Usage

Once installed, pyMARS can be run as an executable. Change to the directory where your input files are located, then run:

pymars [options]

The following options are available, and can also be seen by using the -h or --help option:

-h, --help:
   show this help message and exit
-i, --input:
   YAML file with reduction inputs
--path:
   Path to directory for writing files
--num_threads:
   Number of CPU cores to use for running simulations in parallel.
   If no number, then use available number of cores minus 1.
--convert:
   Convert files between Cantera and Chemkin formats (.yaml <=> .inp)
--thermo:
   thermodynamic data filename (only necessary for Chemkin files)
--transport:
   transport data filename (only necessary for Chemkin files)

Example reduction

To apply the DRGEP method for reducing the GRI Mech 3.0 model (included with Cantera), with a maximum error of 10%, using the main reactants as targets (CH4 and O2) and always retaining N2, first create a YAML file (let’s call it reduction_input.yaml:

model: gri30.yaml
targets:
  - CH4
  - O2
retained-species:
  - N2
method: DRGEP
error: 10.0
sensitivity-analysis: False
autoignition-conditions:
  - kind: constant volume
    pressure: 1.0
    temperature: 1000.0
    fuel:
      CH4: 1.0
    oxidizer:
      O2: 1.0
      N2: 3.76
    equivalence-ratio: 1.0

  - kind: constant volume
    pressure: 1.0
    temperature: 1200.0
    fuel:
      CH4: 1.0
    oxidizer:
      O2: 1.0
      N2: 3.76
    equivalence-ratio: 0.5

Then, execute this command:

pymars --input reduction_input.yaml

You can also download an annotated version of the example input file; refer to the Reduction input file section for a detailed explanation.

Parallelization: If you have a large number of initial conditions, the reduction may be sped up by parallelizing the associated simulations over multiple CPU cores. You can do this by adding --num_threads N, where N is the desired number of cores. If you just specify --num_threads, then pyMARS will use the available number of cores minus one.

(pyMARS does not currently support distributed memory parallelization, meaning across multiple nodes that do not share the same memory.)

Sensitivity analysis: To perform sensitivity analysis following DRGEP, change the sensitivity-analysis key to True in the input file, and choose the type of sensitivity analysis with the sensitivity-type field (either initial or greedy). Let’s use the “initial” method for now, since it is less computationally expensive.

Generally it is a good idea to specify an upper threshold value of 0.2 to ensure important species are not evaluated; do this by adding the line upper-threshold: 0.2. (In the Theory guide, this variable is referred to as \(\epsilon^*\).)

Your new input file (called drgepsa_input.yaml) would then look like:

model: gri30.yaml
targets:
  - CH4
  - O2
retained-species:
  - N2
method: DRGEP
error: 10.0
sensitivity-analysis: True
sensitivity-type: initial
upper-threshold: 0.2
autoignition-conditions:
  - kind: constant volume
    pressure: 1.0
    temperature: 1000.0
    fuel:
      CH4: 1.0
    oxidizer:
      O2: 1.0
      N2: 3.76
    equivalence-ratio: 1.0

  - kind: constant volume
    pressure: 1.0
    temperature: 1200.0
    fuel:
      CH4: 1.0
    oxidizer:
      O2: 1.0
      N2: 3.76
    equivalence-ratio: 0.5

Then, the command for performing a reduction using DRGEPSA with parallelized simulations would be:

pymars --input drgepsa_input.yaml --num_threads

Reduction input file

You control the model reduction process in pyMARS through a YAML input file, indicated with the --input or -i command-line argument. Keys include:

  • model: filename of kinetic model being reduced (Chemkin or Cantera)

  • phase-name: Optional name of phase in Cantera YAML file to be reduced

  • targets: List of one or more target species; required for DRG, DRGEP, and PFA methods

  • retained-species: Optional list of one or more species to never remove.

  • method: Reduction method; one of DRG, DRGEP, or PFA

  • error: Maximum error limit of reduced model, given as percentage (e.g., 10.0 for 10%).

  • sensitivity-analysis: Specify True to perform sensitivity analysis, either alone or following a method given by method

  • sensitivity-type: Type of sensitivity analysis, either initial or greedy

  • upper-threshold: Upper threshold value for species to be considered for sensitivity analysis; only used when following one of the graph-based reduction methods

  • autoignition-conditions: List of initial conditions for autoignition simulations, described in more detail next

  • psr-conditions: List of inlet conditions for perfectly stirred reactor (PSR) simulations, described in more detail below

  • laminar-flame-conditions: List of initial conditions for freely-propagating laminar flame simulations, described in more detail below

  • min-flame-speed: Optional minimum laminar flame speed, in m/s, that counts as a real flame (default 0.05); see the laminar flame parameters below

At least one of autoignition-conditions, psr-conditions, or laminar-flame-conditions must be provided; you may also supply any combination, in which case the sampled states and the error metrics from all cases are combined.

The theory behind the PSR extinction-curve computation is documented separately; see Perfectly stirred reactor (PSR) extinction.

Species given in targets, retained-species, or fuel/oxidizer/reactants must be present in the model specified in model, spelling must match exactly (including case).

Autoignition parameters: pyMARS can use autoignition simulations to sample thermochemical data for the reduction and to calculate ignition delays for measuring error of candidate reduced models. Initial conditions are provided for performing these simulations in the autoignition-conditions field of the input file.

These initial conditions are given as a list, with these required keys:

  • kind: Type of homogeneous autoignition simulation; either constant volume or constant pressure

  • pressure: initial pressure, given in atm

  • temperature: initial temperature, given in K

The initial reactant mixture can be given using either an equivalence ratio with separate fuel and oxidizer specifications, or as list of reactants.

To specify the mixture using an equivalence ratio, you must give lists of species in the fuel and oxidizer, with the mole fraction/number of the species in each (these will be automatically normalized):

fuel:
  CH4: 1.0
oxidizer:
  O2: 1.0
  N2: 3.76
equivalence-ratio: 1.0

To specify the mixture using a list of reactants, just give the number of moles of each species in the initial mixture:

reactants:
  CH4: 1.0
  O2: 2.0
  N2: 7.52

When giving the composition as a list of reactants, you can also specify the mass fraction of the mixture using composition-type: mass:

reactants:
  CH4: 0.05518632
  O2: 0.22014867
  N2: 0.724665
composition-type: mass

Note: By default, pyMARS automatically integrates each autoignition case to steady state, or to a maximum of 10,000 integration steps. This can be bypassed by specifying either a different number of maximum steps with max-steps: or a maximum integration end time with end-time: (in seconds). During initial sampling, pyMARS will raise an error if it does not detect autoignition, based on reaching the initial temperature + 400 K.

For convenience, and to save significant runtime when reducing the same model with different parameters, pyMARS will automatically reuse saved ignition data from a prior run. It semi-intelligently checks if the number of cases matches that in the input file, but to be safe output files should be cleaned between applications.

Laminar flame parameters: pyMARS can additionally (or instead) use one-dimensional freely-propagating laminar flame simulations to sample thermochemical data and to use the laminar flame speed as an error metric. Initial conditions are given in the laminar-flame-conditions field as a list, using the same mixture keys as autoignition cases (pressure in atm, temperature in K, and either equivalence-ratio with fuel/oxidizer or a list of reactants). Unlike autoignition cases, no kind is given, since freely-propagating flames are always constant pressure. The temperature should be the unburned-mixture temperature (e.g., 300 K).

Each flame case also accepts an optional width key giving the width of the computational domain in meters (default 0.1); this is the initial estimate of the domain size, which Cantera refines automatically during the solve:

laminar-flame-conditions:
  - pressure: 1.0
    temperature: 300.0
    width: 0.03
    fuel:
      H2: 1.0
    oxidizer:
      O2: 1.0
      N2: 3.76
    equivalence-ratio: 1.0

Note that the kinetic model must include transport data to run laminar flame simulations. Flame simulations are considerably more expensive than autoignition simulations, so reductions that rely on them will take longer.

No-flame detection. A non-flammable mixture does not raise an error when solved; it instead converges to a degenerate, near-zero (or negative) “flame speed”. pyMARS treats any solved flame speed at or below min-flame-speed (default 0.05 m/s) as no flame: during a reduction, a candidate reduced model that produces such a result is rejected (assigned 100% error) rather than aborting the run. min-flame-speed is a single global setting (not per-case); lower it if you are studying a fuel with actual low flame speeds that could fall below the default floor:

min-flame-speed: 0.01

As with autoignition data, pyMARS reuses saved laminar flame samples from a prior run when the number and shape of the saved cases match the input file.

Perfectly stirred reactor (PSR) parameters: pyMARS can additionally (or instead) use steady perfectly stirred reactor simulations to sample thermochemical data and to use the reactor’s extinction behavior as an error metric. For each case, pyMARS traces the steady temperature-versus-residence-time response curve and follows its upper (burning) branch through the extinction turning point using pseudo-arclength continuation, which is robust where ordinary time-integration fails near extinction. The underlying theory is documented in Perfectly stirred reactor (PSR) extinction. This capability requires the scipy package.

Conditions are given in the psr-conditions field as a list, using the same mixture keys as laminar flame cases (pressure in atm, temperature in K, and either equivalence-ratio with fuel/oxidizer or a list of reactants). PSR cases are modeled as adiabatic and constant pressure, and temperature is the inlet temperature (e.g., 300 K):

psr-conditions:
  - pressure: 1.0
    temperature: 300.0
    fuel:
      CH4: 1.0
    oxidizer:
      O2: 1.0
      N2: 3.76
    equivalence-ratio: 1.0

Three points are sampled from the burning branch: the extinction turning point, the point nearest a residence time of 0.1 s, and their logarithmic midpoint. The PSR error metric is the largest of the relative error in the extinction residence time and the relative errors in the response temperatures at the other two points. A candidate reduced model that can no longer sustain a stirred reactor (its response curve cannot be traced) is rejected—assigned 100% error—rather than aborting the run, the same way non-igniting and non-flammable candidates are handled. As with the other data sources, pyMARS reuses saved PSR samples from a prior run when the number and shape of the saved cases match the input file.

Conversion

pyMARS provides a tool for converting between Chemkin and Cantera model formats. (This is used implicity if a Chemkin model is given when running pyMARS.) Generally this will be used to convert a Cantera reduced model generated by pyMARS into a Chemkin-format model.

To convert a Cantera model into a Chemkin model, do

pymars --convert -m model.yaml

pyMARS also provides conversion from Chemkin to Cantera for convenience:

pymars --convert -m model.inp --thermo thermo.dat

The _thermo option is not required if the thermodynamic data is contained within the model file (i.e., with the THERMO ALL keyword). The transport data can also be included in the resulting Cantera file with the --transport option.