Introduction to YAML Input Files — Cantera 3.2.0 documentation

All calculations in Cantera require an input file to describe the properties of the relevant phase(s) of matter. These input files can be provided via one of several methods:
Use an existing input file. The input files included with Cantera should suffice for tutorials and introductory work with thermodynamic phases and reaction kinetics. A number of additional input files are available from various sources on the web.
Convert a mechanism from Chemkin (CK) format to YAML format. Many reaction mechanisms are published in Chemkin (CK) format, and can be converted to Cantera’s YAML format using the ck2yaml conversion tool. see Converting Chemkin Format Files for more information.
Create your own YAML file from scratch or by editing an existing file. Advanced users may need to edit an existing input file in order to define additional species, reactions, or entirely new phases. See Creating YAML Mechanism Files from Scratch for more information.
Whenever you edit a Cantera input file, it is highly advised that you begin by copying the existing file and saving it under a new name, before editing the new file. Editing a file under its original name can easily lead to errors, if one forgets that this file does not represent the original mechanism.
With any input file, it can be helpful to understand the syntax requirements. Clearly, anyone writing directly in the YAML formats must conform to these standards. However, even when importing an externally-provided file or converting from CK format, understanding the input file syntax can help diagnose and correct any errors (although many/most of the CK conversion errors will be related to errors in the CK syntax formatting).
Cantera YAML files use a subset of the YAML 1.2 specification. Cantera YAML files consist of individual values, which may be strings, numbers or booleans, that are then composed as elements of nested mappings and sequences.
Strings may be generally written without quotes, but may be enclosed in single quotes or double quotes if needed in order to avoid certain parsing ambiguities.
Numbers can be written as integers, decimal values, or using E-notation
Boolean values in YAML are written as the words true or false.
A sequence of multiple items is specified by separating the items by commas and enclosing them in square brackets. The individual items can have any type – strings, integers, floating-point numbers, mappings, or sequences.
The syntax above, using square brackets to define a list, is called flow style in YAML. Sequences can also be written in block style, using one line for each item in the sequence, with each line starting with a dash:
Sequences can also be nested. The following examples are all equivalent:
A mapping is a container consisting of key–value pairs. The keys in a mapping must be unique. Like sequences, there are two ways to write a mapping. In the flow style, the mapping is enclosed in curly brackets, colons (followed by spaces) are used to separate keys and values, and key–value pairs are separated by commas:
In the block style, each key is written on a new line, followed by a colon. The value can be placed either on the same line, or on the following line, indented one level:
All keys in Cantera YAML files are treated as strings. A Cantera YAML file is itself a mapping, usually in the block style. We refer to the keys in this top-level mapping as the sections of the input file.
A common structure in Cantera input files is a nested sequence of mappings. This can be written in the block style as:
The keys in each mapping need not be the same. In this example, each of the three mappings in the sequence has equation and rate-constant keys, while only the third entry has type and efficiencies keys.
The character # is the comment character. Everything to the right of this character on a line is ignored:
Many fields have numerical values that represent dimensional quantities—a pressure, or a density, for example. If these are entered without specifying the units, the default units (set by the units directive) will be used. However, it is also possible to specify the units for each individual dimensional quantity, unless stated otherwise. All that is required is to write the units after the value, separated by a space:
Compound unit strings may be used, as long as a few rules are followed:
Units in the denominator follow /.
Units in the numerator follow *, except for the first one.
Numerical exponents follow the unit string with a ^ character.
Examples of compound units:
See the Units API documentation for additional details, including the full set of supported units.
Default units that apply to a whole input file or some portion thereof can be set using units mapping. A units mapping placed at the top level of an input file applies to the entire file. A units mapping placed as a member of another mapping applies to that mapping and any nested mappings or sequences, and overrides higher-level units mappings:
Default units may be set for mass, length, time, quantity, pressure, energy, and activation-energy.
Several reaction mechanism files are included in the Cantera distribution, including ones that model natural gas combustion gri30.yaml, high-temperature air (air.yaml), a hydrogen/oxygen reaction mechanism h2o2.yaml, some pure fluids in the liquid-vapor region (liquidvapor.yaml), and a few surface reaction mechanisms (such as ptcombust.yaml, diamond.yaml, etc.), among others. A subset of these data files are shown in the Examples section to demonstrate the YAML format and some of the commonly-used models and options.
Additional data used in various examples are included in the example_data subdirectory of the default Cantera data directory. These files can be imported using relative paths, for example (in Python):
The input files included with Cantera are provided for convenience, and may not be suited for research purposes.
On Windows, these files may be located in C:\Program Files\Cantera\data depending on ho