[docs] Make documentation of derivatives more accessible

Cantera · Jul 17, 2023 · 23fac03 · 23fac03
1 parent f33ec6b
commit 23fac03
Show file tree

Hide file tree

Showing 5 changed files with 22 additions and 9 deletions.
diff --git a/include/cantera/kinetics/Kinetics.h b/include/cantera/kinetics/Kinetics.h
@@ -22,6 +22,9 @@ class Reaction;
 class Solution;
 class AnyMap;
 
+//! @defgroup derivGroup Derivative Calculations
+//! @details Methods for calculating analytical and/or numerical derivatives.
+
 /**
  * @defgroup chemkinetics Chemical Kinetics
  */
@@ -590,11 +593,15 @@ class Kinetics
     virtual void getNetProductionRates(doublereal* wdot);
 
     //! @}
-    //! @name Routines to Calculate Derivatives (Jacobians)
+
+    //! @addtogroup derivGroup
+    //! @{
+
+    //! @name Routines to Calculate Kinetics Derivatives (Jacobians)
     //!
-    //! Derivatives are calculated with respect to temperature, pressure, molar
-    //! concentrations and species mole fractions for forward/reverse/net rates of
-    //! progress as well as creation/destruction and net production of species.
+    //! Kinetics derivatives are calculated with respect to temperature, pressure,
+    //! molar concentrations and species mole fractions for forward/reverse/net rates
+    //! of progress as well as creation/destruction and net production of species.
     //!
     //! The following suffixes are used to indicate derivatives:
     //!  - `_ddT`: derivative with respect to temperature (a vector)
@@ -1064,6 +1071,8 @@ class Kinetics
     Eigen::SparseMatrix<double> netProductionRates_ddCi();
 
     //! @}
+    //! @} End of addtogroup derivGroup
+
     //! @name Reaction Mechanism Informational Query Routines
     //! @{
 

diff --git a/include/cantera/numerics/AdaptivePreconditioner.h b/include/cantera/numerics/AdaptivePreconditioner.h
@@ -48,7 +48,8 @@ class AdaptivePreconditioner : public PreconditionerBase
     //! Prune preconditioner elements
     void prunePreconditioner();
 
-    //! Function used to return semi-analytical jacobian matrix
+    //! Return semi-analytical Jacobian of an AdaptivePreconditioner object.
+    //! @ingroup derivGroup
     Eigen::SparseMatrix<double> jacobian() {
         Eigen::SparseMatrix<double> jacobian_mat(m_dim, m_dim);
         jacobian_mat.setFromTriplets(m_jac_trips.begin(), m_jac_trips.end());

diff --git a/include/cantera/oneD/MultiJac.h b/include/cantera/oneD/MultiJac.h
@@ -17,8 +17,9 @@ namespace Cantera
  * residual function supplied by an instance of class OneDim. The residual
  * function may consist of several linked 1D domains, with different variables
  * in each domain.
-* @ingroup onedUtilsGroup
-  */
+ * @ingroup onedUtilsGroup
+ * @ingroup derivGroup
+ */
 class MultiJac : public BandMatrix
 {
 public:

diff --git a/include/cantera/oneD/OneDim.h b/include/cantera/oneD/OneDim.h
@@ -45,7 +45,8 @@ class OneDim
     //!     superseded by addDomain() using shared_ptr<Domain1D>
     void addDomain(Domain1D* d);
 
-    //! Return a reference to the Jacobian evaluator.
+    //! Return a reference to the Jacobian evaluator of an OneDim object.
+    //! @ingroup derivGroup
     MultiJac& jacobian();
 
     //! Return a reference to the Newton iterator.

diff --git a/include/cantera/zeroD/Reactor.h b/include/cantera/zeroD/Reactor.h
@@ -197,10 +197,11 @@ class Reactor : public ReactorBase
     //! @param limit value for step size limit
     void setAdvanceLimit(const std::string& nm, const double limit);
 
-    //! Method to calculate the reactor specific jacobian
+    //! Calculate the Jacobian of a specific Reactor specialization.
     //! @warning Depending on the particular implementation, this may return an
     //! approximate Jacobian intended only for use in forming a preconditioner for
     //! iterative solvers.
+    //! @ingroup derivGroup
     //!
     //! @warning  This method is an experimental part of the %Cantera
     //! API and may be changed or removed without notice.