Documenting coupled solvers

ddemidov · Dec 21, 2020 · 781fb82 · 781fb82
1 parent 15b8dfb
commit 781fb82
Show file tree

Hide file tree

Showing 4 changed files with 151 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -26,12 +26,12 @@ See AMGCL documentation at http://amgcl.readthedocs.io/
 
 ## Referencing
 
-D. Demidov. AMGCL: An efficient, flexible, and extensible algebraic multigrid
+Demidov, Denis. AMGCL: An efficient, flexible, and extensible algebraic multigrid
 implementation. Lobachevskii Journal of Mathematics, 40(5):535–546, May 2019.
 [doi](https://doi.org/10.1134/S1995080219050056) [pdf](https://rdcu.be/bHFsY)
 [bib](https://raw.githubusercontent.com/ddemidov/amgcl/master/docs/demidov19.bib)
 
-D. Demidov. AMGCL -- A C++ library for efficient solution of large sparse linear
+Demidov, Denis. AMGCL -- A C++ library for efficient solution of large sparse linear
 systems.  Software Impacts, 6:100037, November 2020.
 [doi](https://doi.org/10.1016/j.simpa.2020.100037)
 [bib](https://raw.githubusercontent.com/ddemidov/amgcl/master/docs/demidov20.bib)

diff --git a/docs/bibliography.rst b/docs/bibliography.rst
@@ -30,6 +30,7 @@ Bibliography
 .. [SlDi93] Sleijpen, Gerard LG, and Diederik R. Fokkema. "BiCGstab (l) for linear equations involving unsymmetric matrices with complex spectrum." Electronic Transactions on Numerical Analysis 1.11 (1993): 2000.
 .. [Stue07] Stüben, Klaus, et al. `Algebraic multigrid methods (AMG) for the efficient solution of fully implicit formulations in reservoir simulation <https://doi.org/10.2118/105832-MS>`_. SPE Reservoir Simulation Symposium. Society of Petroleum Engineers, 2007.
 .. [Stue99] Stüben, Klaus. Algebraic multigrid (AMG): an introduction with applications. GMD-Forschungszentrum Informationstechnik, 1999.
+.. [TNVE09] Tang, J. M., Nabben, R., Vuik, C., & Erlangga, Y. A. (2009). `Comparison of two-level preconditioners derived from deflation, domain decomposition and multigrid methods <https://doi.org/10.1007/s10915-009-9272-6>`_. Journal of scientific computing, 39(3), 340-370.
 .. [TrOS01] Trottenberg, U., Oosterlee, C., and Schüller, A. Multigrid. Academic Press, London, 2001.
 .. [VaMB96] Vaněk, Petr, Jan Mandel, and Marian Brezina. `Algebraic multigrid by smoothed aggregation for second and fourth order elliptic problems. <https://doi.org/10.1007/BF02238511>`_ Computing 56.3 (1996): 179-196.
 .. [ViBo92] Vincent, C., and R. Boyer. `A preconditioned conjugate gradient Uzawa‐type method for the solution of the Stokes problem by mixed Q1–P0 stabilized finite elements <https://doi.org/10.1002/fld.1650140304>`_. International journal for numerical methods in fluids 14.3 (1992): 289-298.
diff --git a/docs/components/coupled_solvers.rst b/docs/components/coupled_solvers.rst
@@ -1,11 +1,158 @@
 Coupling Solvers with Preconditioners
 =====================================
 
+These classes provide a convenient way to couple an iterative solver and a
+preconditioner. This may be used both for convenience and as a building block
+for a composite :doc:`preconditioner <preconditioners>`.
+
 make_solver
 -----------
 
+.. cpp:class:: template <class Precond, class IterSolver> \
+               amgcl::make_solver
+
+   .. rubric:: Include ``<amgcl/make_solver.hpp>``
+
+   The class has two template parameters: ``Precond`` and ``IterSolver``, which
+   specify the preconditioner and the iterative solver to use. During
+   construction of the class, instances of both components are constructed and
+   are ready to use as a whole.
+
+   .. cpp:type:: typename Backend::params backend_params
+
+      The backend parameters
+
+   .. cpp:type:: typename Backend::value_type value_type
+
+      The value type of the system matrix
+
+   .. cpp:type:: typename amgcl::math::scalar_of<value_type>::type scalar_type
+
+      The scalar type corresponding to the value type. For example, when the
+      value type is ``std::complex<double>``, then the scalar type is
+      ``double``.
+
+   .. cpp:class:: params
+
+      The coupled solver parameters
+
+      .. cpp:member:: typename Precond::params precond
+
+         The preconditioner parameters
+
+      .. cpp:member:: IterSolver::params solver
+
+         The iterative solver parameters
+
+   .. cpp:function:: template <class Matrix> \
+                     make_solver(const Matrix &A, \
+                                 const params &prm = params(), \
+                                 const backend_params &bprm = backend_params())
+
+      The constructor
+
+   .. cpp:function:: template <class Matrix, class VectorRHS, class VectorX> \
+                     std::tuple<size_t, scalar_type> operator()( \
+                         const Matrix &A, const VectorRHS &rhs, VectorX &x) const
+
+      Computes the solution for the given system matrix ``A`` and the
+      right-hand side ``rhs``.  Returns the number of iterations made and
+      the achieved residual as a ``std::tuple``. The solution vector
+      ``x`` provides initial approximation on input and holds the computed
+      solution on output.
+
+      The system matrix may differ from the matrix used during
+      initialization. This may be used for the solution of non-stationary
+      problems with slowly changing coefficients. There is a strong chance
+      that a preconditioner built for a time step will act as a reasonably
+      good preconditioner for several subsequent time steps [DeSh12]_.
+
+   .. cpp:function:: template <class VectorRHS, class VectorX> \
+                     std::tuple<size_t, scalar_type> operator()( \
+                         const VectorRHS &rhs, VectorX &x) const
+
+      Computes the solution for the given right-hand side ``rhs``.
+      Returns the number of iterations made and the achieved residual as a
+      ``std::tuple``. The solution vector ``x`` provides initial
+      approximation on input and holds the computed solution on output.
+
+   .. cpp:function:: const Precond& precond() const
+
+      Returns reference to the constructed preconditioner
+
+   .. cpp:function:: const IterSolver& solver() const
+
+      Returns reference to the constructed iterative solver
+
 make_block_solver
 -----------------
 
+.. cpp:class:: template <class Precond, class IterSolver> \
+               amgcl::make_block_solver
+
+   .. rubric:: Include ``<amgcl/make_block_solver.hpp>``
+
+   Creates coupled solver which targets a block valued backend, but may be
+   initialized with a scalar system matrix, and used with scalar vectors.
+
+   The scalar system matrix is transparently converted to the block-valued on
+   using the :cpp:func:`amgcl::adapter::block_matrix` adapter in the class
+   constructor, and the scalar vectors are reinterpreted to the block-valued
+   ones upon application.
+
+   This class may be used as a building block in a composite preconditioner,
+   when one (or more) of the subsystems has block values, but has to be
+   computed as a scalar matrix.
+
+   The interface is the same as that of :cpp:class:`amgcl::make_solver`.
+
 deflated_solver
 ---------------
+
+.. cpp:class:: template <class Precond, class IterSolver> \
+               amgcl::deflated_solver
+
+   .. rubric:: Include ``<amgcl/deflated_solver.hpp>``
+
+   Creates preconditioned deflated solver. Deflated Krylov subspace methods are
+   supposed to solve problems with large jumps in the coefficients on layered
+   domains. It appears that the convergence of a deflated solver is independent
+   of the size of the jump in the coefficients. The specific variant of the
+   deflation method used here is A-DEF2 from [TNVE09]_.
+
+   .. cpp:type:: typename Backend::params backend_params
+
+      The backend parameters
+
+   .. cpp:type:: typename Backend::value_type value_type
+
+      The value type of the system matrix
+
+   .. cpp:type:: typename amgcl::math::scalar_of<value_type>::type scalar_type
+
+      The scalar type corresponding to the value type. For example, when the
+      value type is ``std::complex<double>``, then the scalar type is
+      ``double``.
+
+   .. cpp:class:: params
+
+      The deflated solver parameters
+
+      .. cpp:member:: int nvec = 0
+
+         The number of deflation vectors
+
+      .. cpp:member:: scalar_type *vec = nullptr
+
+         .. close the*
+
+         The deflation vectors stored as a [nvec x n] matrix in row-major order
+
+      .. cpp:member:: typename Precond::params precond
+
+         The preconditioner parameters
+
+      .. cpp:member:: IterSolver::params solver
+
+         The iterative solver parameters
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -24,7 +24,7 @@ Referencing
 -----------
 
 .. [Demi19] Demidov, Denis. `AMGCL: An efficient, flexible, and extensible algebraic multigrid implementation <https://doi.org/10.1134/S1995080219050056>`_. Lobachevskii Journal of Mathematics 40.5 (2019): 535-546. `pdf <https://rdcu.be/bHFsY>`_, :download:`bib <demidov19.bib>`
-.. [Demi20] D. Demidov. `AMGCL – A C++ library for efficient solution of large sparse linear systems <https://doi.org/10.1016/j.simpa.2020.100037>`_. Software Impacts, 6:100037, November 2020. :download:`bib <demidov20.bib>`
+.. [Demi20] Demidov, Denis. `AMGCL – A C++ library for efficient solution of large sparse linear systems <https://doi.org/10.1016/j.simpa.2020.100037>`_. Software Impacts, 6:100037, November 2020. :download:`bib <demidov20.bib>`
 
 Contents:
 ---------