I - An example to start with ...

This first tutorial's main objective is to help you get started with the Python interface of Cantera. The goal here is to get acquainted with the notion of objects and functions that we will encounter in all Python scripts.
We will start by defining a simple gaseous object directly in a script, before introducing the Python terminal and its possibilities. Next, we will see how to access and modify the state of this newly instantiated gas object through adequate functions; before concluding with a general discussion on the specificities of gaseous objects.
The second objective of this first tutorial is to introduce the data file format of Cantera, which will be the subject of the second tutorial.

1. Importation of cantera

In [1]:
import cantera as ct
from cantera import cti2yaml

2. Create solution from yaml file

This will create an instance of the class Solution from cantera package.
The file gri30.yaml contains all the important informations about the chemistry, meaning :
  • the properties of the different species
  • the reactions
  • the kinetics used
  • the type of transport used
In [2]:
gas = ct.Solution("gri30.yaml")
NB : Cantera only supports yaml format mechanisms. Indeed, yaml format is more human readable and more flexible than cti format (used in the previous versions of Cantera). You will see some more information about the structure and the data present in this yaml file at the end of this tutorial, and how to convert a cti to a yaml file.

3. Choose and print the thermodynamic state of the gas

To define the mixture of the gas correctly, it is necessary to define two thermodynamic parameters and the quantities of the different species ( molar fraction X or mass fraction Y ). These commands give all the interesting informations for the gas state, namely the temperature, the pressure and the density of the mixture. It also gives information about the species in the mixture as mass fractions Y or molar fractions X.

NB : If you are lost, you can still use the function help to see what are the functions available for a gaseous object.

In [3]:
help(gas)
Help on Solution in module cantera.composite object:

class Solution(cantera.transport.Transport, cantera.kinetics.Kinetics, cantera.thermo.ThermoPhase)
 |  A class for chemically-reacting solutions. Instances can be created to
 |  represent any type of solution -- a mixture of gases, a liquid solution, or
 |  a solid solution, for example.
 |  
 |  Class `Solution` derives from classes `ThermoPhase`, `Kinetics`, and
 |  `Transport`.  It defines no methods of its own, and is provided so that a
 |  single object can be used to compute thermodynamic, kinetic, and transport
 |  properties of a solution.
 |  
 |  To skip initialization of the Transport object, pass the keyword argument
 |  ``transport_model=None`` to the `Solution` constructor.
 |  
 |  The most common way to instantiate `Solution` objects is by using a phase
 |  definition, species and reactions defined in an input file::
 |  
 |      gas = ct.Solution('gri30.yaml')
 |  
 |  If an input file defines multiple phases, the corresponding key in the
 |  ``phases`` map can be used to specify the desired phase via the ``name`` keyword
 |  argument of the constructor::
 |  
 |      gas = ct.Solution('diamond.yaml', name='gas')
 |      diamond = ct.Solution('diamond.yaml', name='diamond')
 |  
 |  The name of the `Solution` object defaults to the *phase* identifier
 |  specified in the input file. Upon initialization of a `Solution` object,
 |  a custom name can assigned via::
 |  
 |      gas.name = 'my_custom_name'
 |  
 |  `Solution` objects can also be constructed using `Species` and `Reaction`
 |  objects which can themselves either be imported from input files or defined
 |  directly in Python::
 |  
 |      spec = ct.Species.list_from_file("gri30.yaml")
 |      spec_gas = ct.Solution(thermo='ideal-gas', species=spec)
 |      rxns = ct.Reaction.list_from_file("gri30.yaml", spec_gas)
 |      gas = ct.Solution(thermo='ideal-tas', kinetics='gas',
 |                        species=spec, reactions=rxns, name='my_custom_name')
 |  
 |  where the ``thermo`` and ``kinetics`` keyword arguments are strings
 |  specifying the thermodynamic and kinetics model, respectively, and
 |  ``species`` and ``reactions`` keyword arguments are lists of `Species` and
 |  `Reaction` objects, respectively. Note that importing the reactions from a
 |  YAML input file requires a `Kinetics` object containing the species, as
 |  shown.
 |  
 |  Types of underlying models that form the composite `Solution` object are
 |  queried using the ``thermo_model``, ``kinetics_model`` and
 |  ``transport_model`` attributes; further, the ``composite`` attribute is a
 |  shorthand returning a tuple containing the types of the three constitutive
 |  models.
 |  
 |  For non-trivial uses cases of this functionality, see the examples
 |  `extract_submechanism.py <https://cantera.org/examples/python/kinetics/extract_submechanism.py.html>`_
 |  and `mechanism_reduction.py <https://cantera.org/examples/python/kinetics/mechanism_reduction.py.html>`_.
 |  
 |  In addition, `Solution` objects can be constructed by passing the text of
 |  the YAML phase definition in directly, using the ``yaml`` keyword
 |  argument::
 |  
 |      yaml_def = '''
 |      phases:
 |      - name: gas
 |        thermo: ideal-gas
 |        kinetics: gas
 |        elements: [O, H, Ar]
 |        species:
 |        - gri30.yaml/species: all
 |        reactions:
 |        - gri30.yaml/reactions: declared-species
 |        skip-undeclared-elements: true
 |        skip-undeclared-third-bodies: true
 |        state: {T: 300, P: 1 atm}
 |      '''
 |      gas = ct.Solution(yaml=yaml_def)
 |  
 |  Method resolution order:
 |      Solution
 |      cantera.transport.Transport
 |      cantera.kinetics.Kinetics
 |      cantera.thermo.ThermoPhase
 |      cantera.solutionbase._SolutionBase
 |      builtins.object
 |  
 |  Methods inherited from cantera.transport.Transport:
 |  
 |  __init__(self, /, *args, **kwargs)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |  
 |  __reduce_cython__(...)
 |  
 |  __setstate_cython__(...)
 |  
 |  get_binary_diff_coeffs_polynomial(self, i, j)
 |      Get the polynomial fit to the logarithm of temperature for
 |      the binary diffusion coefficient of species ``i`` and ``j``.
 |  
 |  get_collision_integral_polynomials(self, i, j)
 |      Get the polynomial fit to the logarithm of temperature for
 |      the collision integral of species ``i`` and ``j``.
 |  
 |  get_thermal_conductivity_polynomial(self, i)
 |      Get the polynomial fit to the logarithm of temperature for
 |      the thermal conductivity of species ``i``.
 |  
 |  get_viscosity_polynomial(self, i)
 |      Get the polynomial fit to the logarithm of temperature for
 |      the viscosity of species ``i``.
 |  
 |  set_binary_diff_coeffs_polynomial(self, i, j, values)
 |      Set the polynomial fit to the logarithm of temperature for
 |      the binary diffusion coefficient of species ``i`` and ``j``.
 |  
 |  set_collision_integral_polynomial(self, i, j, avalues, bvalues, cvalues, actualT)
 |      Get the polynomial fit to the logarithm of temperature for
 |      the collision integral of species ``i`` and ``j``.
 |  
 |  set_thermal_conductivity_polynomial(self, i, values)
 |      Set the polynomial fit to the logarithm of temperature for
 |      the thermal conductivity of species ``i``.
 |  
 |  set_viscosity_polynomial(self, i, values)
 |      Set the polynomial fit to the logarithm of temperature for
 |      the viscosity of species ``i``.
 |  
 |  ----------------------------------------------------------------------
 |  Static methods inherited from cantera.transport.Transport:
 |  
 |  __new__(*args, **kwargs) from builtins.type
 |      Create and return a new object.  See help(type) for accurate signature.
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from cantera.transport.Transport:
 |  
 |  CK_mode
 |      Boolean to indicate if the chemkin interpretation is used.
 |  
 |  binary_diff_coeffs
 |      Binary diffusion coefficients [m^2/s].
 |  
 |  electrical_conductivity
 |      Electrical conductivity. [S/m].
 |  
 |  mix_diff_coeffs
 |      Mixture-averaged diffusion coefficients [m^2/s] relating the
 |      mass-averaged diffusive fluxes (with respect to the mass averaged
 |      velocity) to gradients in the species mole fractions.
 |  
 |  mix_diff_coeffs_mass
 |      Mixture-averaged diffusion coefficients [m^2/s] relating the
 |      diffusive mass fluxes to gradients in the species mass fractions.
 |  
 |  mix_diff_coeffs_mole
 |      Mixture-averaged diffusion coefficients [m^2/s] relating the
 |      molar diffusive fluxes to gradients in the species mole fractions.
 |  
 |  mobilities
 |      Electrical mobilities of charged species [m^2/s-V]
 |  
 |  multi_diff_coeffs
 |      Multicomponent diffusion coefficients, D[i,j], the diffusion
 |      coefficient for species i due to concentration gradients in
 |      species j [m**2/s].
 |  
 |  species_viscosities
 |      Pure species viscosities [Pa-s]
 |  
 |  thermal_conductivity
 |      Thermal conductivity. [W/m/K]
 |  
 |  thermal_diff_coeffs
 |      Return a one-dimensional array of the species thermal diffusion
 |      coefficients [kg/m/s].
 |  
 |  transport_model
 |      Get/Set the transport model associated with this transport model.
 |      
 |      Setting a new transport model deletes the underlying C++ Transport
 |      object and replaces it with a new one implementing the specified model.
 |  
 |  viscosity
 |      Viscosity [Pa-s].
 |  
 |  ----------------------------------------------------------------------
 |  Methods inherited from cantera.kinetics.Kinetics:
 |  
 |  add_reaction(self, rxn)
 |      Add a new reaction to this phase.
 |  
 |  kinetics_species_index(self, species, phase)
 |      The index of species ``species`` of phase ``phase`` within arrays returned
 |      by methods of class `Kinetics`. If ``species`` is a string, the ``phase``
 |      argument is unused.
 |  
 |  kinetics_species_name(self, k)
 |      Name of the species with index ``k`` in the arrays returned by methods
 |      of class `Kinetics`.
 |  
 |  modify_reaction(self, irxn, rxn)
 |      Modify the `Reaction` with index ``irxn`` to have the same rate
 |      parameters as ``rxn``. ``rxn`` must have the same reactants and products
 |      and be of the same type (for example, `ElementaryReaction`, `FalloffReaction`,
 |      `PlogReaction`, etc.) as the existing reaction. This method does not
 |      modify the third-body efficiencies, reaction orders, or reversibility of
 |      the reaction.
 |  
 |  multiplier(self, i_reaction)
 |      A scaling factor applied to the rate coefficient for reaction
 |      ``i_reaction``. Can be used to carry out sensitivity analysis or to
 |      selectively disable a particular reaction. See `set_multiplier`.
 |  
 |  product_stoich_coeff(self, k_spec, i_reaction)
 |      The stoichiometric coefficient of species ``k_spec`` as a product in
 |      reaction ``i_reaction``.
 |  
 |  reactant_stoich_coeff(self, k_spec, i_reaction)
 |      The stoichiometric coefficient of species ``k_spec`` as a reactant in
 |      reaction ``i_reaction``.
 |  
 |  reaction(self, i_reaction)
 |      Return a `Reaction` object representing the reaction with index
 |      ``i_reaction``. Changes to this object do not affect the `Kinetics` or
 |      `Solution` object until the `modify_reaction` function is called.
 |  
 |  reaction_equations(self, indices)
 |      Returns a list containing the reaction equation for all reactions in the
 |      mechanism if ``indices`` is unspecified, or the equations for each
 |      reaction in the sequence ``indices``. For example::
 |      
 |          >>> gas.reaction_equations()
 |          ['2 O + M <=> O2 + M', 'O + H + M <=> OH + M', 'O + H2 <=> H + OH', ...]
 |          >>> gas.reaction_equations([2,3])
 |          ['O + H + M <=> OH + M', 'O + H2 <=> H + OH']
 |      
 |      See also `reaction_equation`.
 |  
 |  reactions(self)
 |      Return a list of all `Reaction` objects. Changes to these objects do not
 |      affect the `Kinetics` or `Solution` object until the `modify_reaction`
 |      function is called.
 |  
 |  reset_custom(self)
 |      Function calling the dlclose in CustomKinetics
 |      in order to close the dynamic library (handle)
 |  
 |  set_multiplier(self, value, i_reaction)
 |      Set the multiplier for for reaction ``i_reaction`` to ``value``.
 |      If ``i_reaction`` is not specified, then the multiplier for all reactions
 |      is set to ``value``. See `multiplier`.
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from cantera.kinetics.Kinetics:
 |  
 |  creation_rates
 |      Creation rates for each species. [kmol/m^3/s] for bulk phases or
 |      [kmol/m^2/s] for surface phases.
 |  
 |  creation_rates_ddC
 |      Calculate derivatives of species creation rates with respect to molar
 |      concentration at constant temperature, pressure and mole fractions.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  creation_rates_ddCi
 |      Calculate derivatives for species creation rates with respect to species
 |      concentration at constant temperature, pressure, and concentration of all other
 |      species. For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      The method returns a matrix with `n_total_species` rows and `n_total_species`
 |      columns.
 |      
 |      For a derivative with respect to :math: `c_i`, all other :math: `c_i` are
 |      held constant.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |      
 |      .. versionadded:: 3.0
 |  
 |  creation_rates_ddP
 |      Calculate derivatives of species creation rates with respect to pressure
 |      at constant temperature, molar concentration and mole fractions.
 |  
 |  creation_rates_ddT
 |      Calculate derivatives of species creation rates with respect to temperature
 |      at constant pressure, molar concentration and mole fractions.
 |  
 |  creation_rates_ddX
 |      Calculate derivatives for species creation rates with respect to species
 |      concentrations at constant temperature, pressure and molar concentration.
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      Note that for derivatives with respect to :math:`X_i`, all other :math:`X_j`
 |      are held constant, rather than enforcing :math:`\sum X_j = 1`.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  delta_enthalpy
 |      Change in enthalpy for each reaction [J/kmol].
 |  
 |  delta_entropy
 |      Change in entropy for each reaction [J/kmol/K].
 |  
 |  delta_gibbs
 |      Change in Gibbs free energy for each reaction [J/kmol].
 |  
 |  delta_standard_enthalpy
 |      Change in standard-state enthalpy (independent of composition) for
 |      each reaction [J/kmol].
 |  
 |  delta_standard_entropy
 |      Change in standard-state entropy (independent of composition) for
 |      each reaction [J/kmol/K].
 |  
 |  delta_standard_gibbs
 |      Change in standard-state Gibbs free energy (independent of composition)
 |      for each reaction [J/kmol].
 |  
 |  derivative_settings
 |      Property setting behavior of derivative evaluation.
 |      
 |      For ``GasKinetics``, the following keyword/value pairs are supported:
 |      
 |      -  ``skip-third-bodies`` (boolean) ... if `False` (default), third body
 |         concentrations are considered for the evaluation of derivatives
 |      
 |      -  ``skip-falloff`` (boolean) ... if `True` (default), third-body effects
 |         on reaction rates are not considered.
 |      
 |      -  ``rtol-delta`` (double) ... relative tolerance used to perturb properties
 |         when calculating numerical derivatives. The default value is 1e-8.
 |      
 |      Derivative settings are updated using a dictionary::
 |      
 |          >>> gas.derivative_settings = {"skip-falloff": True}
 |      
 |      Passing an empty dictionary will reset all values to their defaults.
 |  
 |  destruction_rates
 |      Destruction rates for each species. [kmol/m^3/s] for bulk phases or
 |      [kmol/m^2/s] for surface phases.
 |  
 |  destruction_rates_ddC
 |      Calculate derivatives of species destruction rates with respect to molar
 |      concentration at constant temperature, pressure and mole fractions.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  destruction_rates_ddCi
 |      Calculate derivatives for species destruction rates with respect to species
 |      concentration at constant temperature, pressure, and concentration of all other
 |      species. For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      The method returns a matrix with `n_total_species` rows and `n_total_species` columns.
 |      For a derivative with respect to :math: `c_i`, all other :math: `c_i` are
 |      held constant.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |      
 |      .. versionadded:: 3.0
 |  
 |  destruction_rates_ddP
 |      Calculate derivatives of species destruction rates with respect to pressure
 |      at constant temperature, molar concentration and mole fractions.
 |  
 |  destruction_rates_ddT
 |      Calculate derivatives of species destruction rates with respect to temperature
 |      at constant pressure, molar concentration and mole fractions.
 |  
 |  destruction_rates_ddX
 |      Calculate derivatives for species destruction rates with respect to species
 |      concentrations at constant temperature, pressure and molar concentration.
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      Note that for derivatives with respect to :math:`X_i`, all other :math:`X_j`
 |      are held constant, rather than enforcing :math:`\sum X_j = 1`.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  equilibrium_constants
 |      Equilibrium constants in concentration units for all reactions.
 |  
 |  forward_rate_constants
 |      Forward rate constants for all reactions.
 |      
 |      The computed values include all temperature-dependent and pressure-dependent
 |      contributions. By default, third-body concentrations are only considered if
 |      they are part of the reaction rate definition; for a legacy implementation that
 |      includes third-body concentrations, see `use_legacy_rate_constants`.
 |  
 |  forward_rate_constants_ddC
 |      Calculate derivatives for forward rate constants with respect to molar
 |      concentration at constant temperature, pressure and mole fractions.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  forward_rate_constants_ddP
 |      Calculate derivatives for forward rate constants with respect to pressure
 |      at constant temperature, molar concentration and mole fractions.
 |  
 |  forward_rate_constants_ddT
 |      Calculate derivatives for forward rate constants with respect to temperature
 |      at constant pressure, molar concentration and mole fractions.
 |  
 |  forward_rates_of_progress
 |      Forward rates of progress for the reactions. [kmol/m^3/s] for bulk
 |      phases or [kmol/m^2/s] for surface phases.
 |  
 |  forward_rates_of_progress_ddC
 |      Calculate derivatives for forward rates-of-progress with respect to molar
 |      concentration at constant temperature, pressure and mole fractions.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  forward_rates_of_progress_ddCi
 |      Calculate derivatives for forward rates-of-progress with respect to species
 |      concentrations at constant temperature, pressure and remaining species
 |      concentrations.
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      Note that for derivatives with respect to :math:`c_i`, all other :math:`c_j`
 |      are held constant.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |      
 |      .. versionadded:: 3.0
 |  
 |  forward_rates_of_progress_ddP
 |      Calculate derivatives for forward rates-of-progress with respect to pressure
 |      at constant temperature, molar concentration and mole fractions.
 |  
 |  forward_rates_of_progress_ddT
 |      Calculate derivatives for forward rates-of-progress with respect to temperature
 |      at constant pressure, molar concentration and mole fractions.
 |  
 |  forward_rates_of_progress_ddX
 |      Calculate derivatives for forward rates-of-progress with respect to species
 |      concentrations at constant temperature, pressure and molar concentration.
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      Note that for derivatives with respect to :math:`X_i`, all other :math:`X_j`
 |      are held constant, rather than enforcing :math:`\sum X_j = 1`.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  heat_production_rates
 |      Get the volumetric heat production rates [W/m^3] on a per-reaction
 |      basis. The sum over all reactions results in the total volumetric heat
 |      release rate.
 |      Example: C. K. Law: Combustion Physics (2006), Fig. 7.8.6
 |      
 |      >>> gas.heat_production_rates[1]  # heat production rate of the 2nd reaction
 |  
 |  heat_release_rate
 |      Get the total volumetric heat release rate [W/m^3].
 |  
 |  kinetics_model
 |      Return type of kinetics.
 |  
 |  kinetics_species_names
 |      A list of all species names, corresponding to the arrays returned by
 |      methods of class `Kinetics`.
 |  
 |  n_phases
 |      Number of phases in the reaction mechanism.
 |  
 |  n_reactions
 |      Number of reactions in the reaction mechanism.
 |  
 |  n_total_species
 |      Total number of species in all phases participating in the kinetics
 |      mechanism.
 |  
 |  net_production_rates
 |      Net production rates for each species. [kmol/m^3/s] for bulk phases or
 |      [kmol/m^2/s] for surface phases.
 |  
 |  net_production_rates_ddC
 |      Calculate derivatives of species net production rates with respect to molar
 |      density at constant temperature, pressure and mole fractions.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  net_production_rates_ddCi
 |      Calculate derivatives for species net production rates with respect to species
 |      concentration at constant temperature, pressure, and concentration of all other
 |      species. For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      The method returns a matrix with `n_total_species` rows and `n_total_species` columns.
 |      For a derivative with respect to :math: `c_i`, all other :math: `c_i` are
 |      held constant.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |      
 |      .. versionadded:: 3.0
 |  
 |  net_production_rates_ddP
 |      Calculate derivatives of species net production rates with respect to pressure
 |      at constant temperature, molar concentration and mole fractions.
 |  
 |  net_production_rates_ddT
 |      Calculate derivatives of species net production rates with respect to
 |      temperature at constant pressure, molar concentration and mole fractions.
 |  
 |  net_production_rates_ddX
 |      Calculate derivatives for species net production rates with respect to species
 |      concentrations at constant temperature, pressure and molar concentration.
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      Note that for derivatives with respect to :math:`X_i`, all other :math:`X_j`
 |      are held constant, rather than enforcing :math:`\sum X_j = 1`.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  net_rates_of_progress
 |      Net rates of progress for the reactions. [kmol/m^3/s] for bulk phases
 |      or [kmol/m^2/s] for surface phases.
 |  
 |  net_rates_of_progress_ddC
 |      Calculate derivatives for net rates-of-progress with respect to molar
 |      concentration at constant temperature, pressure and mole fractions.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  net_rates_of_progress_ddCi
 |      Calculate derivatives for net rates-of-progress with respect to species
 |      concentrations at constant temperature, pressure and remaining species
 |      concentrations. For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      Note that for derivatives with respect to :math:`c_i`, all other :math:`c_j`
 |      are held constant.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |      
 |      .. versionadded:: 3.0
 |  
 |  net_rates_of_progress_ddP
 |      Calculate derivatives for net rates-of-progress with respect to pressure
 |      at constant temperature, molar concentration and mole fractions.
 |  
 |  net_rates_of_progress_ddT
 |      Calculate derivatives for net rates-of-progress with respect to temperature
 |      at constant pressure, molar concentration and mole fractions.
 |  
 |  net_rates_of_progress_ddX
 |      Calculate derivatives for net rates-of-progress with respect to species
 |      concentrations at constant temperature, pressure and molar concentration.
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      Note that for derivatives with respect to :math:`X_i`, all other :math:`X_j`
 |      are held constant, rather than enforcing :math:`\sum X_j = 1`.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  product_stoich_coeffs
 |      The array of product stoichiometric coefficients. Element ``[k,i]`` of
 |      this array is the product stoichiometric coefficient of species ``k`` in
 |      reaction ``i``.
 |      
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      .. versionchanged:: 3.0
 |      
 |          Method was changed to a property in Cantera 3.0.
 |  
 |  product_stoich_coeffs3
 |      The array of product stoichiometric coefficients. Element ``[k,i]`` of
 |      this array is the product stoichiometric coefficient of species ``k`` in
 |      reaction ``i``.
 |      
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      .. deprecated:: 3.0
 |      
 |          Method to be removed after Cantera 3.0. Replaceable by
 |          `Kinetics.product_stoich_coeffs`
 |  
 |  product_stoich_coeffs_reversible
 |      The array of product stoichiometric coefficients of reversible reactions.
 |      Element ``[k,i]`` of this array is the product stoichiometric coefficient
 |      of species ``k`` in reaction ``i``.
 |      
 |      For sparse output, set ``ct.use_sparse(True)``.
 |  
 |  reactant_stoich_coeffs
 |      The array of reactant stoichiometric coefficients. Element ``[k,i]`` of
 |      this array is the reactant stoichiometric coefficient of species ``k`` in
 |      reaction ``i``.
 |      
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      .. versionchanged:: 3.0
 |      
 |          Method was changed to a property in Cantera 3.0.
 |  
 |  reactant_stoich_coeffs3
 |      The array of reactant stoichiometric coefficients. Element ``[k,i]`` of
 |      this array is the reactant stoichiometric coefficient of species ``k`` in
 |      reaction ``i``.
 |      
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      .. deprecated:: 3.0
 |      
 |          Method to be removed after Cantera 3.0. Replaceable by
 |          `Kinetics.reactant_stoich_coeffs`
 |  
 |  reaction_phase_index
 |      The index of the phase where the reactions occur.
 |      
 |      .. deprecated:: 3.0
 |      
 |          After Cantera 3.0, the reacting phase is always the first phase associated
 |          with the Kinetics object. This method will be removed after Cantera 3.1.
 |  
 |  reverse_rate_constants
 |      Reverse rate constants for all reactions.
 |      
 |      The computed values include all temperature-dependent and pressure-dependent
 |      contributions. By default, third-body concentrations are only considered if
 |      they are part of the reaction rate definition; for a legacy implementation that
 |      includes third-body concentrations, see `use_legacy_rate_constants`.
 |  
 |  reverse_rates_of_progress
 |      Reverse rates of progress for the reactions. [kmol/m^3/s] for bulk
 |      phases or [kmol/m^2/s] for surface phases.
 |  
 |  reverse_rates_of_progress_ddC
 |      Calculate derivatives for reverse rates-of-progress with respect to molar
 |      concentration at constant temperature, pressure and mole fractions.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  reverse_rates_of_progress_ddCi
 |      Calculate derivatives for reverse rates-of-progress with respect to species
 |      concentrations at constant temperature, pressure and remaining species
 |      concentrations.
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      Note that for derivatives with respect to :math:`c_i`, all other :math:`c_j`
 |      are held constant.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |      
 |      .. versionadded:: 3.0
 |  
 |  reverse_rates_of_progress_ddP
 |      Calculate derivatives for reverse rates-of-progress with respect to pressure
 |      at constant temperature, molar concentration and mole fractions.
 |  
 |  reverse_rates_of_progress_ddT
 |      Calculate derivatives for reverse rates-of-progress with respect to temperature
 |      at constant pressure, molar concentration and mole fractions.
 |  
 |  reverse_rates_of_progress_ddX
 |      Calculate derivatives for reverse rates-of-progress with respect to species
 |      concentrations at constant temperature, pressure and molar concentration.
 |      For sparse output, set ``ct.use_sparse(True)``.
 |      
 |      Note that for derivatives with respect to :math:`X_i`, all other :math:`X_j`
 |      are held constant, rather than enforcing :math:`\sum X_j = 1`.
 |      
 |      .. warning::
 |      
 |          This property is an experimental part of the Cantera API and
 |          may be changed or removed without notice.
 |  
 |  third_body_concentrations
 |      Effective third-body concentrations used by individual reactions; values
 |      are only defined for reactions involving third-bodies and are set to
 |      not-a-number otherwise.
 |  
 |  ----------------------------------------------------------------------
 |  Methods inherited from cantera.thermo.ThermoPhase:
 |  
 |  __call__(self, /, *args, **kwargs)
 |      Call self as a function.
 |  
 |  add_species(self, species)
 |      Add a new species to this phase. Missing elements will be added
 |      automatically.
 |  
 |  add_species_alias(self, name, alias)
 |      Add the alternate species name ``alias`` for an original species ``name``.
 |  
 |  atomic_weight(self, m)
 |      Atomic weight [kg/kmol] of element ``m``
 |  
 |  element_index(self, element)
 |      The index of element ``element``, which may be specified as a string or
 |      an integer. In the latter case, the index is checked for validity and
 |      returned. If no such element is present, an exception is thrown.
 |  
 |  element_name(self, m)
 |      Name of the element with index ``m``.
 |  
 |  elemental_mass_fraction(self, m)
 |      Get the elemental mass fraction :math:`Z_{\mathrm{mass},m}` of element
 |      :math:`m` as defined by:
 |      
 |      .. math:: Z_{\mathrm{mass},m} = \sum_k \frac{a_{m,k} M_m}{M_k} Y_k
 |      
 |      with :math:`a_{m,k}` being the number of atoms of element :math:`m` in
 |      species :math:`k`, :math:`M_m` the atomic weight of element :math:`m`,
 |      :math:`M_k` the molecular weight of species :math:`k`, and :math:`Y_k`
 |      the mass fraction of species :math:`k`::
 |      
 |          >>> phase.elemental_mass_fraction('H')
 |          1.0
 |      
 |      :param m:
 |          Base element, may be specified by name or by index.
 |  
 |  elemental_mole_fraction(self, m)
 |      Get the elemental mole fraction :math:`Z_{\mathrm{mole},m}` of element
 |      :math:`m` (the number of atoms of element m divided by the total number
 |      of atoms) as defined by:
 |      
 |      .. math:: Z_{\mathrm{mole},m} = \frac{\sum_k a_{m,k} X_k}
 |                                           {\sum_k \sum_j a_{j,k} X_k}
 |      
 |      with :math:`a_{m,k}` being the number of atoms of element :math:`m` in
 |      species :math:`k`, :math:`\sum_j` being a sum over all elements, and
 |      :math:`X_k` being the mole fraction of species :math:`k`::
 |      
 |          >>> phase.elemental_mole_fraction('H')
 |          1.0
 |      
 |      :param m:
 |          Base element, may be specified by name or by index.
 |  
 |  equilibrate(self, XY, solver, rtol, max_steps, max_iter, estimate_equil, log_level)
 |      Set to a state of chemical equilibrium holding property pair
 |      ``XY`` constant.
 |      
 |      :param XY:
 |          A two-letter string, which must be one of the set::
 |      
 |              ['TP','TV','HP','SP','SV','UV']
 |      
 |      :param solver:
 |          Specifies the equilibrium solver to use. May be one of the following:
 |      
 |          * ``'element_potential'`` - a fast solver using the element potential
 |            method
 |          * ``'gibbs'`` - a slower but more robust Gibbs minimization solver
 |          * ``'vcs'`` - the VCS non-ideal equilibrium solver
 |          * ``'auto'`` - The element potential solver will be tried first, then
 |            if it fails the Gibbs solver will be tried.
 |      :param rtol:
 |          The relative error tolerance.
 |      :param max_steps:
 |          The maximum number of steps in composition to take to find a converged
 |          solution.
 |      :param max_iter:
 |          For the Gibbs minimization solver, this specifies the number of
 |          outer iterations on T or P when some property pair other
 |          than TP is specified.
 |      :param estimate_equil:
 |          Integer indicating whether the solver should estimate its own
 |          initial condition. If 0, the initial mole fraction vector in the
 |          `ThermoPhase` object is used as the initial condition. If 1, the
 |          initial mole fraction vector is used if the element abundances are
 |          satisfied. If -1, the initial mole fraction vector is thrown out,
 |          and an estimate is formulated.
 |      :param log_level:
 |          Set to a value greater than 0 to write diagnostic output.
 |  
 |  equivalence_ratio(self, fuel, oxidizer, basis, include_species)
 |      Get the equivalence ratio :math:`\phi` of the current mixture, which is a
 |      conserved quantity. Considers the oxidation of C to CO2, H to H2O
 |      and S to SO2. Other elements are assumed not to participate in oxidation
 |      (that is, N ends up as N2). If fuel and oxidizer are not specified, the
 |      equivalence ratio is computed from the available oxygen and the
 |      required oxygen for complete oxidation:
 |      
 |      .. math:: \phi = \frac{Z_{\mathrm{mole},C} + Z_{\mathrm{mole},S}
 |                + \frac{1}{4}Z_{\mathrm{mole},H}} {\frac{1}{2}Z_{\mathrm{mole},O}}
 |      
 |      where :math:`Z_{\mathrm{mole},e}` is the elemental mole fraction of element
 |      :math:`e`. If the fuel and oxidizer compositions are specified, :math:`\phi` is
 |      computed from:
 |      
 |      .. math:: \phi = \frac{Z}{1-Z}\frac{1-Z_{\mathrm{st}}}{Z_{\mathrm{st}}}
 |      
 |      where :math:`Z` is the Bilger mixture fraction and :math:`Z_{\mathrm{st}}`
 |      the Bilger mixture fraction at stoichiometric conditions.
 |      The ``basis`` determines the composition of fuel and oxidizer:
 |      ``basis='mole'`` (default) means mole fractions, ``basis='mass'`` means
 |      mass fractions. Note that this definition takes all species into account.
 |      In case certain species like inert diluents should be ignored, a
 |      list of species can be provided with ``include_species``. This means that
 |      only these species are considered for the computation of the equivalence
 |      ratio. For more information, see `Python example
 |      <https://cantera.org/examples/python/thermo/equivalenceRatio.py.html>`_ ::
 |      
 |          >>> gas.set_equivalence_ratio(0.5, fuel='CH3:0.5, CH3OH:.5, N2:0.125', oxidizer='O2:0.21, N2:0.79, NO:0.01')
 |          >>> gas.equivalence_ratio(fuel='CH3:0.5, CH3OH:.5, N2:0.125', oxidizer='O2:0.21, N2:0.79, NO:0.01')
 |          0.5
 |      
 |      :param fuel:
 |          Fuel species name or mole/mass fractions as string, array, or dict.
 |      :param oxidizer:
 |          Oxidizer species name or mole/mass fractions as a string, array, or dict.
 |      :param basis:
 |          Determines if ``fuel`` and ``oxidizer`` are given in mole fractions
 |          (``basis="mole"``) or mass fractions (``basis="mass"``)
 |      :param include_species:
 |          List of species names (optional). Only these species are considered for the
 |          computation of the equivalence ratio. By default, all species are considered
 |  
 |  find_isomers(self, comp)
 |      Find species/isomers matching a composition specified by ``comp``.
 |  
 |  mass_fraction_dict(self, threshold)
 |      Return a dictionary giving the mass fraction for each species by name where the
 |      mass fraction is greater than ``threshold``.
 |  
 |  mixture_fraction(self, fuel, oxidizer, basis, element)
 |      Get the mixture fraction of the current mixture in
 |      (kg fuel / (kg oxidizer + kg fuel)). This is a quantity that is conserved after
 |      oxidation. Considers the oxidation of C to CO2, H to H2O and S to SO2. Other
 |      elements are assumed not to participate in oxidation (that is, N ends up as N2).
 |      The ``basis`` determines the composition of fuel and oxidizer:
 |      ``basis="mole"`` (default) means mole fractions, ``basis="mass"`` means mass
 |      fractions. The mixture fraction can be computed from a single element (for
 |      example, carbon with ``element="C"``)
 |      
 |      .. math:: Z_m = \frac{Z_{\mathrm{mass},m}-Z_{\mathrm{mass},m,\mathrm{ox}}}
 |          {Z_{\mathrm{mass},\mathrm{fuel}}-Z_{\mathrm{mass},m,\mathrm{ox}}}
 |      
 |      where :math:`Z_{\mathrm{mass},m}` is the elemental mass fraction of
 |      element :math:`m` in the mixture, and :math:`Z_{\mathrm{mass},m,\mathrm{ox}}`
 |      and :math:`Z_{\mathrm{mass},\mathrm{fuel}}` are the elemental mass fractions of
 |      the oxidizer and fuel, or from the Bilger mixture fraction
 |      (``element="Bilger"``), which considers the elements C, S, H and O
 |      (R. W. Bilger, "Turbulent jet diffusion flames," Prog. Energy Combust. Sci.,
 |      109-131 (1979)). The Bilger mixture fraction is computed by default:
 |      
 |      .. math:: Z_m = Z_{\mathrm{Bilger}} = \frac{\beta-\beta_{\mathrm{ox}}}
 |          {\beta_{\mathrm{fuel}}-\beta_{\mathrm{ox}}}
 |      
 |      with
 |      
 |      .. math:: \beta = 2\frac{Z_C}{M_C}+2\frac{Z_S}{M_S}+\frac{1}{2}\frac{Z_H}{M_H}
 |          - \frac{Z_O}{M_O}
 |      
 |      and :math:`M_m` the atomic weight of element :math:`m`.
 |      For more information, see `Python example
 |      <https://cantera.org/examples/python/thermo/equivalenceRatio.py.html>`_.::
 |      
 |          >>> gas.set_mixture_fraction(0.5, 'CH3:0.5, CH3OH:0.5, N2:0.125', 'O2:0.21, N2:0.79, NO:0.01')
 |          >>> gas.mixture_fraction('CH3:0.5, CH3OH:0.5, N2:0.125', 'O2:0.21, N2:0.79, NO:.01')
 |          0.5
 |      
 |      :param fuel:
 |          Fuel species name or mole/mass fractions as string, array, or dict.
 |      :param oxidizer:
 |          Oxidizer species name or mole/mass fractions as a string, array, or
 |          dict.
 |      :param basis:
 |          Determines if ``fuel`` and ``oxidizer`` are given in mole
 |          fractions (``basis='mole'``) or mass fractions (``basis='mass'``)
 |      :param element:
 |          Computes the mixture fraction from the specified elemental
 |          mass fraction (given by element name or element index) or as
 |          the Bilger mixture fraction (default)
 |  
 |  modify_species(self, k, species)
 |      Modify the thermodynamic data associated with a species. The species name,
 |      elemental composition, and type of thermo parameterization must be unchanged.
 |  
 |  mole_fraction_dict(self, threshold)
 |      Return a dictionary giving the mole fraction for each species by name where the
 |      mole fraction is greater than ``threshold``.
 |  
 |  n_atoms(self, species, element)
 |      Number of atoms of element ``element`` in species ``species``. The element
 |      and species may be specified by name or by index.
 |      
 |      >>> phase.n_atoms('CH4','H')
 |      4
 |  
 |  report(self, show_thermo, threshold)
 |      Generate a report describing the thermodynamic state of this phase. To
 |      print the report to the terminal, simply call the phase object. The
 |      following two statements are equivalent::
 |      
 |      >>> phase()
 |      >>> print(phase.report())
 |  
 |  set_discretized_electron_energy_distribution(self, levels, distribution)
 |      Set electron energy distribution. When this method is used, electron
 |      temperature is calculated from the distribution.
 |      
 |      :param levels:
 |          vector of electron energy levels [eV]
 |      :param distribution:
 |          vector of distribution
 |  
 |  set_equivalence_ratio(self, phi, fuel, oxidizer, basis, *, diluent, fraction)
 |      Set the composition to a mixture of ``fuel`` and ``oxidizer`` at the
 |      specified equivalence ratio ``phi``, holding temperature and pressure
 |      constant. Considers the oxidation of C to CO2, H to H2O and S to SO2.
 |      Other elements are assumed not to participate in oxidation (that is,
 |      N ends up as N2). The ``basis`` determines the fuel and oxidizer
 |      compositions: ``basis='mole'`` means mole fractions (default),
 |      ``basis='mass'`` means mass fractions. The fuel/oxidizer mixture can be
 |      be diluted by a ``diluent`` based on a mixing ``fraction``. The amount of
 |      diluent is quantified as a fraction of fuel, oxidizer or the fuel/oxidizer
 |      mixture. For more information, see `Python example
 |      <https://cantera.org/examples/python/thermo/equivalenceRatio.py.html>`_ ::
 |      
 |          >>> gas.set_equivalence_ratio(0.5, 'CH4', 'O2:1.0, N2:3.76', basis='mole')
 |          >>> gas.mass_fraction_dict()
 |          {'CH4': 0.02837633052851, 'N2': 0.7452356312613, 'O2': 0.22638803821018}
 |          >>> gas.set_equivalence_ratio(1.2, 'NH3:0.8,CO:0.2', 'O2:1', basis='mole')
 |          >>> gas.mass_fraction_dict()
 |          {'CO': 0.14784006249290, 'NH3': 0.35956645545401, 'O2': 0.49259348205308}
 |      
 |      :param phi:
 |          Equivalence ratio
 |      :param fuel:
 |          Fuel species name or mole/mass fractions as string, array, or dict.
 |      :param oxidizer:
 |          Oxidizer species name or mole/mass fractions as a string, array, or dict.
 |      :param basis:
 |          Determines if ``fuel`` and ``oxidizer`` are given in mole
 |          fractions (``basis='mole'``) or mass fractions (``basis='mass'``).
 |      :param diluent:
 |          Optional parameter. Required if dilution is used. Specifies the composition
 |          of the diluent in mole/mass fractions as a string, array or dict.
 |      :param fraction:
 |          Optional parameter. Dilutes the fuel/oxidizer mixture with the diluent
 |          according to ``fraction``. Fraction can refer to the fraction of diluent in
 |          the  mixture (for example ``fraction="diluent:0.7"`` will create a mixture
 |          with 30 % fuel/oxidizer and 70 % diluent), the fraction of fuel in the
 |          mixture (for example ``fraction="fuel:0.1"`` means that the mixture contains
 |          10 % fuel. The amount of oxidizer is determined from the equivalence ratio
 |          and the remaining mixture is the diluent) or fraction of oxidizer in the
 |          mixture (for example ``fraction="oxidizer:0.1"``). The fraction itself is
 |          interpreted as mole or mass fraction based on ``basis``. The diluent is not
 |          considered in the computation of the equivalence ratio. Default is no
 |          dilution or ``fraction=None``. May be given as string or dictionary (for
 |          example ``fraction={"fuel":0.7}``).
 |  
 |  set_mixture_fraction(self, mixture_fraction, fuel, oxidizer, basis)
 |      Set the composition to a mixture of ``fuel`` and ``oxidizer`` at the
 |      specified mixture fraction ``mixture_fraction`` (kg fuel / kg mixture), holding
 |      temperature and pressure constant. Considers the oxidation of C to CO2,
 |      H to H2O and S to SO2. Other elements are assumed not to participate in
 |      oxidation (that is, N ends up as N2). The ``basis`` determines the composition
 |      of fuel and oxidizer: ``basis='mole'`` (default) means mole fractions,
 |      ``basis='mass'`` means mass fractions. For more information, see `Python
 |      example
 |      <https://cantera.org/examples/python/thermo/equivalenceRatio.py.html>`_ ::
 |      
 |          >>> gas.set_mixture_fraction(0.5, 'CH4', 'O2:1.0, N2:3.76')
 |          >>> gas.mass_fraction_dict()
 |          {'CH4': 0.5, 'N2': 0.38350014242997776, 'O2': 0.11649985757002226}
 |          >>> gas.set_mixture_fraction(0.5, {'NH3':0.8, 'CO':0.2}, 'O2:1.0')
 |          >>> gas.mass_fraction_dict()
 |          {'CO': 0.145682068778996, 'NH3': 0.354317931221004, 'O2': 0.5}
 |      
 |      :param mixture_fraction:
 |          Mixture fraction (kg fuel / kg mixture)
 |      :param fuel:
 |          Fuel species name or mole/mass fractions as string, array, or dict.
 |      :param oxidizer:
 |          Oxidizer species name or mole/mass fractions as a string, array, or
 |          dict.
 |      :param basis: determines if ``fuel`` and ``oxidizer`` are given in mole
 |          fractions (``basis='mole'``) or mass fractions (``basis='mass'``)
 |  
 |  set_unnormalized_mass_fractions(self, Y)
 |      Set the mass fractions without normalizing to force ``sum(Y) == 1.0``.
 |      Useful primarily when calculating derivatives with respect to ``Y[k]`` by
 |      finite difference.
 |  
 |  set_unnormalized_mole_fractions(self, X)
 |      Set the mole fractions without normalizing to force ``sum(X) == 1.0``.
 |      Useful primarily when calculating derivatives with respect to ``X[k]``
 |      by finite difference.
 |  
 |  species(self, k)
 |      Return the `Species` object for species ``k``, where ``k`` is either the
 |      species index or the species name. If ``k`` is not specified, a list of
 |      all species objects is returned. Changes to this object do not affect
 |      the `ThermoPhase` or `Solution` object until the `modify_species`
 |      function is called.
 |  
 |  species_index(self, species)
 |      The index of species ``species``, which may be specified as a string or
 |      an integer. In the latter case, the index is checked for validity and
 |      returned. If no such species is present, an exception is thrown.
 |  
 |  species_name(self, k)
 |      Name of the species with index ``k``.
 |  
 |  stoich_air_fuel_ratio(self, fuel, oxidizer, basis)
 |      Get the stoichiometric air to fuel ratio (kg oxidizer / kg fuel). Considers the
 |      oxidation of C to CO2, H to H2O and S to SO2. Other elements are assumed
 |      not to participate in oxidation (that is, N ends up as N2).
 |      The ``basis`` determines the composition of fuel and oxidizer: ``basis='mole'`` (default)
 |      means mole fractions, ``basis='mass'`` means mass fractions::
 |      
 |          >>> gas.set_mixture_fraction(0.5, 'CH3:0.5, CH3OH:.5, N2:0.125', 'O2:0.21, N2:0.79, NO:0.01')
 |          >>> gas.stoich_air_fuel_ratio('CH3:0.5, CH3OH:.5, N2:0.125', 'O2:0.21, N2:0.79, NO:0.01')
 |          8.148040722239438
 |      
 |      :param fuel:
 |          Fuel species name or mole/mass fractions as string, array, or dict.
 |      :param oxidizer:
 |          Oxidizer species name or mole/mass fractions as a string, array, or
 |          dict.
 |      :param basis:
 |          Determines if ``fuel`` and ``oxidizer`` are given in mole
 |          fractions (``basis='mole'``) or mass fractions (``basis='mass'``)
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from cantera.thermo.ThermoPhase:
 |  
 |  DP
 |      Get/Set density [kg/m^3] and pressure [Pa].
 |  
 |  DPX
 |      Get/Set density [kg/m^3], pressure [Pa], and mole fractions.
 |  
 |  DPY
 |      Get/Set density [kg/m^3], pressure [Pa], and mass fractions.
 |  
 |  HP
 |      Get/Set enthalpy [J/kg or J/kmol] and pressure [Pa].
 |  
 |  HPX
 |      Get/Set enthalpy [J/kg or J/kmol], pressure [Pa] and mole fractions.
 |  
 |  HPY
 |      Get/Set enthalpy [J/kg or J/kmol], pressure [Pa] and mass fractions.
 |  
 |  P
 |      Pressure [Pa].
 |  
 |  P_sat
 |      Saturation pressure [Pa] at the current temperature.
 |  
 |  Pe
 |      Get electron Pressure [Pa].
 |  
 |  SP
 |      Get/Set entropy [J/kg/K or J/kmol/K] and pressure [Pa].
 |  
 |  SPX
 |      Get/Set entropy [J/kg/K or J/kmol/K], pressure [Pa], and mole fractions.
 |  
 |  SPY
 |      Get/Set entropy [J/kg/K or J/kmol/K], pressure [Pa], and mass fractions.
 |  
 |  SV
 |      Get/Set entropy [J/kg/K or J/kmol/K] and specific volume [m^3/kg or
 |      m^3/kmol].
 |  
 |  SVX
 |      Get/Set entropy [J/kg/K or J/kmol/K], specific volume [m^3/kg or
 |      m^3/kmol], and mole fractions.
 |  
 |  SVY
 |      Get/Set entropy [J/kg/K or J/kmol/K], specific volume [m^3/kg or
 |      m^3/kmol], and mass fractions.
 |  
 |  T
 |      Temperature [K].
 |  
 |  TD
 |      Get/Set temperature [K] and density [kg/m^3 or kmol/m^3].
 |  
 |  TDX
 |      Get/Set temperature [K], density [kg/m^3 or kmol/m^3], and mole
 |      fractions.
 |  
 |  TDY
 |      Get/Set temperature [K] and density [kg/m^3 or kmol/m^3], and mass
 |      fractions.
 |  
 |  TP
 |      Get/Set temperature [K] and pressure [Pa].
 |  
 |  TPX
 |      Get/Set temperature [K], pressure [Pa], and mole fractions.
 |  
 |  TPY
 |      Get/Set temperature [K], pressure [Pa], and mass fractions.
 |  
 |  T_sat
 |      Saturation temperature [K] at the current pressure.
 |  
 |  Te
 |      Get/Set electron Temperature [K].
 |  
 |  UV
 |      Get/Set internal energy [J/kg or J/kmol] and specific volume
 |      [m^3/kg or m^3/kmol].
 |  
 |  UVX
 |      Get/Set internal energy [J/kg or J/kmol], specific volume
 |      [m^3/kg or m^3/kmol], and mole fractions.
 |  
 |  UVY
 |      Get/Set internal energy [J/kg or J/kmol], specific volume
 |      [m^3/kg or m^3/kmol], and mass fractions.
 |  
 |  X
 |      Get/Set the species mole fractions. Can be set as an array, as a dictionary,
 |      or as a string. Always returns an array::
 |      
 |          >>> phase.X = [0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5]
 |          >>> phase.X = {'H2':0.1, 'O2':0.4, 'AR':0.5}
 |          >>> phase.X = 'H2:0.1, O2:0.4, AR:0.5'
 |          >>> phase.X
 |          array([0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5])
 |  
 |  Y
 |      Get/Set the species mass fractions. Can be set as an array, as a dictionary,
 |      or as a string. Always returns an array::
 |      
 |          >>> phase.Y = [0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5]
 |          >>> phase.Y = {'H2':0.1, 'O2':0.4, 'AR':0.5}
 |          >>> phase.Y = 'H2:0.1, O2:0.4, AR:0.5'
 |          >>> phase.Y
 |          array([0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5])
 |  
 |  activities
 |      Array of nondimensional activities. Returns either molar or molal
 |      activities depending on the convention of the thermodynamic model.
 |  
 |  activity_coefficients
 |      Array of nondimensional, molar activity coefficients.
 |  
 |  atomic_weights
 |      Array of atomic weight [kg/kmol] for each element in the mixture.
 |  
 |  basis
 |      Determines whether intensive thermodynamic properties are treated on a
 |      ``mass`` (per kg) or ``molar`` (per kmol) basis. This affects the values
 |      returned by the properties `h`, `u`, `s`, `g`, `v`, `density`, `cv`,
 |      and `cp`, as well as the values used with the state-setting properties
 |      such as `HPX` and `UV`.
 |  
 |  case_sensitive_species_names
 |      Enforce case-sensitivity for look up of species names
 |  
 |  charges
 |      Array of species charges [elem. charge].
 |  
 |  chemical_potentials
 |      Array of species chemical potentials [J/kmol].
 |  
 |  concentrations
 |      Get/Set the species concentrations. Units are kmol/m^3 for bulk phases, kmol/m^2
 |      for surface phases, and kmol/m for edge phases.
 |  
 |  cp
 |      Heat capacity at constant pressure [J/kg/K or J/kmol/K] depending
 |      on `basis`.
 |  
 |  cp_mass
 |      Specific heat capacity at constant pressure [J/kg/K].
 |  
 |  cp_mole
 |      Molar heat capacity at constant pressure [J/kmol/K].
 |  
 |  critical_density
 |      Critical density [kg/m^3 or kmol/m^3] depending on `basis`.
 |  
 |  critical_pressure
 |      Critical pressure [Pa].
 |  
 |  critical_temperature
 |      Critical temperature [K].
 |  
 |  cv
 |      Heat capacity at constant volume [J/kg/K or J/kmol/K] depending on
 |      `basis`.
 |  
 |  cv_mass
 |      Specific heat capacity at constant volume [J/kg/K].
 |  
 |  cv_mole
 |      Molar heat capacity at constant volume [J/kmol/K].
 |  
 |  density
 |      Density [kg/m^3 or kmol/m^3] depending on `basis`.
 |  
 |  density_mass
 |      (Mass) density [kg/m^3].
 |  
 |  density_mole
 |      Molar density [kmol/m^3].
 |  
 |  electric_potential
 |      Get/Set the electric potential [V] for this phase.
 |  
 |  electrochemical_potentials
 |      Array of species electrochemical potentials [J/kmol].
 |  
 |  electron_energy_distribution
 |      Electron energy distribution
 |  
 |  electron_energy_distribution_type
 |      Electron energy distribution type
 |  
 |  electron_energy_levels
 |      Electron energy levels [eV]
 |  
 |  element_names
 |      A list of all the element names.
 |  
 |  enthalpy_mass
 |      Specific enthalpy [J/kg].
 |  
 |  enthalpy_mole
 |      Molar enthalpy [J/kmol].
 |  
 |  entropy_mass
 |      Specific entropy [J/kg/K].
 |  
 |  entropy_mole
 |      Molar entropy [J/kmol/K].
 |  
 |  g
 |      Gibbs free energy [J/kg or J/kmol] depending on `basis`.
 |  
 |  gibbs_mass
 |      Specific Gibbs free energy [J/kg].
 |  
 |  gibbs_mole
 |      Molar Gibbs free energy [J/kmol].
 |  
 |  h
 |      Enthalpy [J/kg or J/kmol] depending on `basis`.
 |  
 |  has_phase_transition
 |      Returns true if the phase represents a substance with phase transitions
 |  
 |  int_energy_mass
 |      Specific internal energy [J/kg].
 |  
 |  int_energy_mole
 |      Molar internal energy [J/kmol].
 |  
 |  is_compressible
 |      Returns true if the density of the phase is an independent variable defining
 |      the thermodynamic state of a substance
 |  
 |  is_pure
 |      Returns true if the phase represents a pure (fixed composition) substance
 |  
 |  isothermal_compressibility
 |      Isothermal compressibility [1/Pa].
 |  
 |  isotropic_shape_factor
 |      Shape factor of isotropic-velocity distribution for electron energy
 |  
 |  max_temp
 |      Maximum temperature for which the thermodynamic data for the phase are
 |      valid.
 |  
 |  mean_electron_energy
 |      Mean electron energy [eV]
 |  
 |  mean_molecular_weight
 |      The mean molecular weight (molar mass) [kg/kmol].
 |  
 |  min_temp
 |      Minimum temperature for which the thermodynamic data for the phase are
 |      valid.
 |  
 |  molecular_weights
 |      Array of species molecular weights (molar masses) [kg/kmol].
 |  
 |  n_electron_energy_levels
 |      Number of electron energy levels
 |  
 |  n_elements
 |      Number of elements.
 |  
 |  n_selected_species
 |      Number of species selected for output (by slicing of Solution object)
 |  
 |  n_species
 |      Number of species.
 |  
 |  normalize_electron_energy_distribution_enabled
 |      Automatically normalize electron energy distribution
 |  
 |  partial_molar_cp
 |      Array of species partial molar specific heat capacities at constant
 |      pressure [J/kmol/K].
 |  
 |  partial_molar_enthalpies
 |      Array of species partial molar enthalpies [J/kmol].
 |  
 |  partial_molar_entropies
 |      Array of species partial molar entropies [J/kmol/K].
 |  
 |  partial_molar_int_energies
 |      Array of species partial molar internal energies [J/kmol].
 |  
 |  partial_molar_volumes
 |      Array of species partial molar volumes [m^3/kmol].
 |  
 |  phase_of_matter
 |      Get the thermodynamic phase (gas, liquid, etc.) at the current conditions.
 |  
 |  quadrature_method
 |      Quadrature method
 |  
 |  reference_pressure
 |      Reference state pressure [Pa].
 |  
 |  s
 |      Entropy [J/kg/K or J/kmol/K] depending on `basis`.
 |  
 |  sound_speed
 |      Speed of sound [m/s].
 |  
 |  species_names
 |      A list of all the species names.
 |  
 |  standard_concentration_units
 |      Get standard concentration units for this phase.
 |  
 |  standard_cp_R
 |      Array of nondimensional species standard-state specific heat capacities
 |      at constant pressure at the current temperature and pressure.
 |  
 |  standard_enthalpies_RT
 |      Array of nondimensional species standard-state enthalpies at the
 |      current temperature and pressure.
 |  
 |  standard_entropies_R
 |      Array of nondimensional species standard-state entropies at the
 |      current temperature and pressure.
 |  
 |  standard_gibbs_RT
 |      Array of nondimensional species standard-state Gibbs free energies at
 |      the current temperature and pressure.
 |  
 |  standard_int_energies_RT
 |      Array of nondimensional species standard-state internal energies at the
 |      current temperature and pressure.
 |  
 |  state
 |      Get/Set the full thermodynamic state as a single array, arranged as
 |      [temperature, density, mass fractions] for most phases. Useful mainly
 |      in cases where it is desired to store many states in a multidimensional
 |      array.
 |  
 |  state_size
 |      Return size of vector defining internal state of the phase.
 |  
 |  thermal_expansion_coeff
 |      Thermal expansion coefficient [1/K].
 |  
 |  thermo_model
 |      Return thermodynamic model describing phase.
 |  
 |  u
 |      Internal energy in [J/kg or J/kmol].
 |  
 |  v
 |      Specific volume [m^3/kg or m^3/kmol] depending on `basis`.
 |  
 |  volume_mass
 |      Specific volume [m^3/kg].
 |  
 |  volume_mole
 |      Molar volume [m^3/kmol].
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes inherited from cantera.thermo.ThermoPhase:
 |  
 |  __pyx_vtable__ = <capsule object NULL>
 |  
 |  ----------------------------------------------------------------------
 |  Methods inherited from cantera.solutionbase._SolutionBase:
 |  
 |  __copy__(self)
 |  
 |  __del__(self)
 |  
 |  __getitem__(self, key, /)
 |      Return self[key].
 |  
 |  __getstate__(self)
 |      Save complete information of the current phase for pickling.
 |  
 |  __setstate__(self, pkl)
 |      Restore Solution from pickled information.
 |  
 |  clear_user_data(self)
 |      Clear all saved input data, so that the data given by `input_data` or
 |      `write_yaml` will only include values generated by Cantera based on the
 |      current object state.
 |  
 |  clear_user_header(self)
 |      Clear all saved header data, so that the data given by `input_header` or
 |      `write_yaml` will only include values generated by Cantera based on the
 |      current object state.
 |  
 |  update_user_data(self, data)
 |      Add the contents of the provided `dict` as additional fields when generating
 |      YAML phase definition files with `write_yaml` or in the data returned by
 |      `input_data`. Existing keys with matching names are overwritten.
 |  
 |  update_user_header(self, data)
 |      Add the contents of the provided `dict` as additional top-level YAML fields
 |      when generating files with `write_yaml` or in the data returned by
 |      `input_header`. Existing keys with matching names are overwritten.
 |  
 |  write_chemkin(self, mechanism_path, thermo_path, transport_path, sort_species, sort_elements, overwrite)
 |      Write this `~cantera.Solution` instance to one or more Chemkin-format files.
 |      See the documentation for `cantera.yaml2ck.convert` for information about the
 |      arguments to this function.
 |  
 |  write_yaml(self, filename, phases, units, precision, skip_user_defined, header)
 |      Write the definition for this phase, any additional phases specified,
 |      and their species and reactions to the specified file.
 |      
 |      :param filename:
 |          The name of the output file; if ``None``, a YAML string is returned
 |      :param phases:
 |          Additional ThermoPhase / Solution objects to be included in the
 |          output file
 |      :param units:
 |          A `UnitSystem` object or dictionary of the units to be used for
 |          each dimension.
 |          See `YamlWriter.output_units <cantera.YamlWriter.output_units>`.
 |      :param precision:
 |          For output floating point values, the maximum number of digits to
 |          the right of the decimal point. The default is 15 digits.
 |      :param skip_user_defined:
 |          If `True`, user-defined fields which are not used by Cantera will
 |          be stripped from the output. These additional contents can also be
 |          controlled using the `update_user_data` and `clear_user_data` functions.
 |      :param header:
 |          If `True`, fields of the `input_header` will be added to the YAML header;
 |          note that fields name ``generator``, ``cantera-version``, ``git-commit``
 |          and ``date`` are reserved, which means that any existing data are
 |          replaced by automatically generated content when the file is written.
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from cantera.solutionbase._SolutionBase:
 |  
 |  composite
 |      Returns tuple of thermo/kinetics/transport models associated with
 |      this SolutionBase object.
 |  
 |  input_data
 |      Get input data corresponding to the current state of this Solution,
 |      along with any user-specified data provided with its input (YAML)
 |      definition.
 |  
 |  input_header
 |      Retrieve input header data not associated with the current state of this
 |      Solution, which corresponds to fields at the root level of the YAML input
 |      that are not required for the instantiation of Cantera objects.
 |  
 |  name
 |      The name assigned to this object. The default value corresponds
 |      to the YAML input file phase entry.
 |  
 |  selected_species
 |      Get/set the set of species that are included when returning results that have
 |      a value for each species, such as `species_names <cantera.ThermoPhase.species_names>`,
 |      `partial_molar_enthalpies <cantera.ThermoPhase.partial_molar_enthalpies>`, or
 |      `net_production_rates <cantera.Kinetics.net_production_rates>`. The list of
 |      selected species can be set by name or index. This property returns the
 |      species by index.::
 |      
 |         >>> gas.selected_species = ["H2", "O2"]
 |         >>> print(gas.molecular_weights)
 |         [ 2.016 31.998]
 |      
 |      This method is often used implicitly by using an indexing expression on a
 |      `Solution` object::
 |      
 |         >>> print(gas["H2", "O2"].molecular_weights)
 |         [ 2.016 31.998]
 |  
 |  source
 |      The source of this object (such as a file name).

You can use several functions to define the state of your gas, that is to say :

  • gas.TP (Temperature Pressure)
  • gas.TD (Temperature Density)
  • gas.HP (Enthalpy Pressure)
  • gas.UV (Specific Internal Energy, Specific Volume)
  • gas.SP (Entropy Pressure)
  • gas.SV (Entropy Specific Volume).
In [10]:
gas.TP = 500, 101325

Wrong method

Here, we chose to define the molar fraction of the gas directly by the following :

In [4]:
gas.X = {'CH4':1, 'O2':2, 'N2':7.52}
In [5]:
print(gas())
  gri30:

       temperature   300 K
          pressure   7392.2 Pa
           density   0.081894 kg/m^3
  mean mol. weight   27.633 kg/kmol
   phase of matter   gas

                          1 kg             1 kmol     
                     ---------------   ---------------
          enthalpy       -2.5459e+05       -7.0351e+06  J
   internal energy       -3.4485e+05       -9.5295e+06  J
           entropy            8035.4        2.2205e+05  J/K
    Gibbs function       -2.6652e+06       -7.3649e+07  J
 heat capacity c_p            1077.3             29770  J/K
 heat capacity c_v            776.45             21456  J/K

                      mass frac. Y      mole frac. X     chem. pot. / RT
                     ---------------   ---------------   ---------------
                O2           0.22014           0.19011           -28.952
               CH4          0.055187          0.095057           -57.294
                N2           0.72467           0.71483           -25.987
     [  +50 minor]                 0                 0  

None

What do you notice here ? Look at the pressure : it is not the same than what has been defined above. You should never define pressure and temperature and call the command "gas.X" afterwards. Below are explained correct methods to set the case correctly.

First method

In [6]:
gas.TPX = 500, 101325, {'CH4':1, 'O2':2, 'N2':7.52}
In [7]:
print(gas())
  gri30:

       temperature   500 K
          pressure   1.0132e+05 Pa
           density   0.67352 kg/m^3
  mean mol. weight   27.633 kg/kmol
   phase of matter   gas

                          1 kg             1 kmol     
                     ---------------   ---------------
          enthalpy            -33317       -9.2066e+05  J
   internal energy       -1.8376e+05       -5.0779e+06  J
           entropy            7811.5        2.1586e+05  J/K
    Gibbs function       -3.9391e+06       -1.0885e+08  J
 heat capacity c_p            1140.4             31514  J/K
 heat capacity c_v            839.53             23199  J/K

                      mass frac. Y      mole frac. X     chem. pot. / RT
                     ---------------   ---------------   ---------------
                O2           0.22014           0.19011            -26.74
               CH4          0.055187          0.095057           -43.238
                N2           0.72467           0.71483           -23.767
     [  +50 minor]                 0                 0  

None

Second method

Here, we will set an equivalence ratio equal to unity with a mix of fuel (CH4) and oxidizer (air), which is doing the same as above.

In [8]:
gas.TP = 500, 101325
In [9]:
gas.set_equivalence_ratio(1, 'CH4: 1', 'O2:1.0, N2:3.76')
In [10]:
print(gas())
  gri30:

       temperature   500 K
          pressure   1.0132e+05 Pa
           density   0.67352 kg/m^3
  mean mol. weight   27.633 kg/kmol
   phase of matter   gas

                          1 kg             1 kmol     
                     ---------------   ---------------
          enthalpy            -33317       -9.2066e+05  J
   internal energy       -1.8376e+05       -5.0779e+06  J
           entropy            7811.5        2.1586e+05  J/K
    Gibbs function       -3.9391e+06       -1.0885e+08  J
 heat capacity c_p            1140.4             31514  J/K
 heat capacity c_v            839.53             23199  J/K

                      mass frac. Y      mole frac. X     chem. pot. / RT
                     ---------------   ---------------   ---------------
                O2           0.22014           0.19011            -26.74
               CH4          0.055187          0.095057           -43.238
                N2           0.72467           0.71483           -23.767
     [  +50 minor]                 0                 0  

None

Additional informations

In [11]:
print(gas.species_names)
['H2', 'H', 'O', 'O2', 'OH', 'H2O', 'HO2', 'H2O2', 'C', 'CH', 'CH2', 'CH2(S)', 'CH3', 'CH4', 'CO', 'CO2', 'HCO', 'CH2O', 'CH2OH', 'CH3O', 'CH3OH', 'C2H', 'C2H2', 'C2H3', 'C2H4', 'C2H5', 'C2H6', 'HCCO', 'CH2CO', 'HCCOH', 'N', 'NH', 'NH2', 'NH3', 'NNH', 'NO', 'NO2', 'N2O', 'HNO', 'CN', 'HCN', 'H2CN', 'HCNN', 'HCNO', 'HOCN', 'HNCO', 'NCO', 'N2', 'AR', 'C3H7', 'C3H8', 'CH2CHO', 'CH3CHO']
In [12]:
print(gas.species_index('CO2'))
15

Other informations concerning functions associated to the thermodynamic properties of the gas object can be found on the help function or on the following link :
https://cantera.org/documentation/docs-3.0/sphinx/html/matlab/thermodynamics.html#thermodynamic-properties

4. Kinetic state of the gas

As well as for the thermodynamic state of the gas, the kinetic state can be found at the following link :
https://cantera.org/documentation/docs-3.0/sphinx/html/matlab/kinetics.html#chemical-kinetics

In [13]:
print(gas.net_production_rates)
[ 0.00000000e+00  3.47828405e-33  9.56903426e-36 -1.90362726e-19
  0.00000000e+00  0.00000000e+00  1.90362726e-19  0.00000000e+00
  0.00000000e+00  0.00000000e+00  0.00000000e+00  0.00000000e+00
  1.90362726e-19 -1.90362726e-19  0.00000000e+00  0.00000000e+00
  0.00000000e+00  0.00000000e+00  0.00000000e+00  0.00000000e+00
  0.00000000e+00  0.00000000e+00  0.00000000e+00  0.00000000e+00
  0.00000000e+00  0.00000000e+00  0.00000000e+00  0.00000000e+00
  0.00000000e+00  0.00000000e+00  0.00000000e+00  0.00000000e+00
  0.00000000e+00  0.00000000e+00  9.36554007e-42  0.00000000e+00
  0.00000000e+00  9.56903407e-36  0.00000000e+00  0.00000000e+00
  0.00000000e+00  0.00000000e+00  0.00000000e+00  0.00000000e+00
  0.00000000e+00  0.00000000e+00  0.00000000e+00 -9.56904343e-36
  0.00000000e+00  0.00000000e+00  0.00000000e+00  0.00000000e+00
  0.00000000e+00]

Here, this is nearly zero as no reaction has occured in the mix.

5. Transport properties

In [14]:
print(gas.binary_diff_coeffs)
[[3.42125932e-04 5.16149564e-04 2.56085897e-04 ... 1.13601915e-04
  1.41676148e-04 1.41603612e-04]
 [5.16149564e-04 7.60016231e-04 4.32829554e-04 ... 1.70066300e-04
  2.14491230e-04 2.14435073e-04]
 [2.56085897e-04 4.32829554e-04 1.20461676e-04 ... 4.41954859e-05
  5.49580609e-05 5.47874219e-05]
 ...
 [1.13601915e-04 1.70066300e-04 4.41954859e-05 ... 1.62051724e-05
  1.83687401e-05 1.82620858e-05]
 [1.41676148e-04 2.14491230e-04 5.49580609e-05 ... 1.83687401e-05
  2.10821066e-05 2.09611620e-05]
 [1.41603612e-04 2.14435073e-04 5.47874219e-05 ... 1.82620858e-05
  2.09611620e-05 2.08395155e-05]]

Default value uses the default transport specified in the phase definition. gas.binary_diff_coeffs works because the transport model is specified and defined as "mixture-averaged".

In [15]:
print(gas.transport_model)
mixture-averaged

Here, with the version we used at CERFACS, four types of transport are available. The four differs in the following way :

  • multicomponent is the most complicated and detailed version, it uses each diffusion coefficient $D_{kj}$ to represent the interaction between each species (k being a species and j another one).
  • mixture-averaged is the most used version in Cantera as it allows the user to approximate results without losing too much precision. The approximation made is that every species has one interaction with the whole mix following the rule : $D_{km} = \frac{1-Y_k}{\sum_{j\ne k}^{K} \frac{X_j}{Djk}}$.
  • AVBP which is the transport used to compare results with AVBP solver used at cerfacs (this transport is not included in the normal version). This supposes a constant Schmidt number ( $Sc = \frac{\rho}{\mu D_{km}}$, $\rho$ being the density and $\mu$ the viscosity ) for all the species and $D_{km}$ is guessed from this relation.
  • unity-Lewis-number which implements the unity Lewis number approximation for the mixture-averaged species diffusion coefficients.

This types of transport are used in the yaml file, as you will see in a minute.

Conclusion

The purpose of this part was to explain :

  • how one can set up the thermodynamic state of a gas for a computation
  • how one will be able to print interesting data from the gaseous object
    In the next part, we will focus on the object used to created the cantera gas object : the yaml file.

Things to retain from the first tutorial :

  • you should always import Cantera at the beginning of your file.
  • the solution is imported from a yaml file.
  • you should set the thermodynamic state and the amount of species of your gas before starting any computation.

Appendix : The data files

a. Creation of the data file from CHEMKIN files

The information required to compute the previous quantities were specified in the .yaml file, also labeled mechanism file or data file. In fact, Cantera no longer supports a data file format with the extension '.cti' or '.xml'.
For the following part, you can open a yaml script in the Mechanisms folder (for instance the gri30 mechanism) to have a visual idea of what is a yaml file.

Cantera simulations will always involve one or more phases of matter. Depending on the calculation being performed, it may be necessary to evaluate thermodynamic properties, but also transport properties, and/or homogeneous reaction rates for the phase(s) present. In problems with multiple phases, the properties of the interfaces between phases, and the heterogeneous reaction rates at these interfaces, may also be required.

https://cantera.org/science/phase-thermo.html

Before the properties can be evaluated, each phase must be defined, meaning that the models used to compute its properties and reaction rates must be specified, along with any parameters the models require. For example, a solid phase might be defined as being incompressible, with a specified density and composition. A gaseous phase for a combustion simulation might be defined as an ideal gas consisting of a mixture of many species that react with one another via a specified set of reactions.
If phases contain multiple species and reactions, as it is often the case in combustion application, a large amount of data is required to define it, since the contribution of each species to the thermodynamic and transport properties must be specified, and rate information must be given for each reaction. Rather than defining this information via an application program, the Cantera approach is to put the phase and interface definitions in a text file that can be called from and read by an application program - or a script.

In this tutorial, we will review what must be included in such 'data files', or 'mechanism files', and provide guidelines on how to write them to define phases and interfaces to use them in Cantera simulations. We will start by a review of some basic writing rules, followed by a discussion on how they are processed, and of how errors are handled. We will work with examples in the last sections.

To be able to translate the files from Chemkin (mechanism file, thermo database and transport database) to yaml format, it is necessary to use the command ck2yaml.
The following command should be executed on a terminal:

ck2yaml --input=./CK2YAML/mech.inp --thermo=./CK2YAML/therm.dat --transport=./CK2YAML/tran.dat

Now, if you look into the folder CK2YAML, the data file mechanism should be created.

You can also convert the files from cti to cantera (data file), using the command cti2yaml:

cti2yaml ./CTI2YAML/gri30.cti

b. The .yaml file

The typical shape of a **yaml** file will be the following :

UNITS DIRECTIVE

Phase & Interface data

PHASE ENTRIES(name, thermo, elements, species, kinetics, reactions, transport, state*, options)
INTERFACE ENTRIES(name, elements, species, reactions, phases, site_density, state*)

Species & Elements data

ELEMENT ENTRIES(symbol, atomic_mass) SPECIES ENTRIES(name, composition, thermo ,transport, note, size, charge)

Reaction data

REACTION ENTRIES(equation, type, rate-constant, efficiencies, options)

A data file consists of entries and directives, both of which have a syntax much like functions.

A directive will tell the code how the entry parameters are to be interpreted, such as what is the default unit system, or how certain errors should be handled. For example :

units: {length: cm, quantity: mol, activation-energy: cal/mol}

An entry defines an object, for example, a reaction or a species. Entries have fields, that can be assigned values. Take the definition of the argon species :

  • name: AR composition: {Ar: 1} thermo: model: NASA7 temperature-ranges: [300.0, 1000.0, 5000.0] data:
    • [2.5, 0.0, 0.0, 0.0, 0.0, -745.375, 4.366]
    • [2.5, 0.0, 0.0, 0.0, 0.0, -745.375, 4.366] transport: model: gas geometry: atom diameter: 3.33 well-depth: 136.5 note: '120186' </code>

Its fields are its name, compositions, thermodynamic, transport and notes properties.
The syntax is < field name > : < value > , and the fields can be specified on one line or extended across several to be read more easily, as it was the case in the previous example. Some fields are required, otherwise processing the file will abort and an error message will be printed.
As can be seen on this example, the transport field for instance has several subfields (model, geometry, diameter, well-depth). A field can specify a model or a large group of parameters.

A cti file can support four different types of reactions :

  • classic reactions (classic Arrhenius defined like equations) which does not need a specified type.
  • three-body reactions three-body (reactions involving another species which can be a probability of being one species or another)
  • falloff reaction falloff (three-body reactions whose rates k are depending on the concentration of the three-body)
  • pressure dependent reaction pressure-dependent-Arrhenius (set of several Arrhenius parameters for specific pressures with a logarithmic interpolation inbetween)

If you want more documentation about the reactions in cantera, please follow the link below :
https://cantera.org/documentation/docs-3.0/sphinx/html/yaml/reactions.html

NB : The following link will provide you other information about the species data if you are interested in knowing more about it :
https://cantera.org/science/species-thermo.html