[Doc] Update preconditioner/Jacobian docs

doc/sphinx/python/index.md

@@ -119,6 +119,10 @@ interacting with input data defined using Cantera's [YAML input format](/yaml/in
 Classes {py:class}`UnitSystem` and {py:class}`Units` are used for expressing dimensional
 quantities in input files.
 
+Several implementations of {py:class}`SystemJacobian` are available for use as
+preconditioners for reactor network simulations or linear solvers for the 1D flame simulations (notably, {py:class}`AdaptivePreconditioner` and
+{py:class}`EigenSparseDirectJacobian`).
+
 A number of [global functions](sec-python-global-funcs) are provided for managing
 locations where Cantera looks for data files, for setting how Cantera handles warnings
 and errors, and how some transitional/legacy features are handled.

doc/sphinx/python/utilities.rst

@@ -31,6 +31,29 @@ Units
 .. autoclass:: Units(name)
    :no-undoc-members:
 
+
+.. _sec-python-jacobians:
+
+Jacobians & Preconditioners
+---------------------------
+
+SystemJacobian
+^^^^^^^^^^^^^^
+.. autoclass:: SystemJacobian()
+
+AdaptivePreconditioner
+^^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: AdaptivePreconditioner()
+
+BandedJacobian
+^^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: BandedJacobian()
+
+EigenSparseDirectJacobian
+^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: EigenSparseDirectJacobian()
+
+
 .. _sec-python-global-funcs:
 
 Global Functions

doc/sphinx/python/zerodim.rst

@@ -141,13 +141,6 @@ PressureController
 .. autoclass:: PressureController(upstream, downstream, *, name=None, primary=None, K=1.0, edge_attr=None)
    :inherited-members:
 
-Preconditioners
----------------
-
-AdaptivePreconditioner
-^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: AdaptivePreconditioner()
-
 Drawing Reactor Networks
 ------------------------
 These functions provide the implementation behind the ``draw`` methods of the

include/cantera/numerics/EigenSparseDirectJacobian.h

@@ -11,6 +11,7 @@
 namespace Cantera
 {
 
+//! A system matrix solver that uses Eigen's sparse direct (LU) algorithm
 class EigenSparseDirectJacobian : public EigenSparseJacobian
 {
 public:

include/cantera/numerics/SystemJacobian.h

@@ -25,6 +25,21 @@ enum class PreconditionerSide {
 
 //! Abstract base class representing Jacobian matrices and preconditioners used in
 //! nonlinear solvers.
+//!
+//! The matrix is initially populated with elements of the (steady-state) Jacobian
+//! using the setValue() method.
+//!
+//! If the object is being used for preconditioning, the preconditioner matrix
+//! @f$ M = I - \gamma J @f$ is computed and factorized by calling
+//! updatePreconditioner(). If the object is being used for solving a (pseudo-)transient
+//! problem, the transient Jacobian @f$ M = J - \alpha \Delta t^{-1} @f$ is computed and
+//! factorized by calling the updateTransient() method.
+//!
+//! Once the system is factorized, the solve() method can be used for preconditioning
+//! or solving Newton steps as appropriate.
+//!
+//! Implementations of this class provide different options for how to store the
+//! matrix elements and different algorithms for factorizing the matrix.
 class SystemJacobian
 {
 public:
@@ -59,14 +74,26 @@ public:
         m_precon_side = preconSide;
     }
 
-    //! Update the diagonal terms in the Jacobian by using the transient mask.
+    //! Transform Jacobian vector and write into
+    //! preconditioner, P = (I - gamma * J)
+    virtual void updatePreconditioner() {
+        throw NotImplementedError("SystemJacobian::updatePreconditioner");
+    }
+
+    //! Update the diagonal terms in the Jacobian by using the transient mask
+    //! @f$ \alpha @f$.
     //! @param rdt  Reciprocal of the time step [1/s]
     //! @param mask  Mask for transient terms: 1 if transient, 0 if algebraic.
     virtual void updateTransient(double rdt, int* mask) {
         throw NotImplementedError("SystemJacobian::updateTransient");
     }
 
-    //! Solve a linear system Ax=b where A is the preconditioner
+    //! Solve a linear system using the system matrix *M*
+    //!
+    //! The matrix *M* can either be the preconditioner or the transient Jacobian
+    //! matrix, depending on whether updateTransient() or updatePreconditioner() was
+    //! called last.
+    //!
     //! @param[in] stateSize length of the rhs and output vectors
     //! @param[in] rhs_vector right hand side vector used in linear system
     //! @param[out] output output vector for solution
@@ -102,12 +129,6 @@ public:
         throw NotImplementedError("SystemJacobian::printPreconditioner");
     };
 
-    //! Transform Jacobian vector and write into
-    //! preconditioner, P = (I - gamma * J)
-    virtual void updatePreconditioner() {
-        throw NotImplementedError("SystemJacobian::updatePreconditioner");
-    }
-
     //! Set gamma used in preconditioning
     //! @param gamma used in M = I - gamma*J
     virtual void setGamma(double gamma) {

interfaces/cython/cantera/_onedim.pyx

@@ -1017,7 +1017,7 @@ cdef class Sim1D:
         """
         Get/Set the the linear solver used to hold the Jacobian matrix and solve linear
         systems as part of each Newton iteration. The default is a banded, direct
-        solver.
+        solver. See :ref:`sec-python-jacobians` for available solvers.
         """
         return SystemJacobian.wrap(self.sim.linearSolver())
 

interfaces/cython/cantera/jacobians.pyx

@@ -11,6 +11,7 @@ cdef dict _class_registry = {}
 cdef class SystemJacobian:
     """
     Common base class for Jacobian matrices used in the solution of nonlinear systems.
+    Wraps C++ class :ct:`SystemJacobian`.
     """
     _type = "SystemJacobian"
     linear_solver_type = "GMRES"
@@ -64,6 +65,11 @@ cdef class SystemJacobian:
 
 
 cdef class EigenSparseJacobian(SystemJacobian):
+    """
+    Base class for system Jacobians that use Eigen sparse matrices for storage.
+    Wraps C++ class :ct:`EigenSparseJacobian`.
+    """
+
     _type = "eigen-sparse"
 
     cdef set_cxx_object(self):
@@ -158,6 +164,10 @@ cdef class AdaptivePreconditioner(EigenSparseJacobian):
 
 
 cdef class BandedJacobian(SystemJacobian):
+    """
+    A system matrix solver that uses a direct banded linear solver. Wraps C++
+    class :ct:`MultiJac`.
+    """
     _type = "banded-direct"
     linear_solver_type = "direct"