
=================
Chemical Kinetics
=================

Kinetics
--------

.. mat:class:: Kinetics(ph, src, id, neighbor1, neighbor2, neighbor3, neighbor4)

    Kinetics class constructor.

    Class Kinetics represents kinetics managers, which are classes
    that manage reaction mechanisms.  The reaction mechanism
    attributes are specified in a CTML file.
    Instances of class :mat:func:`Kinetics` are responsible for evaluating reaction rates
    of progress, species production rates, and other quantities pertaining to
    a reaction mechanism.
    
    :param ph:
        An instance of class :mat:func:`ThermoPhase` representing the phase
        in which reactions occur
    :param src:
        Input string of YAML, CTI, or XML file name.
    :param id:
        ID of the phase to import as specified in the input file. (optional)
    :param neighbor1:
        Instance of class :mat:func:`ThermoPhase` or :mat:func:`Solution` representing a
        neighboring phase.
    :param neighbor2:
        Instance of class :mat:func:`ThermoPhase` or :mat:func:`Solution` representing a
        neighboring phase.
    :param neighbor3:
        Instance of class :mat:func:`ThermoPhase` or :mat:func:`Solution` representing a
        neighboring phase.
    :param neighbor4:
        Instance of class :mat:func:`ThermoPhase` or :mat:func:`Solution` representing a
        neighboring phase.
    :return:
         Instance of class :mat:func:`Kinetics`
    

    .. mat:function:: advanceCoverages(k, dt)

        Advance the surface coverages forward in time.

        The bulk phase concentrations are held fixed during this operation.
        
        :param k:
            Instance of class :mat:func:`Interface` with an associated
            :mat:func:`Kinetics` object.
        :param dt:
            Time interval by which the coverages should be advanced
        

    .. mat:function:: creationRates(a)

        Get the chemical creation rates.

        
        See also: :mat:func:`destructionRates`, :mat:func:`netProdRates`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which creation rates are desired.
        :return:
            Returns a column vector of the creation rates of all
            species. If the output is not assigned to a variable, a
            bar graph is produced. Units: kmol/m**3-s
        

    .. mat:function:: destructionRates(a)

        Get the chemical destruction rates.

        
        See also: :mat:func:`creationRates`, :mat:func:`netProdRates`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which destruction rates are desired.
        :return:
            Returns a column vector of the destruction rates of all
            species. If the output is not assigned to a variable, a
            bar graph is produced. Units: kmol/m**3-s
        

    .. mat:function:: equil_Kc(a)

        Get the equilibrium constants for all reactions

        
        See also: :mat:func:`fwdRateConstants`, :mat:func:`revRateConstants`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which equilibrium constants are desired.
        :return:
            Returns a column vector of the equilibrium constants
            for all reactions. The vector has an entry for every
            reaction, whether reversible or not, but non-zero values
            occur only for the reversible reactions. If the output is
            not assigned to a variable, a bar graph is produced instead.
        

    .. mat:function:: fwdRateConstants(a)

        Get the forward reaction rate constants.

        
        The computed values include all temperature-dependent, pressure-dependent, and
        third body contributions. Units are a combination of kmol, m^3 and s, that
        depend on the rate expression for the reaction.
        
        Deprecated 2.6:
        
            Behavior to change after Cantera 2.6; for Cantera 2.6, rate constants of
            three-body reactions are multiplied with third-body concentrations
            (no change to legacy behavior). After Cantera 2.6, results will no longer
            include third-body concentrations and be consistent with conventional
            definitions (see Eq. 9.75 in Kee, Coltrin and Glarborg, 'Chemically
            Reacting Flow', Wiley Interscience, 2003).
            To switch to new behavior, run 'useLegacyRateConstants(0)'.
        
        see also: :mat:func:`revRateConstants`, :mat:func:`equil_Kc`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which forward rate constants are desired.
        :return:
            Returns a column vector of the forward rate constants of
            all of the reactions.
        

    .. mat:function:: getDeltaEnthalpies(a)

        Get the enthalpy of reaction for each reaction.

        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics) for which the enthalpies of
            reaction are desired.
        :return:
            Returns a vector of the enthalpy of reaction for each
            reaction. Units: J/kmol
        

    .. mat:function:: getDeltaEntropies(a)

        Get the entropy of reaction for each reaction.

        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics) for which the entropies of
            reaction are desired.
        :return:
            Returns a vector of the entropy of reaction for each
            reaction. Units: J/kmol-K
        

    .. mat:function:: getDeltaGibbs(a)

        Get the Gibbs free energy of reaction for each reaction.

        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics) for which the Gibbs free
            energies of reaction are desired.
        :return:
            Returns a vector of the Gibbs free energy of reaction
            for each reaction. Units: J/kmol
        

    .. mat:function:: isReversible(a, i)

        Get an array of flags indicating reversibility of a reaction.

        A reversible reaction is one that runs in both the forward
        direction (reactants -> products) and in the reverse direction
        (products -> reactants). The reverse rate for reversible
        reactions can computed from thermochemistry, so that the
        reaction satisfies detailed balance, and the net rate of
        progress is zero in states of chemical equilibrium. The reverse
        rate can also be specified directly by a rate expression. An
        irreversible reaction is one whose reverse reaction rate is
        zero.
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the reversible flags are desired.
        :param i:
            Integer reaction number
        :return:
            1 if reaction number ``i`` is
            reversible, and 0 if it is irreversible.
        

    .. mat:function:: multiplier(a,irxn)

        Get the multiplier for reaction rate of progress.

        The multiplier multiplies the reaction rate of progress. It may
        be used to implement sensitivity analysis, or to selectively
        disable reactions.  For reversible reactions, it multiplies both
        the forward and reverse rates. By default, the multiplier value
        is 1.0, but it may be set to any other value by calling method
        :mat:func:`setMultiplier`.
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the multipliers are desired.
        :param irxn:
            Integer reaction number for which the multiplier is desired.
        :return:
            Multiplier of the rate of progress of reaction number ``irxn``
        

    .. mat:function:: nReactions(a)

        Get the number of reactions.

        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the number of reactions is desired.
        :return:
            Integer number of reactions
        

    .. mat:function:: nTotalSpecies(a)

        Get the total number of species.

        The total number of species, summed over all
        participating phases.
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the number of species is desired.
        :return:
            Integer total number of species
        

    .. mat:function:: netProdRates(a)

        Get the net chemical production rates for all species.

        
        See also: :mat:func:`creationRates`, :mat:func:`destructionRates`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which net production rates are desired.
        :return:
            Returns a column vector of the net production (creation -
            destruction) rates of all species. If the output is not
            assigned to a variable, a bar plot is produced.
        

    .. mat:function:: reactionEqn(a, irxn)

        Get the reaction equation of a reaction.

        If only the first argument
        is given, the reaction equations of all of the reactions are
        returned in a cell array. Otherwise, ``irxn`` must be an integer
        or vector of integers.
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the reaction equations are desired.
        :param irxn:
            Optional. Integer or vector of integer reaction numbers.
        :return:
            String or cell array of strings of the reaction equations.
        

    .. mat:function:: revRateConstants(a)

        Get the reverse reaction rate constants.

        
        The computed values include all temperature-dependent, pressure-dependent, and
        third body contributions. Units are a combination of kmol, m^3 and s, that
        depend on the rate expression for the reaction.
        
        Deprecated 2.6:
        
            Behavior to change after Cantera 2.6; for Cantera 2.6, rate constants of
            three-body reactions are multiplied with third-body concentrations
            (no change to legacy behavior). After Cantera 2.6, results will no longer
            include third-body concentrations and be consistent with conventional
            definitions (see Eq. 9.75 in Kee, Coltrin and Glarborg, 'Chemically
            Reacting Flow', Wiley Interscience, 2003).
            To switch to new behavior, run 'useLegacyRateConstants(0)'.
        
        See also: :mat:func:`fwdRateConstants`, :mat:func:`equil_KC`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which reverse rate constants are desired.
        :return:
            Returns a column vector of the reverse rate constants of
            all of the reactions.
        

    .. mat:function:: rop(a)

        Get the forward and reverse rates of progress.

        
        See also: :mat:func:`rop_f`, :mat:func:`rop_r`, :mat:func:`rop_net`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which forward and reverse rates of progress are desired.
        :return:
            Returns an I x 2 array of reaction rates of
            progress, where I is the number of reactions. The first
            column contains the forward rates of progress, and the
            second column the reverse rates. If this function
            is called with no output argument, a bar graph is produced.
        

    .. mat:function:: rop_f(a)

        Forward rates of progress for all reactions.

        
           See also: :mat:func:`rop_r`, :mat:func:`rop_net`, :mat:func:`rop`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which forward rates of progress are desired.
        :return:
            Returns a column vector of the forward rates of progress
            for all reactions. If this function
            is called with no output argument, a bar graph is produced.
        

    .. mat:function:: rop_net(a)

        Net rates of progress for all reactions.

        
        See also: :mat:func:`rop_f`, :mat:func:`rop_r`, :mat:func:`rop`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the net rates of progress are desired.
        :return:
            Returns a column vector of the net rates of progress
            for all reactions. If this function
            is called with no output argument, a bar graph is produced.
        

    .. mat:function:: rop_r(a)

        Get the reverse rates of progress for all reactions.

        
           See also: :mat:func:`rop_f`, :mat:func:`rop_net`, :mat:func:`rop`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which reverse rates of progress are desired.
        :return:
            Returns a column vector of the reverse rates of progress
            for all reactions. If this function
            is called with no output argument, a bar graph is produced.
        

    .. mat:function:: setMultiplier(a, irxn, v)

        Set the multiplier for the reaction rate of progress.

        The multiplier multiplies the reaction rate of progress. It may
        be used to implement sensitivity analysis, or to selectively
        disable reactions.  For reversible reactions, it multiplies both
        the forward and reverse rates. By default, the multiplier value
        is 1.0, but the current value may be checked by calling method
        :mat:func:`multiplier`.
        
        If only two arguments are given, it is assumed that the second is
        the desired multiplication factor for all of the reactions.
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the multipliers should be set.
        :param irxn:
            Integer or vector of integers. Reaction number(s) for which
            the multiplier should be set. Optional.
        :param v:
            Value by which the reaction rate of progress should be multiplied
        

    .. mat:function:: stoich_net(a, species, rxns)

        Get the net stoichiometric coefficients.

        
        See also: :mat:func:`stoich_r`, :mat:func:`stoich_p`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the net stoichiometric coefficients are desired.
        :param species:
            Species indices for which net stoichiometric coefficients
            should be retrieved. Optional argument; if specified, ``rxns``
            must be specified as well.
        :param rxns:
            Reaction indices for which net stoichiometric coefficients
            should be retrieved. Optional argument; if specified, ``species``
            must be specified as well.
        :return:
            Returns a sparse matrix of all net stoichiometric
            coefficients. The matrix element ``nu(k,i)`` is the
            stoichiometric coefficient of species k as a net in
            reaction i. If ``species`` and ``rxns`` are specified, the matrix
            will contain only entries for the specified species and
            reactions. For example, ``stoich_p(a,3,[1 3 5 7])`` returns a
            sparse matrix containing only the coefficients for species 3
            in reactions 1, 3, 5, and 7.
        

    .. mat:function:: stoich_p(a, species, rxns)

        Get the product stoichiometric coefficients.

        
        See also: :mat:func:`stoich_r`, :mat:func:`stoich_net`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the product stoichiometric coefficients are desired.
        :param species:
            Species indices for which product stoichiometric coefficients
            should be retrieved. Optional argument; if specified, ``rxns``
            must be specified as well.
        :param rxns:
            Reaction indices for which product stoichiometric coefficients
            should be retrieved. Optional argument; if specified, ``species``
            must be specified as well.
        :return:
            Returns a sparse matrix of all product stoichiometric
            coefficients. The matrix element ``nu(k,i)`` is the
            stoichiometric coefficient of species k as a product in
            reaction i. If ``species`` and ``rxns`` are specified, the matrix
            will contain only entries for the specified species and
            reactions. For example, ``stoich_p(a,3,[1 3 5 7])`` returns a
            sparse matrix containing only the coefficients for species 3
            in reactions 1, 3, 5, and 7.
        

    .. mat:function:: stoich_r(a, species, rxns)

        Get the reactant stoichiometric coefficients.

        
        See also: :mat:func:`stoich_p`, :mat:func:`stoich_net`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the reactant stoichiometric coefficients are desired.
        :param species:
            Species indices for which reactant stoichiometric coefficients
            should be retrieved. Optional argument; if specified, ``rxns``
            must be specified as well.
        :param rxns:
            Reaction indices for which reactant stoichiometric coefficients
            should be retrieved. Optional argument; if specified, ``species``
            must be specified as well.
        :return:
            Returns a sparse matrix of all reactant stoichiometric
            coefficients. The matrix element ``nu(k,i)`` is the
            stoichiometric coefficient of species k as a reactant in
            reaction i. If ``species`` and ``rxns`` are specified, the matrix
            will contain only entries for the specified species and
            reactions. For example, ``stoich_r(a,3,[1 3 5 7])`` returns a
            sparse matrix containing only the coefficients for species 3
            in reactions 1, 3, 5, and 7.
        

    .. mat:function:: ydot(a)

        Get the mass production rates of the species.

        Evaluates the source term :math:`\dot{\omega}_k M_k /\rho`
        
        :param a:
            Instance of class :mat:func:`Kinetics` (or another
            object deriving from Kinetics)
            for which the ydots are desired.
        :return:
            Returns a vector of length nSpecies. Units: kg/s
        


