diff --git a/doc/sphinx/python/index.md b/doc/sphinx/python/index.md index abc270913..b60ecbbde 100644 --- a/doc/sphinx/python/index.md +++ b/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. diff --git a/doc/sphinx/python/utilities.rst b/doc/sphinx/python/utilities.rst index a22c2a208..9c4e547d0 100644 --- a/doc/sphinx/python/utilities.rst +++ b/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 diff --git a/doc/sphinx/python/zerodim.rst b/doc/sphinx/python/zerodim.rst index 8bb733921..8428bbde4 100644 --- a/doc/sphinx/python/zerodim.rst +++ b/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 diff --git a/include/cantera/numerics/EigenSparseDirectJacobian.h b/include/cantera/numerics/EigenSparseDirectJacobian.h index 2b2dbedf3..4f09a087a 100644 --- a/include/cantera/numerics/EigenSparseDirectJacobian.h +++ b/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: diff --git a/include/cantera/numerics/SystemJacobian.h b/include/cantera/numerics/SystemJacobian.h index 5e99318ef..8ef2a7929 100644 --- a/include/cantera/numerics/SystemJacobian.h +++ b/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) { diff --git a/interfaces/cython/cantera/_onedim.pyx b/interfaces/cython/cantera/_onedim.pyx index 5a9ed1b9e..1ba98664e 100644 --- a/interfaces/cython/cantera/_onedim.pyx +++ b/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()) diff --git a/interfaces/cython/cantera/jacobians.pyx b/interfaces/cython/cantera/jacobians.pyx index 34412a6bd..98362e1b4 100644 --- a/interfaces/cython/cantera/jacobians.pyx +++ b/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"