Added a new way to specify the kinetics reaction rate coefficient

when dealing with electron transfer surface reactions.
This way specifies an exchange current density reaction rate coefficient
in units of amps / m2.  This is slightly more informative for 
electrode reactions. 

The new also preserves the correct treatment of activity coefficients
for these reactions. 

A memo describing this new capability is in the works.

Cantera/src/kinetics/InterfaceKinetics.h

@@ -45,11 +45,15 @@ namespace Cantera {
   class InterfaceKineticsData {
   public:
     InterfaceKineticsData() :
+      m_logp0(0.0),
+      m_logc0(0.0),
       m_ROP_ok(false),
-      m_temp(0.0), m_logtemp(0.0)
+      m_temp(0.0), 
+      m_logtemp(0.0)
     {}
     //! Virtual destructor
-    virtual ~InterfaceKineticsData(){}
+    virtual ~InterfaceKineticsData() {
+    }
 
     doublereal m_logp0;
     doublereal m_logc0;
@@ -59,7 +63,9 @@ namespace Cantera {
 
     bool m_ROP_ok;
 
+    //! Current temperature of the data
     doublereal m_temp;
+    //! Current log of the temperature
     doublereal m_logtemp;
     vector_fp m_rfn;
     vector_fp m_rkcn;
@@ -76,9 +82,9 @@ namespace Cantera {
 
   public:
 
-    /**
-     * Constructor
-     *
+
+    //! Constructor
+    /*!
      * @param thermo The optional parameter may be used to initialize
      *               the object with one ThermoPhase object.
      *               HKM Note -> Since the interface kinetics
@@ -125,9 +131,9 @@ namespace Cantera {
     virtual int ID() const { return cInterfaceKinetics; }
     virtual int type() const { return cInterfaceKinetics; }
 
-    /**
-     * Set the electric potential in the nth phase
-     *
+
+    //! Set the electric potential in the nth phase
+     /*!
      * @param n phase Index in this kinetics object.
      * @param V Electric potential (volts)
      */
@@ -172,8 +178,17 @@ namespace Cantera {
       std::copy(m_kdata->m_ropnet.begin(), m_kdata->m_ropnet.end(), netROP);
     }
 
+
+    //! Get the equilibrium constants of all reactions, whether
+    //! the reaction is reversible or not.
+    /*!
+     *  @param kc   Returns the concentration equation constant for the reaction.
+     *              Length is the number of reactions
+     */
     virtual void getEquilibriumConstants(doublereal* kc);
 
+    void getExchangeCurrentQuantities();
+
 
     virtual void getDeltaGibbs( doublereal* deltaG);
 
@@ -394,8 +409,19 @@ namespace Cantera {
     void updateROP();
 
 
-
+
+    //! Update properties that depend on temperature
+    /*!
+     *  This is called to update all of the properties that depend on temperature
+     *
+     *  Current objects that this function updates
+     *       m_kdata->m_logtemp 
+     *       m_kdata->m_rfn
+     *       m_rates.
+     *       updateKc();
+     */
     void _update_rates_T();
+
     void _update_rates_phi();
     void _update_rates_C();
 
@@ -445,11 +471,49 @@ namespace Cantera {
     void setIOFlag(int ioFlag);
 
     void checkPartialEquil();
-
-    //! Temporary work vector of length m_kk
-    vector_fp m_grt;
 
+
+    int reactionNumber() const { return m_ii;}
+
+    void addElementaryReaction(const ReactionData& r);
+    void addGlobalReaction(const ReactionData& r);
+    void installReagents(const ReactionData& r);
+
+    void updateKc();
+
+    //! Write values into m_index
+    /*!
+     * @param rxnNumber reaction number
+     * @param type      reaction type
+     * @param loc       location ??
+     */
+    void registerReaction(int rxnNumber, int type, int loc) {
+      m_index[rxnNumber] = std::pair<int, int>(type, loc);
+    }
+
+    //! Apply corrections for interfacial charge transfer reactions
+    /*!
+     * For reactions that transfer charge across a potential difference,
+     * the activation energies are modified by the potential difference.
+     * (see, for example, ...). This method applies this correction.
+     *
+     * @param kf  Vector of forward reaction rate constants on which to have
+     *            the correction applied
+     */
+    void applyButlerVolmerCorrection(doublereal* const kf);
+
+    //! When an electrode reaction rate is optionally specified in terms of its
+    //! exchange current density, extra vectors need to be precalculated
+    /*!
+     *
+     */
+    void applyExchangeCurrentDensityFormulation(doublereal* const kfwd);
+
+
   protected:
+
+    //! Temporary work vector of length m_kk
+    vector_fp m_grt;
 
     //! m_kk is the number of species in all of the phases
     //! that participate in this kinetics mechanism.
@@ -489,7 +553,7 @@ namespace Cantera {
      *    production rates and also handles turning thermo
      *    properties into reaction thermo properties.
      */
-    ReactionStoichMgr                   m_rxnstoich;
+    ReactionStoichMgr m_rxnstoich;
 
     //! Number of irreversible reactions in the mechanism
     int m_nirrev;
@@ -607,42 +671,58 @@ namespace Cantera {
     ImplicitSurfChem* m_integrator;
 
     vector_fp m_beta;
+
+    //! Vector of reaction indexes specifying the id of the current transfer reactions
+    //! in the mechanism
+    /*!
+     *  Vector of reaction indecices which involve current transfers. This provides
+     *  an index into the m_beta array.
+     *
+     *        irxn = m_ctrxn[i] 
+     */
     vector_int m_ctrxn;
 
-    int reactionNumber(){ return m_ii;}
+    //! Vector of booleans indicating whether the charge transfer reaction may be 
+    //! described by an exchange current density expression
+    vector_int m_ctrxn_ecdf;
 
-    void addElementaryReaction(const ReactionData& r);
-    void addGlobalReaction(const ReactionData& r);
-    void installReagents(const ReactionData& r);
+    vector_fp m_logStandardConc;
+    vector_fp m_deltaG0;
+    vector_fp m_logProdStanConcReac;
 
-    void updateKc();
 
-    //! Write values into m_index
-    /*!
-     * @param rxnNumber reaction number
-     * @param type      reaction type
-     * @param loc       location ??
-     */
-    void registerReaction(int rxnNumber, int type, int loc) {
-      m_index[rxnNumber] = std::pair<int, int>(type, loc);
-    }
-
-    void applyButlerVolmerCorrection(doublereal* kf);
 
     //! boolean indicating whether mechanism has been finalized
     bool m_finalized;
+
+    //! Boolean flag indicating whether any reaction in the mechanism
+    //! has a coverage dependent forward reaction rate
+    /*!
+     *   If this is true, then the coverage dependence is multiplied into
+     *   the forward reaction rates constant
+     */
     bool m_has_coverage_dependence;
 
     //! Boolean flag indicating whether any reaction in the mechanism
     //! has a beta electrochemical parameter.
     /*!
-     *  If this is true, the the Butler-Volmer correction is applied
+     *  If this is true, the Butler-Volmer correction is applied
      *  to the forward reaction rate for those reactions.
      *
      *    fac = exp ( - beta * (delta_phi))
      */
     bool m_has_electrochem_rxns;
 
+    //! Boolean flag indicating whether any reaction in the mechanism
+    //! is described by an exchange current density expression
+    /*!
+     *  If this is true, the standard state gibbs free energy of the reaction and
+     *  the product of the reactant standard concentrations must be precalculated
+     *  in order to calculate the rate constant.
+     */
+    bool m_has_exchange_current_density_formulation;
+
+
     int m_ioFlag;
   private:
 

Cantera/src/kinetics/Kinetics.cpp

@@ -29,9 +29,16 @@ using namespace std;
 namespace Cantera {
 
 
-  Kinetics::Kinetics() : m_ii(0), m_thermo(0),
-			 m_index(-1), m_surfphase(-1), m_rxnphase(-1), 
-			 m_mindim(4) {}
+  Kinetics::Kinetics() :
+    m_ii(0), 
+    m_nTotalSpecies(0),
+    m_thermo(0),
+    m_index(-1), 
+    m_surfphase(-1),
+    m_rxnphase(-1), 
+    m_mindim(4)
+  {
+  }
 
   Kinetics::~Kinetics(){}
 
@@ -42,7 +49,8 @@ namespace Cantera {
    * throw an exception.
    */
   Kinetics::Kinetics(const Kinetics &right) :
-    m_ii(0), 
+    m_ii(0),
+    m_nTotalSpecies(0),
     m_thermo(0),
     m_index(-1), 
     m_surfphase(-1),
@@ -70,6 +78,7 @@ namespace Cantera {
     if (this == &right) return *this;
 
     m_ii                = right.m_ii;
+    m_nTotalSpecies     = right.m_nTotalSpecies;
     m_perturb           = right.m_perturb;
     m_reactants         = right.m_reactants;
     m_products          = right.m_products;
@@ -285,6 +294,15 @@ namespace Cantera {
     m_phaseindex[m_thermo.back()->id()] = nPhases();
   }
 
+  void Kinetics::finalize() {
+    m_nTotalSpecies = 0;
+    int np = nPhases();
+    for (int n = 0; n < np; n++) {
+      int nsp = m_thermo[n]->nSpecies();
+      m_nTotalSpecies += nsp;
+    }
+  }
+
 
   //! Private function of the class Kinetics, indicating that a function
   //!  inherited from the base class hasn't had a definition assigned to it

Cantera/src/kinetics/Kinetics.h

@@ -811,7 +811,7 @@ namespace Cantera {
      * any initialization (allocating arrays, etc.) that must be
      * done after the reactions are entered.
      */
-    virtual void finalize() {}
+    virtual void finalize();
 
     /**
      * Add a single reaction to the mechanism. This routine
@@ -904,6 +904,9 @@ namespace Cantera {
 
     //! Number of reactions in the mechanism
     int m_ii;
+
+    //! Number of species in the species vector for this kinetics operator
+    int m_nTotalSpecies;
 
     /// Vector of perturbation factors for each reaction's rate of
     /// progress vector. It is initialized to one.

Cantera/src/kinetics/ReactionData.h

@@ -25,7 +25,7 @@ namespace Cantera {
       number = 0;
       rxn_number = 0;
       reversible = true;
-      rateCoeffType = ARRHENIUS;
+      rateCoeffType = ARRHENIUS_REACTION_RATECOEFF_TYPE;
       falloffType = NONE;
       error = 0;
       equation = "";
@@ -36,7 +36,12 @@ namespace Cantera {
     }
     virtual ~ReactionData(){}
 
+    //! type of the reaction
+    /*!
+     *  The valid types are listed in the file, reaction_defs.h.
+     */
     int reactionType;
+
     int number;
     int rxn_number;
     vector_int reactants;
@@ -51,7 +56,14 @@ namespace Cantera {
 
     //! True if the current reaction is reversible. False otherwise
     bool reversible;
+
+    //! type of the rate coefficient for the forward rate constant
+    /*!
+     *  The valid types are listed in the file, reaction_defs.h and they
+     *  all end in RATECOEFF_TYPE
+     */
     int rateCoeffType;
+
     vector_fp rateCoeffParameters;
     vector_fp auxRateCoeffParameters;
     int falloffType;

Cantera/src/kinetics/ReactionStoichMgr.h

@@ -214,6 +214,7 @@ namespace Cantera {
      * \f[
      *  R_i = R_i * \prod_k C_k^{o_{k,i}}
      * \f]
+     *
      * Here \f$ o_{k,i} \f$ is the reaction order of species k in reaction i.
      */
       virtual void multiplyReactants(const doublereal* C, doublereal* R);