Creating YAML Mechanism Files from Scratch — Cantera 3.2.0 documentation

Virtually every Cantera simulation involves one or more phases of matter. Depending on the calculation being performed, it may be necessary to evaluate thermodynamic properties, transport properties, and/or reaction rates for the phase(s) present. Before the properties can be evaluated, each phase must be defined, meaning that the models to use to compute its properties and reaction rates must be specified, along with any parameters the models require.
Because the amount of data required can be quite large, this data is imported from a YAML file that can be read by the application, so that a given phase model can be re-used for other simulations. This guide describes how to write such files to define phases and interfaces for use in Cantera simulations.
See the Introduction to YAML Input Files for an introduction to the YAML syntax used by Cantera and a description of how dimensional values are handled.
See the Example Input Files for several complete YAML input files demonstrating a variety of thermodynamic and reaction parameterizations.
The top level of a Cantera YAML input file is a mapping, which typically includes several keys providing relevant metadata followed by several sections that provide definitions for phases, species, and reactions. In case input data is provided in a unit system other than Cantera’s default, a units mapping can be provided. The following is a typical, abbreviated input file (a subset of the h2o2.yaml input file included with Cantera):
For each phase that appears in a problem, a corresponding entry should be present in the phases section of the input file. The phase entry specifies the elements and species present in that phase, and the models to be used for computing thermodynamic, kinetic, and transport properties.
The name entry is a string that identifies the phase. It must be unique within the file among all phase definitions of any type. Phases are referenced by name when importing them. The name is also used to identify the phase within multiphase mixtures or at phase boundaries.
The thermodynamic model used to represent a phase is specified in the thermo field. A complete list of supported models can be found in the YAML Input File Reference. Some thermodynamic models use additional fields in the phase entry, which are described in the linked documentation.
In most cases, it is not necessary to specify the elements present in a phase. If no elements field is present, elements will be added automatically using the definitions of the standard chemical elements based on the composition of the species present in the phase.
If non-standard elements such as isotopes need to be represented, or the ordering of elements within the phase is important, the elements in the phase may be declared in the optional elements entry.
If all of the elements to be added are either standard chemical elements or defined in the elements section of the current input file, the elements can be specified as a list of element symbols. For example:
To add elements from other top-level sections, from a different file, or from multiple such sources, a list of single-key mappings can be used where the key of each mapping specifies the source and the value is a list of element names. The keys can be:
The name of a section within the current file.
The name of an input file and a section in that file, separated by a slash, for example myfile.yaml/my_elements. If a relative path is specified, the directory containing the current file is searched first, followed by the Cantera data path.
The name default to reference the standard chemical elements.
The order of the elements specified in the input file determines the order of the elements in the phase when it is imported by Cantera.
If the species present in the phase corresponds to those species defined in the species section of the input file, the species field may be omitted, and those species will be added to the phase automatically. As a more explicit alternative, the species field may be set to the string all.
To include specific species from the species section of the input file, the species entry can be a list of species names from that section. For example:
If species are defined in multiple input file sections, the species entry can be a list of single-key mappings, where the key of each mapping specifies the source and the value is either the string all or a list of species names. Each key can be either the name of a section within the current input file or the name of a different file and a section in that file, separated by a slash. If a relative path is specified, the directory containing the current file is searched first, followed by the Cantera data path. Example:
The order of species specified in the input file determines the order of the species in the phase when it is imported by Cantera.
Species containing elements that are not declared within the phase may be skipped by setting the skip-undeclared-elements field to true. For example, to add all species from the species section that contain only hydrogen or oxygen, the phase definition could contain:
In cases where the element restriction is also being used to select a subset of reactions, it is usually necessary to use the declared-species option and the skip-undeclared-third-bodies flag as well:
The kinetics model to be used, if any, is specified in the kinetics field. Supported kinetics models are bulk, surface, and edge, depending on the dimensionality of the phase. If omitted, no kinetics model will be used. For additional details, see the list of supported models in the YAML Input File Reference.
If a kinetics model has been specified, reactions may be added to the phase. By default, all reactions from the reactions section of the input file will be added. Equivalently, the reactions entry may be specified as the string all.
To disable automatic addition of reactions from the reactions section, the reactions entry may be set to none. This may be useful if reac