This commit updates naming, docs, bugs, and makes other PR changes.

`_ddN` was used for concentration based derivatives now. Missing
derivatives for surface chemistry were added which required some
refactoring of mole reactor interfaces and updates to those derivatives.
Some documentation was added and some of the requested PR changes were
handled.

include/cantera/kinetics/GasKinetics.h

@@ -77,7 +77,9 @@ class GasKinetics : public BulkKinetics
     virtual Eigen::SparseMatrix<double> fwdRatesOfProgress_ddX();
     virtual Eigen::SparseMatrix<double> revRatesOfProgress_ddX();
     virtual Eigen::SparseMatrix<double> netRatesOfProgress_ddX();
-    virtual Eigen::SparseMatrix<double> netRatesOfProgress_ddC();
+    virtual Eigen::SparseMatrix<double> fwdRatesOfProgress_ddN();
+    virtual Eigen::SparseMatrix<double> revRatesOfProgress_ddN();
+    virtual Eigen::SparseMatrix<double> netRatesOfProgress_ddN();
 
     //! Update temperature-dependent portions of reaction rates and falloff
     //! functions.
@@ -131,17 +133,14 @@ class GasKinetics : public BulkKinetics
     void process_ddC(StoichManagerN& stoich, const vector_fp& in,
                      double* drop, bool mass_action=true);
 
-    //! Process mole fraction derivative
+    //! Process derivatives
     //! @param stoich  stoichiometry manager
     //! @param in  rate expression used for the derivative calculation
-    Eigen::SparseMatrix<double> process_ddX(StoichManagerN& stoich,
-                                            const vector_fp& in);
-
-    //! Process mole fraction derivative
-    //! @param stoich  stoichiometry manager
-    //! @param in  rate expression used for the derivative calculation
-    Eigen::SparseMatrix<double> process_ddC(StoichManagerN& stoich,
-                                            const vector_fp& in);
+    //! @param ddX true: w.r.t mole fractions false: w.r.t species concentrations
+    //! @return a sparse matrix of derivative contributions for each reaction of
+    //! dimensions nTotalReactions by nTotalSpecies
+    Eigen::SparseMatrix<double> process_derivatives(StoichManagerN& stoich,
+                                                    const vector_fp& in, bool ddX=true);
 
     //! Helper function ensuring that all rate derivatives can be calculated
     //! @param name  method name used for error output

include/cantera/kinetics/InterfaceKinetics.h

@@ -305,7 +305,16 @@ class InterfaceKinetics : public Kinetics
     */
     double interfaceCurrent(const size_t iphase);
 
-    virtual Eigen::SparseMatrix<double> netRatesOfProgress_ddC();
+    /**
+     * Set/modify derivative settings. For the interface kinetics object this
+     * includes `"skip-cov-dep"`, `"skip-electrochem"`, and `"rtol-delta"`.
+     *
+     * @param settings  AnyMap containing settings determining derivative evaluation.
+     */
+    virtual void setDerivativeSettings(const AnyMap& settings);
+    virtual Eigen::SparseMatrix<double> fwdRatesOfProgress_ddN();
+    virtual Eigen::SparseMatrix<double> revRatesOfProgress_ddN();
+    virtual Eigen::SparseMatrix<double> netRatesOfProgress_ddN();
 
 protected:
     //! @name Internal service methods
@@ -324,9 +333,18 @@ class InterfaceKinetics : public Kinetics
     //! Process mole fraction derivative
     //! @param stoich  stoichiometry manager
     //! @param in  rate expression used for the derivative calculation
-    Eigen::SparseMatrix<double> process_ddC(StoichManagerN& stoich,
+    //! @return a sparse matrix of derivative contributions for each reaction of
+    //! dimensions nTotalReactions by nTotalSpecies
+    Eigen::SparseMatrix<double> process_derivatives(StoichManagerN& stoich,
                                             const vector_fp& in);
 
+    //! Helper function ensuring that all rate derivatives can be calculated
+    //! @param name  method name used for error output
+    //! @throw CanteraError if coverage dependence or electrochemical reactions are
+    //! included
+    void assertDerivativesValid(const std::string& name);
+    //! @}
+
     //! Temporary work vector of length m_kk
     vector_fp m_grt;
 
@@ -490,6 +508,11 @@ class InterfaceKinetics : public Kinetics
     vector_fp m_rbuf0;
     vector_fp m_rbuf1;
     vector_fp m_rbuf2;
+
+    // Derivative settings initialized to their default values
+    bool m_jac_skip_cov_dependance = true;
+    bool m_jac_skip_electrochem = true;
+    double m_jac_rtol_delta = 1e-8;
 };
 
 }

include/cantera/kinetics/Kinetics.h

@@ -589,6 +589,7 @@ class Kinetics
     //!  - `_ddP`: derivative with respect to pressure (a vector)
     //!  - `_ddC`: derivative with respect to molar concentration (a vector)
     //!  - `_ddX`: derivative with respect to species mole fractions (a matrix)
+    //!  - `_ddN`: derivative with respect to species concentrations (a matrix)
     //!
     //! Settings for derivative evaluation are set by keyword/value pairs using
     //! the methods getDerivativeSettings() and setDerivativeSettings().
@@ -716,6 +717,24 @@ class Kinetics
             "Not implemented for kinetics type '{}'.", kineticsType());
     }
 
+    /**
+     * Calculate derivatives for forward rates-of-progress with respect to species
+     * concentration at constant temperature, pressure and remaining species
+     * concentrations.
+     *
+     * The method returns a matrix with nReactions rows and nTotalSpecies columns.
+     * For a derivative with respect to \f$n_i\f$, all other \f$n_j\f$ are held
+     * constant.
+     *
+     * @warning  This method is an experimental part of the %Cantera API and
+     *      may be changed or removed without notice.
+     */
+    virtual Eigen::SparseMatrix<double> fwdRatesOfProgress_ddN()
+    {
+        throw NotImplementedError("Kinetics::fwdRatesOfProgress_ddN",
+            "Not implemented for kinetics type '{}'.", kineticsType());
+    }
+
     /**
      * Calculate derivatives for reverse rates-of-progress with respect to temperature
      * at constant pressure, molar concentration and mole fractions.
@@ -769,6 +788,24 @@ class Kinetics
             "Not implemented for kinetics type '{}'.", kineticsType());
     }
 
+    /**
+     * Calculate derivatives for forward rates-of-progress with respect to species
+     * concentration at constant temperature, pressure and remaining species
+     * concentrations.
+     *
+     * The method returns a matrix with nReactions rows and nTotalSpecies columns.
+     * For a derivative with respect to \f$n_i\f$, all other \f$n_j\f$ are held
+     * constant.
+     *
+     * @warning  This method is an experimental part of the %Cantera API and
+     *      may be changed or removed without notice.
+     */
+    virtual Eigen::SparseMatrix<double> revRatesOfProgress_ddN()
+    {
+        throw NotImplementedError("Kinetics::revRatesOfProgress_ddN",
+            "Not implemented for kinetics type '{}'.", kineticsType());
+    }
+
     /**
      * Calculate derivatives for net rates-of-progress with respect to temperature
      * at constant pressure, molar concentration and mole fractions.
@@ -824,7 +861,8 @@ class Kinetics
 
     /**
      * Calculate derivatives for net rates-of-progress with respect to species
-     * concentration at constant temperature and pressure.
+     * concentration at constant temperature, pressure, and remaining species
+     * concentrations.
      *
      * The method returns a matrix with nReactions rows and nTotalSpecies columns.
      * For a derivative with respect to \f$[n_i]\f$, all other \f$[n_i]\f$ are held
@@ -833,9 +871,9 @@ class Kinetics
      * @warning  This method is an experimental part of the %Cantera API and
      *      may be changed or removed without notice.
      */
-    virtual Eigen::SparseMatrix<double> netRatesOfProgress_ddC()
+    virtual Eigen::SparseMatrix<double> netRatesOfProgress_ddN()
     {
-        throw NotImplementedError("Kinetics::netRatesOfProgress_ddC",
+        throw NotImplementedError("Kinetics::netRatesOfProgress_ddN",
             "Not implemented for kinetics type '{}'.", kineticsType());
     }
 
@@ -952,15 +990,17 @@ class Kinetics
 
     /**
      * Calculate derivatives for species net production rates with respect to species
-     * concentration at constant temperature and pressure.
+     * concentration at constant temperature,  pressure, and concentration of all other
+     * species.
      *
      * The method returns a matrix with nTotalSpecies rows and nTotalSpecies columns.
-     * For a derivative with respect to \f$[n_i]\f$, all other \f$[n_i]\f$ are held constant.
+     * For a derivative with respect to \f$[n_i]\f$, all other \f$[n_i]\f$ are held
+     * constant.
      *
      * @warning  This method is an experimental part of the %Cantera API and
      *      may be changed or removed without notice.
      */
-    Eigen::SparseMatrix<double> netProductionRates_ddC();
+    Eigen::SparseMatrix<double> netProductionRates_ddN();
 
     //! @}
     //! @name Reaction Mechanism Informational Query Routines

include/cantera/zeroD/MoleReactor.h

@@ -36,10 +36,10 @@ class MoleReactor : public Reactor
 
     std::string componentName(size_t k);
 
-    //! Add the surface chemistry Jacobian values to m_jac_trips
-    virtual void addSurfJacobian();
-
 protected:
+    //! Add the surface chemistry dn/dnj Jacobian values to m_jac_trips
+    virtual void addSurfJacobian(double cp, bool pressure=false);
+
     //! Get moles of the system from mass fractions stored by thermo object
     //! @param y vector for moles to be put into
     virtual void getMoles(double* y);

include/cantera/zeroD/ReactorNet.h

@@ -302,9 +302,8 @@ class ReactorNet : public FuncEval
     virtual Eigen::SparseMatrix<double> jacobian();
 
 protected:
-    //! Check if surfaces and preconditioning are included, if so throw an error because
-    //! they are currently not supported.
-    virtual void checkPreconditionerSupported(){};
+    //! check that preconditioning is supported.
+    virtual void checkPreconditionerSupported() {};
 
     //! Update the preconditioner based on the already computed jacobian values
     virtual void updatePreconditioner(double gamma);

interfaces/cython/cantera/kinetics.pxd

@@ -60,6 +60,10 @@ cdef extern from "cantera/kinetics/Kinetics.h" namespace "Cantera":
         CxxSparseMatrix revRatesOfProgress_ddX() except +translate_exception
         CxxSparseMatrix netRatesOfProgress_ddX() except +translate_exception
 
+        CxxSparseMatrix fwdRatesOfProgress_ddN() except +translate_exception
+        CxxSparseMatrix revRatesOfProgress_ddN() except +translate_exception
+        CxxSparseMatrix netRatesOfProgress_ddN() except +translate_exception
+
         CxxSparseMatrix creationRates_ddX() except +translate_exception
         CxxSparseMatrix destructionRates_ddX() except +translate_exception
         CxxSparseMatrix netProductionRates_ddX() except +translate_exception

interfaces/cython/cantera/kinetics.pyx

@@ -517,6 +517,23 @@ cdef class Kinetics(_SolutionBase):
             return get_from_sparse(self.kinetics.fwdRatesOfProgress_ddX(),
                                    self.n_reactions, self.n_total_species)
 
+    property forward_rates_of_progress_ddN:
+        """
+        Calculate derivatives for forward rates-of-progress with respect to species
+        concentrations at constant temperature, pressure and remaining species
+        concentrations.
+        For sparse output, set ``ct.use_sparse(True)``.
+
+        Note that for derivatives with respect to :math:`[n_i]`, all other :math:`[n_j]`
+        are held constant.
+
+        **Warning:** this property is an experimental part of the Cantera API and
+        may be changed or removed without notice.
+        """
+        def __get__(self):
+            return get_from_sparse(self.kinetics.fwdRatesOfProgress_ddN(),
+                                   self.n_reactions, self.n_total_species)
+
     property reverse_rates_of_progress_ddT:
         """
         Calculate derivatives for reverse rates-of-progress with respect to temperature
@@ -560,6 +577,23 @@ cdef class Kinetics(_SolutionBase):
             return get_from_sparse(self.kinetics.revRatesOfProgress_ddX(),
                                    self.n_reactions, self.n_total_species)
 
+    property reverse_rates_of_progress_ddN:
+        """
+        Calculate derivatives for reverse rates-of-progress with respect to species
+        concentrations at constant temperature, pressure and remaining species
+        concentrations.
+        For sparse output, set ``ct.use_sparse(True)``.
+
+        Note that for derivatives with respect to :math:`[n_i]`, all other :math:`[n_j]`
+        are held constant.
+
+        **Warning:** this property is an experimental part of the Cantera API and
+        may be changed or removed without notice.
+        """
+        def __get__(self):
+            return get_from_sparse(self.kinetics.revRatesOfProgress_ddN(),
+                                   self.n_reactions, self.n_total_species)
+
     property net_rates_of_progress_ddT:
         """
         Calculate derivatives for net rates-of-progress with respect to temperature
@@ -603,6 +637,23 @@ cdef class Kinetics(_SolutionBase):
             return get_from_sparse(self.kinetics.netRatesOfProgress_ddX(),
                                    self.n_reactions, self.n_total_species)
 
+    property net_rates_of_progress_ddN:
+        """
+        Calculate derivatives for net rates-of-progress with respect to species
+        concentrations at constant temperature, pressure and remaining species
+        concentrations.
+        For sparse output, set ``ct.use_sparse(True)``.
+
+        Note that for derivatives with respect to :math:`[n_i]`, all other :math:`[n_j]`
+        are held constant.
+
+        **Warning:** this property is an experimental part of the Cantera API and
+        may be changed or removed without notice.
+        """
+        def __get__(self):
+            return get_from_sparse(self.kinetics.netRatesOfProgress_ddN(),
+                                   self.n_reactions, self.n_total_species)
+
     property creation_rates_ddT:
         """
         Calculate derivatives of species creation rates with respect to temperature

interfaces/cython/cantera/preconditioners.pxd

@@ -16,15 +16,15 @@ cdef extern from "cantera/numerics/PreconditionerBase.h" namespace "Cantera":
 cdef extern from "cantera/numerics/AdaptivePreconditioner.h" namespace "Cantera":
     cdef cppclass CxxAdaptivePreconditioner "Cantera::AdaptivePreconditioner" \
         (CxxPreconditionerBase):
-        CxxAdaptivePreconditioner() except +
+        CxxAdaptivePreconditioner() except +translate_exception
         void setThreshold(double threshold)
         double threshold()
         void setIlutFillFactor(int fillfactor)
         double ilutFillFactor()
         void setIlutDropTol(double droptol)
         double ilutDropTol()
         void printPreconditioner()
-        CxxSparseMatrix matrix() except +
+        CxxSparseMatrix matrix() except +translate_exception
 
 cdef extern from "cantera/numerics/PreconditionerFactory.h" namespace "Cantera":
     cdef shared_ptr[CxxPreconditionerBase] newPreconditioner(string) except\

interfaces/cython/cantera/reactor.pyx

@@ -1605,7 +1605,7 @@ cdef class ReactorNet:
 
     property jacobian:
         """
-        Get the Jacobian or an approximation thereof
+        Get the system Jacobian or an approximation thereof.
 
         **Warning**: Depending on the particular implementation, this may return an
         approximate Jacobian intended only for use in forming a preconditioner for