Skip to main content
`Ctrl`+`K`

# Chemical Kinetics

## Kinetics Managers

### Kinetics

class cantera.Kinetics

  Bases: `_SolutionBase`

  Instances of class `Kinetics` are responsible for evaluating reaction rates of progress, species production rates, and other quantities pertaining to a reaction mechanism.

  add_reaction(rxn)

    Add a new reaction to this phase.

  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.

    New in version 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 \(X_i\), all other \(X_j\) are held constant, rather than enforcing \(\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.

    New in version 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 \(X_i\), all other \(X_j\) are held constant, rather than enforcing \(\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 \(c_i\), all other \(c_j\) are held constant.

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

    New in version 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 \(X_i\), all other \(X_j\) are held constant, rather than enforcing \(\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_index(species, phase=0)

    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(k)

    Name of the species with index `k` in the arrays returned by methods of class `Kinetics`.

  kinetics_species_names

    A list of all species names, corresponding to the arrays returned by methods of class `Kinetics`.

  modify_reaction(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(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`.

  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.

    New in version 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 \(X_i\), all other \(X_j\) are held constant, rather than enforcing \(\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 \(c_i\), all other \(c_j\) are held constant.

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

    New in version 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 \(X_i\), all other \(X_j\) are held constant, rather than enforcing \(\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_coeff(k_spec, i_reaction)

    The stoichiometric coefficient of species `k_spec` as a product in reaction `i_reaction`.

  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)`.

    Changed in version 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 since version 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_coeff(k_spec, i_reaction)

    The stoichiometric coefficient of species `k_spec` as a reactant in reaction `i_reaction`.

  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)`.

    Changed in version 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 since version 3.0: Method to be removed after Cantera 3.0. Replaceable by `Kinetics.reactant_stoich_coeffs`

  reaction(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(indices=None)

    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`.

  reaction_phase_index

    The index of the phase where the reactions occur.

    Deprecated since version 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.

  reactions()

    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.

  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 \(c_i\), all other \(c_j\) are held constant.

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

    New in version 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 \(X_i\), all other \(X_j\) are held constant, rather than enforcing \(\sum X_j = 1\).

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

  set_multiplier(value, i_reaction=-1)

    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`.

  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.

### InterfaceKinetics

class cantera.InterfaceKinetics

  Bases: `Kinetics`

  A kinetics manager for heterogeneous reaction mechanisms. The reactions are assumed to occur at an interface between bulk phases.

  advance_coverages(dt, rtol=1e-07, atol=1e-14, max_step_size=0.0, max_steps=20000, max_error_test_failures=7)

    This method carries out a time-accurate advancement of the surface coverages for a specified amount of time.

  advance_coverages_to_steady_state()

    This method advances the surface coverages to steady state.

  get_creation_rates(phase)

    Creation rates for each species in phase `phase`. Use the `creation_rates` property to get the creation rates for species in all phases.

  get_destruction_rates(phase)

    Destruction rates for each species in phase `phase`. Use the `destruction_rates` property to get the destruction rates for species in all phases.

  get_net_production_rates(phase)

    Net production rates for each species in phase `phase`. Use the `net_production_rates` property to get the net production rates for species in all phases.

  interface_current(phase)

    The interface current is useful when charge transfer reactions occur at an interface. It is defined here as the net positive charge entering the phase `phase` (Units: A/m^2 for a surface, A/m for an edge reaction).

  phase_index(phase)

    Get the index of the phase `phase`, where `phase` may specified using the phase object, the name, or the index itself.

  write_yaml(filename, phases=None, units=None, precision=None, skip_user_defined=None)

    See `_SolutionBase.write_yaml`.

## Reactions

These classes contain the definition of a single reaction, independent of a specific `Kinetics` object. Reaction rate evaluation is handled by `ReactionRate` objects.

### Reaction

class cantera.Reaction

  Bases: `object`

  A class which stores data about a reaction and its rate parameterization so that it can be added to a `Kinetics` object.

  Parameters:

    - reactants – Value used to set `reactants`

    - products – Value used to set `products`

    - rate –

      The rate parameterization for the reaction, given as one of the following:

      > - a `ReactionRate` object

      > - a `dict` containing the parameters needed to construct a `ReactionRate` object, with keys corresponding to the YAML format

      > - a `dict` containing Arrhenius parameters (`A`, `b`, and `Ea`)

    - equation – The reaction equation, used to set the reactants and products if values for those arguments are not provided.

  Examples:

      R = ct.Reaction({"O": 1, "H2": 1}, {"H": 1, "OH": 1},
                      ct.ArrheniusRate(38.7, 2.7, 26191840.0))
      R = ct.Reaction(equation="O + H2 <=> H + OH",
                      rate={"A": 38.7, "b": 2.7, "Ea": 26191840.0})
      R = ct.Reaction(equation="HO2 <=> OH + O", rate=ChebyshevRate(...))

  The static method `list_from_file` can be used to create a list of `Reaction` objects from existing definitions in the YAML format. The following will produce a list of the 325 reactions which make up the GRI 3.0 mechanism:

      R = ct.Reaction.list_from_file("gri30.yaml", gas)

  where `gas` is a `Solution` object with the appropriate thermodynamic model, which is the `ideal-gas` model in this case.

  The static method `list_from_yaml` can be used to create lists of `Reaction` objects from a YAML list:

      rxns = '''
        - equation: O + H2 <=> H + OH
          rate-constant: {A: 3.87e+04, b: 2.7, Ea: 6260.0}
        - equation: O + HO2 <=> OH + O2
          rate-constant: {A: 2.0e+13, b: 0.0, Ea: 0.0}
      '''
      R = ct.Reaction.list_from_yaml(rxns, gas)

  The method `from_yaml` can be used to create individual `Reaction` objects from definitions in the YAML format. It is important to verify that either the pre-exponential factor and activation energy are supplied in SI units, or that they have their units specified:

      R = ct.Reaction.from_yaml('''{equation: O + H2 <=> H + OH,
              rate-constant: {A: 3.87e+04 cm^3/mol/s, b: 2.7, Ea: 6260 cal/mol}}''',
              gas)

  ID

    Get/Set the identification string for the reaction, which can be used in filtering operations.

  allow_negative_orders

    Get/Set a flag which is `True` if negative reaction orders are allowed. Default is `False`.

  allow_nonreactant_orders

    Get/Set a flag which is `True` if reaction orders can be specified for non-reactant species. Default is `False`.

  clear_user_data()

    Clear all saved input data, so that the data given by `input_data` or `Solution.write_yaml` will only include values generated by Cantera based on the current object state.

  default_efficiency

    Get/Set the default third-body efficiency for this reaction, used for species not in `efficiencies`.

    Deprecated since version 3.0: To be removed after Cantera 3.0. Access via `third_body` property and `ThirdBody` object instead.

  duplicate

    Get/Set a flag which is `True` if this reaction is marked as a duplicate or `False` otherwise.

  efficiencies

    Get/Set a `dict` defining non-default third-body efficiencies for this reaction, where the keys are the species names and the values are the efficiencies.

    Deprecated since version 3.0: To be removed after Cantera 3.0. Access via `third_body` property and `ThirdBody` object instead.

  efficiency(species)

    Get the efficiency of the third body named `species` considering both the default efficiency and species-specific efficiencies.

    Deprecated since version 3.0: To be removed after Cantera 3.0. Access via `third_body` property and `ThirdBody` object instead.

  equation

    A string giving the chemical equation for this reaction. Determined automatically based on `reactants` and `products`.

  classmethod from_dict(data, kinetics, hyphenize=True)

    Create a `Reaction` object from a dictionary corresponding to its YAML representation. By default, underscores in keys are replaced by hyphens.

    An example for the creation of a Reaction from a dictionary is:

        rxn = Reaction.from_dict(
            {"equation": "O + H2 <=> H + OH",
             "rate-constant": {"A": 38.7, "b": 2.7, "Ea": 26191840.0}},
            kinetics=gas)

    In the example, `gas` is a Kinetics (or Solution) object.

    Parameters:

      - data – A dictionary corresponding to the YAML representation.

      - kinetics – A `Kinetics` object whose associated phase(s) contain the species involved in the reaction.

  classmethod from_yaml(text, kinetics)

    Create a `Reaction` object from its YAML string representation.

    An example for the creation of a Reaction from a YAML string is:

        rxn = Reaction.from_yaml('''
            equation: O + H2 <=> H + OH
            rate-constant: {A: 38.7, b: 2.7, Ea: 6260.0 cal/mol}
            ''', kinetics=gas)

    In the example, `gas` is a Kinetics (or Solution) object.

    Parameters:

      - text – The YAML reaction string.

      - kinetics – A `Kinetics` object whose associated phase(s) contain the species involved in the reaction.

  input_data

    Get input data for this reaction with its current parameter values, along with any user-specified data provided with its input (YAML) definition.

  static list_from_file(filename, kinetics, section='reactions')

    Create a list of Reaction objects from all of the reactions defined in a YAML file. Reactions from the section `section` will be returned.

    Directories on Cantera’s input file path will be searched for the specified file.

  static list_from_yaml(text, kinetics)

    Create a list of `Reaction` objects from all the reactions defined in a YAML string.

  orders

    Get/Set the reaction order with respect to specific species as a dict with species names as the keys and orders as the values, or as a composition string. By default, mass-action kinetics is assumed, with the reaction order for each reactant species equal to each its stoichiometric coefficient.

  product_string

    A string representing the products side of the chemical equation for this reaction. Determined automatically based on `products`.

  products

    Get/Set the products in this reaction as a dict where the keys are species names and the values, are the stoichiometric coefficients, for example `{'CH3':1, 'H2O':1}`, or as a composition string, for example `'CH3:1, H2O:1'`.

    Deprecated since version 3.0: Setter for products is deprecated and will be removed after Cantera 3.0. Use constructor instead.

  rate

    Get/Set the reaction rate evaluator for this reaction.

  rate_coeff_units

    Get reaction rate coefficient units

  reactant_string

    A string representing the reactants side of the chemical equation for this reaction. Determined automatically based on `reactants`.

  reactants

    Get/Set the reactants in this reaction as a dict where the keys are species names and the values, are the stoichiometric coefficients, for example `{'CH4':1, 'OH':1}`, or as a composition string, for example `'CH4:1, OH:1'`.

    Deprecated since version 3.0: Setter for reactants is deprecated and will be removed after Cantera 3.0. Use constructor instead.

  reaction_type

    Retrieve the native type name of the reaction.

  reversible

    Get/Set a flag which is `True` if this reaction is reversible or `False` otherwise.

  third_body

    Returns a `ThirdBody` object if `Reaction` uses a third body collider, and `None` otherwise.

    New in version 3.0.

  third_body_name

    Returns name of `ThirdBody` collider if `Reaction` uses a third body collider, and `None` otherwise.

    New in version 3.0.

  update_user_data(data)

    Add the contents of the provided `dict` as additional fields when generating YAML phase definition files with `Solution.write_yaml` or in the data returned by `input_data`. Existing keys with matching names are overwritten.

### ThreeBodyReaction

class cantera.ThreeBodyReaction

  Bases: `Reaction`

  A reaction with a non-reacting third body “M” that acts to add or remove energy from the reacting species.

  An example for the definition of an `ThreeBodyReaction` object is given as:

      rxn = ThreeBodyReaction(
          equation="2 O + M <=> O2 + M",
          rate={"A": 1.2e+17, "b": -1.0, "Ea": 0.0},
          efficiencies={"H2": 2.4, "H2O": 15.4, "AR": 0.83},
          kinetics=gas)

  The YAML description corresponding to this reaction is:

      equation: 2 O + M <=> O2 + M
      type: three-body
      rate-constant: {A: 1.2e+17 cm^6/mol^2/s, b: -1.0, Ea: 0.0 cal/mol}
      efficiencies: {H2: 2.4, H2O: 15.4, AR: 0.83}

  Deprecated since version 3.0: Class to be removed after Cantera 3.0. Absorbed by `Reaction`.

### FalloffReaction

class cantera.FalloffReaction

  Bases: `Reaction`

  A reaction that is first-order in [M] at low pressure, like a third-body reaction, but zeroth-order in [M] as pressure increases.

  An example for the definition of a `FalloffReaction` object is given as:

      rxn = FalloffReaction(
          equation="2 OH (+ M) <=> H2O2 (+ M)",
          rate=ct.TroeRate(low=ct.Arrhenius(2.3e+12, -0.9, -7112800.0),
                           high=ct.Arrhenius(7.4e+10, -0.37, 0),
                           falloff_coeffs=[0.7346, 94.0, 1756.0, 5182.0]),
          efficiencies={"AR": 0.7, "H2": 2.0, "H2O": 6.0},
          kinetics=gas)

  The YAML description corresponding to this reaction is:

      equation: 2 OH (+ M) <=> H2O2 (+ M)  # Reaction 3
      type: falloff
      low-P-rate-constant: {A: 2.3e+12, b: -0.9, Ea: -1700.0 cal/mol}
      high-P-rate-constant: {A: 7.4e+10, b: -0.37, Ea: 0.0 cal/mol}
      Troe: {A: 0.7346, T3: 94.0, T1: 1756.0, T2: 5182.0}
      efficiencies: {AR: 0.7, H2: 2.0, H2O: 6.0}

  Deprecated since version 3.0: Class to be removed after Cantera 3.0. Absorbed by `Reaction`.

### ChemicallyActivatedReaction

class cantera.ChemicallyActivatedReaction

  Bases: `FalloffReaction`

  A reaction where the rate decreases as pressure increases due to collisional stabilization of a reaction intermediate. Like a `FalloffReaction`, except that the forward rate constant is written as being proportional to the low- pressure rate constant.

### CustomReaction

class cantera.CustomReaction

  Bases: `Reaction`

  A reaction which follows mass-action kinetics with a custom reaction rate.

  An example for the definition of a `CustomReaction` object is given as:

      rxn = CustomReaction(
          equation="H2 + O <=> H + OH",
          rate=lambda T: 38.7 * T**2.7 * exp(-3150.15428/T),
          kinetics=gas)

  Deprecated since version 3.0: Class to be removed after Cantera 3.0. Absorbed by `Reaction`.

## Reaction Rates

### ReactionRate

class cantera.ReactionRate

  Bases: `object`

  Base class for ReactionRate objects.

  ReactionRate objects are used to calculate reaction rates and are associated with a Reaction object.

  conversion_units

    Get the units for converting the leading term in the reaction rate expression to different unit systems.

  classmethod from_dict(data, hyphenize=True)

    Create a `ReactionRate` object from a dictionary corresponding to its YAML representation. By default, underscores in keys are replaced by hyphens.

    An example for the creation of a `ReactionRate` from a dictionary is:

        rate = ReactionRate.from_dict(
            {"rate-constant": {"A": 38.7, "b": 2.7, "Ea": 26191840.0}})

    Parameters:

      data – A dictionary corresponding to the YAML representation.

  classmethod from_yaml(text)

    Create a `ReactionRate` object from its YAML string representation.

    An example for the creation of a `ReactionRate` from a YAML string is:

        rate = ReactionRate.from_yaml(
            "rate-constant: {A: 38.7, b: 2.7, Ea: 6260.0 cal/mol}")

    Units for `A` require a unit system with length in `m` and quantity in `kmol` (standard Cantera units).

    Parameters:

      text – The YAML reaction rate string.

  input_data

    Get input data for this reaction rate with its current parameter values.

  sub_type

    Get the C++ ReactionRate sub-type

  type

    Get the C++ ReactionRate type

### ArrheniusRateBase

class cantera.ArrheniusRateBase(input_data)

  Bases: `ReactionRate`

  Base class collecting commonly used features of Arrhenius-type rate objects. Objects should be instantiated by specialized classes, for example `ArrheniusRate`, `BlowersMaselRate` and `TwoTempPlasmaRate`.

  activation_energy

    The activation energy `E` [J/kmol].

  allow_negative_pre_exponential_factor

    Get/Set whether the rate coefficient is allowed to have a negative pre-exponential factor.

  pre_exponential_factor

    The pre-exponential factor `A` in units of m, kmol, and s raised to powers depending on the reaction order.

  temperature_exponent

    The temperature exponent `b`.

### ArrheniusRate

class cantera.ArrheniusRate(A, b, Ea)

  Bases: `ArrheniusRateBase`

  A reaction rate coefficient which depends on temperature only and follows the modified Arrhenius form:

  \[k_f = A T^b \exp(-\tfrac{E_a}{RT})\]

  where `A` is the `pre_exponential_factor`, `b` is the `temperature_exponent`, and `Ea` is the `activation_energy`.

### BlowersMaselRate

class cantera.BlowersMaselRate(A, b, Ea, w)

  Bases: `ArrheniusRateBase`

  A reaction rate coefficient which depends on temperature and enthalpy change of the reaction follows the Blowers-Masel approximation and modified Arrhenius form described in `ArrheniusRate`.

  bond_energy

    Average bond dissociation energy of the bond being formed and broken in the reaction `E` [J/kmol].

  delta_enthalpy

    Enthalpy change of reaction `deltaH` [J/kmol]

    The enthalpy change of reaction is a function of temperature and thus not an independent property. Accordingly, the setter should be only used for testing purposes, as any value will be overwritten by an update of the thermodynamic state.

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

### TwoTempPlasmaRate

class cantera.TwoTempPlasmaRate(A, b, Ea_gas, Ea_electron)

  Bases: `ArrheniusRateBase`

  A reaction rate coefficient which depends on both gas and electron temperature with the form similar to the modified Arrhenius form. Specifically, the temperature exponent (b) is applied to the electron temperature instead. In addition, the exponential term with activation energy for electron is included.

  \[k_f = A T_e^b \exp(-\tfrac{E_{a,g}}{RT}) \exp(\tfrac{E_{a,e}(T_e - T)}{R T T_e})\]

  where \(A\) is the `pre_exponential_factor`, \(b\) is the `temperature_exponent`, \(E_{a,g}\) (`Ea_gas`) is the `activation_energy`, and \(E_{a,e}\) (`Ea_electron`) is the `activation_electron_energy`.

  activation_electron_energy

    The activation electron energy \(E_{a,e}\) [J/kmol].

### FalloffRate

class cantera.FalloffRate

  Bases: `ReactionRate`

  Base class for parameterizations used to describe the fall-off in reaction rates due to intermolecular energy transfer. These objects are used by `FalloffReaction`. Note that `FalloffRate` is a base class for specialized fall-off parameterizations and cannot be instantiated by itself.

  allow_negative_pre_exponential_factor

    Get/Set whether the rate coefficient is allowed to have a negative pre-exponential factor.

  chemically_activated

    Get whether the object is a chemically-activated reaction rate.

  falloff_coeffs

    The array of coefficients used to define this falloff function.

  falloff_function(temperature, conc3b)

    Evaluate the falloff function based on temperature and third-body concentration.

  high_rate

    Get/Set the `Arrhenius` rate constant in the high-pressure limit

  low_rate

    Get/Set the `Arrhenius` rate constant in the low-pressure limit

### LindemannRate

class cantera.LindemannRate(low, high, falloff_coeffs)

  Bases: `FalloffRate`

  The Lindemann falloff parameterization.

  This class implements the simple falloff function \(F(T,P_r) = 1.0\).

### TroeRate

class cantera.TroeRate(low, high, falloff_coeffs)

  Bases: `FalloffRate`

  The 3- or 4-parameter Troe falloff function.

  Parameters:

    falloff_coeffs – An array of 3 or 4 parameters: \([a, T^{***}, T^*, T^{**}]\) where the final parameter is optional (with a default value of 0).

### SriRate

class cantera.SriRate(low, high, falloff_coeffs)

  Bases: `FalloffRate`

  The 3- or 5-parameter SRI falloff function.

  Parameters:

    falloff_coeffs – An array of 3 or 5 parameters: \([a, b, c, d, e]\) where the last two parameters are optional (with default values of 1 and 0, respectively).

### TsangRate

class cantera.TsangRate(low, high, falloff_coeffs)

  Bases: `FalloffRate`

  The Tsang falloff parameterization.

### PlogRate

class cantera.PlogRate(rates)

  Bases: `ReactionRate`

  A pressure-dependent reaction rate parameterized by logarithmically interpolating between Arrhenius rate expressions at various pressures.

  rates

    Get/Set the rate coefficients for this reaction, which are given as a list of (pressure, `Arrhenius`) tuples.

### ChebyshevRate

class cantera.ChebyshevRate(temperature_range, pressure_range, data)

  Bases: `ReactionRate`

  A pressure-dependent reaction rate parameterized by a bivariate Chebyshev polynomial in temperature and pressure.

  data

    2D array of Chebyshev coefficients where rows and columns correspond to temperature and pressure dimensions over which the Chebyshev fit is computed.

  n_pressure

    Number of pressures over which the Chebyshev fit is computed (same as number of columns of `data` property).

  n_temperature

    Number of temperatures over which the Chebyshev fit is computed. (same as number of rows of `data` property).

  pressure_range

    Valid pressure range [Pa] for the Chebyshev fit

  temperature_range

    Valid temperature range [K] for the Chebyshev fit

### CustomRate

class cantera.CustomRate(k)

  Bases: `ReactionRate`

  A custom rate coefficient which depends on temperature only.

  The simplest way to create a `CustomRate` object is to use a lambda function, for example:

      rr = CustomRate(lambda T: 38.7 * T**2.7 * exp(-3150.15/T))

  Warning

  This class is an experimental part of the Cantera API and may be changed or removed without notice.

  set_rate_function(k)

    Set the function describing a custom reaction rate:

        rr = CustomRate()
        rr.set_rate_function(lambda T: 38.7 * T**2.7 * exp(-3150.15/T))

### ExtensibleRate

class cantera.ExtensibleRate

  Bases: `ReactionRate`

  A base class for a user-defined reaction rate parameterization. Classes derived from this class should be decorated with the `extension` decorator to specify the name of the rate parameterization and its corresponding data class, and to make these rates constructible through factory functions and input files.

  Classes derived from `ExtensibleRate` should implement the `set_parameters`, `get_parameters`, `eval`, and (optionally) `validate` methods, which will be called as delegates from the C++ ReactionRate class.

  Warning

  The delegatable methods defined here are an experimental part of the Cantera API and may change without notice.

  New in version 3.0.

  eval(data: ExtensibleRateData) → float

    Responsible for calculating the forward rate constant based on the current state of the phase, stored in an instance of a class derived from `ExtensibleRateData`.

  get_parameters(params: AnyMap) → None

    Responsible for serializing the state of the ExtensibleRate object, using the same format as a YAML reaction entry. This is the inverse of `set_parameters`.

    Serialization methods may request output in unit systems other than Cantera’s native mks+kmol system. To enable conversions to the user-specified unit system, dimensional values should be added to `params` using the methods `AnyMap.set_quantity` and `AnyMap.set_activation_energy`.

  set_parameters(params: AnyMap, rate_coeff_units: UnitStack) → None

    Responsible for setting rate parameters based on the input data. For example, for reactions created from YAML, `params` is the YAML reaction entry converted to an `AnyMap`. `rate_coeff_units` specifies the units of the rate coefficient.

    Input values contained in `params` may be in non-default unit systems, specified in the user-provided input file. To convert them to Cantera’s native mks+kmol unit system, use the functions `AnyMap.convert`, `AnyMap.convert_activation_energy`, and `AnyMap.convert_rate_coeff` as needed.

  validate(equation: str, soln: Solution) → None

    Responsible for validating that the rate expression is configured with valid parameters. This may depend on properties of the Solution, for example temperature ranges over which the rate expression can be evaluated. Raises an exception if any validation fails.

### InterfaceRateBase

class cantera.InterfaceRateBase

  Bases: `ArrheniusRateBase`

  Base class collecting commonly used features of Arrhenius-type rate objects that include coverage dependencies.

  beta

    Return the charge transfer beta parameter

  coverage_dependencies

    Get/set a dictionary containing adjustments to the Arrhenius rate expression dependent on surface species coverages. The keys of the dictionary are species names, and the values are dictionaries specifying the three coverage parameters `a`, `m` and `E` which are the modifiers for the pre-exponential factor [m, kmol, s units], the temperature exponent [nondimensional], and the activation energy [J/kmol], respectively.

  set_species(species)

    Set association with an ordered list of all species associated with an `InterfaceKinetics` object.

  site_density

    Site density [kmol/m^2]

    The site density is not an independent property, as it is set by an associated `InterfaceKinetics` object. Accordingly, the setter should be only used for testing purposes, as the value will be overwritten by an update of the thermodynamic state.

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

  uses_electrochemistry

    Return boolean flag indicating whether rate involves a charge transfer.

### InterfaceArrheniusRate

class cantera.InterfaceArrheniusRate(A, b, Ea)

  Bases: `InterfaceRateBase`

  A reaction rate coefficient which depends on temperature and interface coverage

### InterfaceBlowersMaselRate

class cantera.InterfaceBlowersMaselRate(A, b, Ea0, w)

  Bases: `InterfaceRateBase`

  A reaction rate coefficient which depends on temperature and enthalpy change of the reaction follows the Blowers-Masel approximation and modified Arrhenius form described in `ArrheniusRate`.

  bond_energy

    Average bond dissociation energy of the bond being formed and broken in the reaction `E` [J/kmol].

  delta_enthalpy

    Enthalpy change of reaction `deltaH` [J/kmol]

    The enthalpy change of reaction is a function of temperature and thus not an independent property. Accordingly, the setter should be only used for testing purposes, as any value will be overwritten by an update of the thermodynamic state.

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

### StickRateBase

class cantera.StickRateBase

  Bases: `InterfaceRateBase`

  Base class collecting commonly used features of Arrhenius-type sticking rate objects that include coverage dependencies.

  motz_wise_correction

    Get/Set a boolean indicating whether to use the correction factor developed by Motz & Wise for reactions with high (near-unity) sticking coefficients when converting the sticking coefficient to a rate coefficient.

  sticking_order

    The exponent applied to site density (sticking order).

    The sticking order is not an independent property and is detected automatically by Cantera. Accordingly, the setter should be only used for testing purposes.

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

  sticking_species

    The name of the sticking species. Needed only for reactions with multiple non-surface reactant species, where the sticking species is ambiguous.

  sticking_weight

    The molecular weight of the sticking species.

    The sticking weight is not an independent property and is detected automatically by Cantera. Accordingly, the setter should be only used for testing purposes.

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

### StickingArrheniusRate

class cantera.StickingArrheniusRate(A, b, Ea)

  Bases: `StickRateBase`

  A surface sticking rate expression based on the Arrhenius parameterization

### StickingBlowersMaselRate

class cantera.StickingBlowersMaselRate(A, b, Ea0, w)

  Bases: `StickRateBase`

  A surface sticking rate expression based on the Blowers-Masel parameterization

  bond_energy

    Average bond dissociation energy of the bond being formed and broken in the reaction `E` [J/kmol].

  delta_enthalpy

    Enthalpy change of reaction `deltaH` [J/kmol]

    The enthalpy change of reaction is a function of temperature and thus not an independent property. Accordingly, the setter should be only used for testing purposes, as any value will be overwritten by an update of the thermodynamic state.

    Warning

    This property is an experimental part of the Cantera API and may be changed or removed without notice.

## Auxiliary Reaction Data

### ExtensibleRateData

class cantera.ExtensibleRateData

  Bases: `object`

  A base class for data used when evaluating instances of `ExtensibleRate`. Classes derived from `ExtensibleRateData` are used to store common data needed to evaluate all reactions of a particular type.

  Classes derived from `ExtensibleRateData` must implement the `update` method. After the `update` method has been called, instances of `ExtensibleRateData` are passed as the argument to `ExtensibleRate.eval`.

  New in version 3.0.

  update(soln)

    This method takes a `Solution` object and stores any thermodynamic data (for example, temperature and pressure) needed to evaluate all reactions of the corresponding ReactionRate type.

    If this state data has changed since the last time `update` was called and the reaction rates need to be updated, this method should return `True`. Otherwise, it should return `False`.

### ThirdBody

class cantera.ThirdBody

  Bases: `object`

  Class representing third-body collision partners in three-body or falloff reactions.

  Parameters:

    - collider – Name of the third-body collider. If `M` (default), the `default_efficiency` is set to 1 and the collider is assumed to participate in a three-body reaction. If the collider includes parentheses, - for example `(+M)`, - a falloff form is assumed, where the collider is not considered for the law of mass action. For species other than `M`, the third-body collider represents a named species with collision efficiency 1, and the `default_efficiency` is set to zero.

    - efficiencies – Non-default third-body efficiencies

    - default_efficiency – Default third-body efficiency

  New in version 3.0.

  default_efficiency

    Get/Set the default third-body efficiency for this reaction, used for species not in `efficiencies`.

  efficiencies

    Get/Set a `dict` defining non-default third-body efficiencies for this reaction, where the keys are the species names and the values are the efficiencies.

  efficiency(species)

    Get the efficiency of the third body named `species` considering both the default efficiency and species-specific efficiencies.

  mass_action

    Retrieve flag indicating whether third-body collider participates in the law of mass action.

  name

    Get the name of the third-body collider used in the reaction equation.

### Arrhenius

class cantera.Arrhenius(A, b, E)

  Bases: `object`

  A reaction rate coefficient which depends on temperature only and follows the modified Arrhenius form:

  \[k_f = A T^b \exp(-\tfrac{E}{RT})\]

  where `A` is the `pre_exponential_factor`, `b` is the `temperature_exponent`, and `E` is the `activation_energy`.

  activation_energy

    The activation energy `E` [J/kmol].

  pre_exponential_factor

    The pre-exponential factor `A` in units of m, kmol, and s raised to powers depending on the reaction order.

  temperature_exponent

    The temperature exponent `b`.

## Reaction Path Analysis

### ReactionPathDiagram

class cantera.ReactionPathDiagram(Kinetics kin, str element)

  Bases: `object`

  Create a reaction path diagram for the fluxes of the element `element` according the the net reaction rates determined by the `Kinetics` object `kin`.

  add(other)

    Add fluxes from `other` to this diagram

  arrow_width

    Get/Set the arrow width. If < 0, then scale with flux value.

  bold_color

    Get/Set the color for bold lines

  bold_threshold

    Get/Set the minimum relative flux for bold lines

  build(verbose=False)

    Build the reaction path diagram. Called automatically by methods which return representations of the diagram, for example write_dot().

  dashed_color

    Get/Set the color for dashed lines

  display_only(k)

    Include only species and fluxes that are directly connected to the species with index `k`. Set to -1 to include all species.

  dot_options

    Get/Set options for the ‘dot’ program

  flow_type

    Get/Set the way flows are drawn. Either ‘NetFlow’ or ‘OneWayFlow’

  font

    Get/Set the name of the font used

  get_data()

    Get a (roughly) human-readable representation of the reaction path diagram.

  get_dot()

    Return a string containing the reaction path diagram formatted for use by Graphviz’s ‘dot’ program.

  label_threshold

    Get/Set the minimum relative flux for labels

  log

    Logging messages generated while building the reaction path diagram

  normal_color

    Get/Set the color for normal-weight lines

  normal_threshold

    Get/Set the maximum relative flux for dashed lines

  scale

    Get/Set the scaling factor for the fluxes. Set to -1 to normalize by the maximum net flux.

  show_details

    Get/Set whether to show the details of which reactions contribute to the flux.

  threshold

    Get/Set the threshold for the minimum flux relative value that will be plotted.

  title

    Get/Set the diagram title

  write_dot(filename)

    Write the reaction path diagram formatted for use by Graphviz’s ‘dot’ program to the file named `filename`.