Cantera  2.2.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Functions
Kinetics Managers
Collaboration diagram for Kinetics Managers:


class  ImplicitSurfChem
 Advances the surface coverages of the associated set of SurfacePhase objects in time. More...
class  Kinetics
 Public interface for kinetics managers. More...


doublereal isDuplicateReaction (std::map< int, doublereal > &r1, std::map< int, doublereal > &r2)
 This function returns a ratio if two reactions are duplicates of one another, and 0.0 otherwise. More...
void checkRxnElementBalance (Kinetics &kin, const ReactionData &rdata, doublereal errorTolerance=1.0e-3)
 This function will check a specific reaction to see if the elements balance. More...
void getRateCoefficient (const XML_Node &kf, Kinetics &kin, ReactionData &rdata, const ReactionRules &rules)
 Read the rate coefficient data from the XML file. More...
bool installReactionArrays (const XML_Node &p, Kinetics &kin, std::string default_phase, bool check_for_duplicates=false)
 Install information about reactions into the kinetics object, kin. More...
bool importKinetics (const XML_Node &phase, std::vector< ThermoPhase * > th, Kinetics *kin)
 Import a reaction mechanism for a phase or an interface. More...
double checkDuplicateStoich (std::map< int, double > &r1, std::map< int, double > &r2) const
 Check whether r1 and r2 represent duplicate stoichiometries This function returns a ratio if two reactions are duplicates of one another, and 0.0 otherwise. More...

Detailed Description

Models and Managers

A kinetics manager is a C++ class that implements a kinetics model; a kinetics model is a set of mathematical equation describing how various kinetic quantities are to be computed – reaction rates, species production rates, etc. Many different kinetics models might be defined to handle different types of kinetic processes. For example, one kinetics model might use expressions valid for elementary reactions in ideal gas mixtures. It might, for example, require the reaction orders to be integral and equal to the forward stoichiometric coefficients, require that each reaction be reversible with a reverse rate satisfying detailed balance, include pressure-dependent unimolecular reactions, etc. Another kinetics model might be designed for heterogeneous chemistry at interfaces, and might allow empirical reaction orders, coverage-dependent activation energies, irreversible reactions, and include effects of potential differences across the interface on reaction rates.

A kinetics manager implements a kinetics model. Since the model equations may be complex and expensive to evaluate, a kinetics manager may adopt various strategies to 'manage' the computation and evaluate the expressions efficiently. For example, if there are rate coefficients or other quantities that depend only on temperature, a manager class may choose to store these quantities internally, and re-evaluate them only when the temperature has actually changed. Or a manager designed for use with reaction mechanisms with a few repeated activation energies might precompute the terms \( exp(-E/RT) \), instead of evaluating the exponential repeatedly for each reaction. There are many other possible 'management styles', each of which might be better suited to some reaction mechanisms than others.

But however a manager structures the internal computation, the tasks the manager class must perform are, for the most part, the same. It must be able to compute reaction rates, species production rates, equilibrium constants, etc. Therefore, all kinetics manager classes should have a common set of public methods, but differ in how they implement these methods.

A kinetics manager computes reaction rates of progress, species production rates, equilibrium constants, and similar quantities for a reaction mechanism. All kinetics manager classes derive from class Kinetics, which defines a common public interface for all kinetics managers. Each derived class overloads the virtual methods of Kinetics to implement a particular kinetics model.

For example, class GasKinetics implements reaction rate expressions appropriate for homogeneous reactions in ideal gas mixtures, and class InterfaceKinetics implements expressions appropriate for heterogeneous mechanisms at interfaces, including how to handle reactions involving charged species of phases with different electric potentials — something that class GasKinetics doesn't deal with at all.

Many of the methods of class Kinetics write into arrays the values of some quantity for each species, for example the net production rate. These methods always write the results into flat arrays, ordered by phase in the order the phase was added, and within a phase in the order the species were added to the phase (which is the same ordering as in the input file). Example: suppose a heterogeneous mechanism involves three phases – a bulk phase 'a', another bulk phase 'b', and the surface phase 'a:b' at the a/b interface. Phase 'a' contains 12 species, phase 'b' contains 3, and at the interface there are 5 adsorbed species defined in phase 'a:b'. Then methods like getNetProductionRates(doublereal* net) will write and output array of length 20, beginning at the location pointed to by 'net'. The first 12 values will be the net production rates for all 12 species of phase 'a' (even if some do not participate in the reactions), the next 3 will be for phase 'b', and finally the net production rates for the surface species will occupy the last 5 locations.

Function Documentation

doublereal isDuplicateReaction ( std::map< int, doublereal > &  r1,
std::map< int, doublereal > &  r2 

This function returns a ratio if two reactions are duplicates of one another, and 0.0 otherwise.

The input arguments are two maps from species number to stoichiometric coefficient, one for each reaction. The reactions are considered duplicates if their stoichiometric coefficients have the same ratio for all species.

r1map 1
r2map 2
Returns 0.0 if the reactions are not the same. If the reactions are the same, it returns the ratio of the stoichiometric coefficients.
Now handled by Kinetics::checkDuplicateStoich. To be removed after Cantera 2.2.

Definition at line 519 of file importKinetics.cpp.

References Cantera::warn_deprecated().

void checkRxnElementBalance ( Kinetics &  kin,
const ReactionData &  rdata,
doublereal  errorTolerance = 1.0e-3 

This function will check a specific reaction to see if the elements balance.

kinKinetics object
rdataObject containing the information about one reaction
errorTolerancedouble containing the error tolerance.
Now handled by Kinetics::checkReactionBalance. To be removed after Cantera 2.2.

Definition at line 35 of file importKinetics.cpp.

References Phase::elementName(), ReactionData::equation, Cantera::fp2str(), Kinetics::kineticsSpeciesIndex(), Phase::nAtoms(), Phase::nElements(), ReactionData::products, ReactionData::pstoich, ReactionData::reactants, ReactionData::rstoich, Kinetics::speciesPhase(), Kinetics::speciesPhaseIndex(), and Cantera::warn_deprecated().

void getRateCoefficient ( const XML_Node &  kf,
Kinetics &  kin,
ReactionData &  rdata,
const ReactionRules &  rules 

Read the rate coefficient data from the XML file.

Extract the rate coefficient for a reaction from the XML node, kf. kf should point to a XML element named "rateCoeff". rdata is the partially filled ReactionData object for the reaction. This function will fill in more fields in the ReactionData object.

kfXML_Node containing information about the rate coefficients.
kinkinetics manager
rdataReactionData reference
rulesRules for parsing and installing reactions

Trigger an exception for negative A unless specifically authorized.

Now handled through newReaction() and its support functions. To be removed after Cantera 2.2.

Definition at line 416 of file importKinetics.cpp.

References XML_Node::attrib(), ReactionData::auxRateCoeffParameters, ReactionData::beta, ReactionData::chebCoeffs, ReactionData::chebDegreeP, ReactionData::chebDegreeT, ReactionData::chebPmax, ReactionData::chebPmin, ReactionData::chebTmax, ReactionData::chebTmin, Cantera::CHEBYSHEV_RXN, Cantera::CHEMACT_RXN, XML_Node::child(), Cantera::EDGE_RXN, Cantera::ELEMENTARY_RXN, Cantera::FALLOFF_RXN, Cantera::fpValue(), Cantera::GasConstant, Cantera::getArrhenius(), Cantera::getCoverageDependence(), Cantera::getEfficiencies(), Cantera::getFalloff(), Cantera::getFloat(), Cantera::getFloatArray(), Cantera::getStick(), Cantera::int2str(), XML_Node::name(), XML_Node::nChildren(), ReactionData::number, Cantera::PLOG_RXN, ReactionData::plogParameters, ReactionData::rateCoeffParameters, ReactionData::rateCoeffType, ReactionData::reactionType, Cantera::SURFACE_RXN, Kinetics::surfacePhaseIndex(), Kinetics::thermo(), Cantera::THREE_BODY_RXN, and Cantera::warn_deprecated().

bool installReactionArrays ( const XML_Node &  p,
Kinetics &  kin,
std::string  default_phase,
bool  check_for_duplicates = false 

Install information about reactions into the kinetics object, kin.

At this point, parent usually refers to the phase XML element. One of the children of this element is reactionArray, the element which determines where in the XML file to look up the reaction rate data.

pparent XML phase element
kinKinetics object to install reactions into
default_phaseThe default_phase is the default phase to assume when looking up species.
check_for_duplicatesCheck for reactions with exactly the same reactants and products.
On return, if reaction instantiation goes correctly, return true. If there is a problem, return false.

Definition at line 561 of file importKinetics.cpp.

References Kinetics::addReaction(), XML_Node::attrib(), Kinetics::checkDuplicates(), XML_Node::child(), Kinetics::finalize(), Cantera::get_XML_Node(), XML_Node::getChildren(), XML_Node::hasChild(), Cantera::newReaction(), Cantera::npos, XML_Node::root(), Kinetics::skipUndeclaredSpecies(), and Kinetics::skipUndeclaredThirdBodies().

Referenced by Cantera::importKinetics().

bool importKinetics ( const XML_Node &  phase,
std::vector< ThermoPhase * >  th,
Kinetics *  kin 

Import a reaction mechanism for a phase or an interface.

This routine will import a reaction mechanism into a kinetics object. The reaction mechanism may either be homogeneous or heterogeneous, involving multiple ThermoPhase objects. The hosting phase should be included as the first argument. For example, if phase I is an interface phase between bulk phases A and B. Then, the XML_Node for phase I should be the first argument. The vector of ThermoPhase objects should consist of pointers to phases I, A, and B.

phaseThis is an XML node containing a description of the owning phase for the kinetics object. Within the phase is a XML element called reactionArray containing the location of the description of the reactions that make up the kinetics object. Also within the phase is an XML element called phaseArray containing a listing of other phases that participate in the kinetics mechanism.
thThis is a list of ThermoPhase pointers which must include all of the phases that participate in the kinetics operator. All of the phases must have already been initialized and formed within Cantera. However, their pointers should not have been added to the Kinetics object; this addition is carried out here. Additional phases may be include in the list; these have no effect.
kinThis is a pointer to a kinetics manager class that will be initialized with the kinetics mechanism. Inherited Kinetics classes should be used here.

Definition at line 677 of file importKinetics.cpp.

References Kinetics::addPhase(), XML_Node::child(), Cantera::getStringArray(), XML_Node::hasChild(), Kinetics::init(), Cantera::installReactionArrays(), Cantera::npos, XML_Node::parent(), and Kinetics::phaseIndex().

Referenced by Cantera::buildSolutionFromXML(), Interface::Interface(), and KineticsFactory::newKinetics().

double checkDuplicateStoich ( std::map< int, double > &  r1,
std::map< int, double > &  r2 
) const

Check whether r1 and r2 represent duplicate stoichiometries This function returns a ratio if two reactions are duplicates of one another, and 0.0 otherwise.

r1 and r2 are maps of species key to stoichiometric coefficient, one for each reaction, where the species key is 1+k for reactants and -1-k for products and k is the species index.

0.0 if the stoichiometries are not multiples of one another Otherwise, it returns the ratio of the stoichiometric coefficients.

Definition at line 258 of file Kinetics.cpp.

Referenced by Kinetics::checkDuplicates().