.. highlight:: yaml

*****************
General Structure
*****************

Sections
--------

The top level of a Cantera `YAML <https://yaml.org/spec/1.2/spec.html#Introduction>`__
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 :ref:`sec-yaml-reactions`, :ref:`sec-yaml-species`, and
:ref:`sec-yaml-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

.. _sec-yaml-units:

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``, any unit of energy per quantity (``J/kmol``,
  ``cal/mol``, etc.), or any unit of energy (such as `eV`)
- 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.

Activation energies given in temperature units will be implicitly converted to energy per
quantity by dividing by the gas constant. Activation energies given in pure energy units
such as eV will be converted to energy per quantity by multiplying by the Avogadro
constant. 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``.