General Structure

Sections

The top level of a Cantera YAML input file is a mapping that defines different input file sections. Each section consists of a list of mappings that define objects of the same type, such as reactions, species, phases, or elements. The phases section of an input file contains all of the phase definitions. Multiple sections containing reaction, species, or element definitions can be used. The specific names reactions, species, and elements are used as defaults when looking for Reactions, Species, and Elements to add to a phase. A simple input file has the following structure:

phases:
- name: spam
  thermo: ideal-gas
  # Additional fields come after this
- name: green-eggs
  thermo: model-name
  # Additional fields come after this

species:
- name: A
  # Additional fields come after this
- name: B
  # Additional fields come after this
- name: C
  # Additional fields come after this

reactions:
- equation: A + B <=> C + D
  # Additional fields come after this
- equation: A + C <=> 2 D
  # Additional fields come after this

Units

While Cantera generally works internally in SI units, input values can be provided using a number of different units.

Compound units are written using the asterisk (*) to indicate multiplication, the forward slash (/) to indicate division, and the caret (^) to indicate exponentiation. Exponents can include negative and decimal values. Standard one-letter metric prefixes can be applied to any unit. Supported base units are:

  • Mass: g

  • Length: m, micron, angstrom, Å

  • Time: s, min, hr

  • Temperature: K, C

  • Current: A

  • Quantity: mol (gram mole), gmol, mole, kmol, kgmol, molec

Supported compound units are:

  • Energy: J, cal, erg, eV

  • Activation Energy: K, or any unit of energy per quantity (J/kmol, cal/mol, etc.)

  • Force: N, dyn

  • Pressure: Pa, atm, bar, dyn/cm^2

  • Volume: m^3, liter, L, l, cc

  • Other electrical units: ohm, V, coulomb

Units can be specified on individual input values by placing them after the value, separated by a space:

{A: 1.45e9 cm^3/kmol, b: 0.4, Ea: 21033 kJ/kmol}

or by using a units mapping:

units: {mass: g, quantity: mol, pressure: atm, activation-energy: cal/mol}

A units mapping will set the default units for all values within the same YAML list or mapping, including any nested lists and mappings. Units not specified by a mapping use the values from higher level mappings, or the Cantera defaults if no units mapping specifies applicable units. If a units mapping appears in a list, it must be the first item in that list.

Default units may be set for mass, length, time, temperature, current, quantity, pressure, energy, and activation-energy. The units pressure and energy are used when these units appear explicitly in the units that a value is being converted to within Cantera. For example, a conversion to N/m^2 will use the default units for mass, length, and time, while a conversion to Pa will use the default units for pressure.

Conversions of activation energies implicitly include scaling by the gas constant where necessary. Setting default units for energy and quantity will determine the default units of activation-energy, which can be overridden by explicitly giving the desired units of activation-energy.