update paper refs

Author: pratikvn

core/solver/minres.cpp

@@ -95,8 +95,9 @@ typename Minres<ValueType>::parameters_type Minres<ValueType>::parse(
 
 
 /**
- * This Minres implementation is based on Anne Grennbaum's 'Iterative Methods
- * for Solving Linear Systems' (DOI: 10.1137/1.9781611970937) Ch. 2 and Ch. 8.
+ * This Minres implementation is based on Anne Greenbaum's *Iterative Methods
+ * for Solving Linear Systems* (<https://doi.org/10.1137/1.9781611970937>),
+ * Ch. 2 and Ch. 8.
  * Most variable names are taken from that reference, with the exception that
  * the vector `w` and `w_tilde` from the reference are called `z` and `z_tilde`.
  * The variable declaration have a comment to specify the name used in the

include/ginkgo/core/solver/bicg.hpp

@@ -52,8 +52,10 @@ namespace solver {
  * It forms the basis of cheaper variants such as BiCGSTAB and CGS, which
  * avoid the explicit \f$ A^H \f$ apply.
  *
- * Reference: R.Fletcher, Conjugate gradient methods for indefinite systems,
- * doi: 10.1007/BFb0080116
+ * @par References
+ * - Fletcher, R. *Conjugate gradient methods for indefinite systems.*
+ *   Numerical Analysis (Dundee 1975), Lecture Notes in Mathematics 506,
+ *   Springer, 1976. <https://doi.org/10.1007/BFb0080116>
  *
  * @tparam ValueType  precision of matrix elements
  *

include/ginkgo/core/solver/chebyshev.hpp

@@ -39,9 +39,6 @@ using coeff_type =
  * matrix. It avoids the computation of inner products, which may be a
  * performance bottleneck for distributed system. Chebyshev iteration is
  * developed based on Chebyshev polynomials of the first kind.
- * This implementation follows the algorithm in "Templates for the
- * Solution of Linear Systems: Building Blocks for Iterative Methods, 2nd
- * Edition".
  *
  * Given a preconditioner \f$ M \approx A^{-1} \f$, the iterate is updated
  * with the three-term recurrence
@@ -61,6 +58,11 @@ using coeff_type =
  * solution_{i-1})
  * ```
  *
+ * @par References
+ * - Barrett, R., Berry, M., Chan, T. F., et al.
+ *   *Templates for the Solution of Linear Systems: Building Blocks for
+ *   Iterative Methods.* 2nd ed. SIAM, 1994.
+ *   <https://doi.org/10.1137/1.9781611971538>
  *
  * @tparam ValueType  precision of matrix elements
  *

include/ginkgo/core/solver/idr.hpp

@@ -36,9 +36,8 @@ namespace solver {
 
 /**
  * IDR(s) is an efficient method for solving large nonsymmetric systems of
- * linear equations. The implemented version is the one presented in the
- * paper "Algorithm 913: An elegant IDR(s) variant that efficiently exploits
- * biorthogonality properties" by M. B. Van Gijzen and P. Sonneveld.
+ * linear equations. The implementation follows the elegant variant that
+ * exploits the biorthogonality of the shadow vectors.
  *
  * The method is based on the induced dimension reduction theorem.  Fixing a
  * full-rank shadow space \f$ R = \mathrm{span}(r_1, \ldots, r_s) \f$ — the
@@ -53,6 +52,13 @@ namespace solver {
  * most \f$ N + N/s \f$ iterations in exact arithmetic — substantially fewer
  * matrix-vector products than the \f$ 2N \f$ BiCG would require.
  *
+ * @par References
+ * - Van Gijzen, M. B., Sonneveld, P.
+ *   *Algorithm 913: An Elegant IDR(s) Variant that Efficiently Exploits
+ *   Biorthogonality Properties.*
+ *   ACM Transactions on Mathematical Software, 38 (1), Article 5, 2011.
+ *   <https://doi.org/10.1145/2049662.2049667>
+ *
  * @tparam ValueType  precision of the elements of the system matrix.
  *
  * @ingroup idr

include/ginkgo/core/solver/minres.hpp

@@ -49,12 +49,16 @@ namespace solver {
  * use of data locality. The inner operations in one iteration of Minres are
  * merged into 2 separate steps.
  *
- * For more details see Anne Grennbaum's 'Iterative Methods
- * for Solving Linear Systems' (DOI: 10.1137/1.9781611970937), and Sou-Cheng
- * (Terrya) Choi's 'ITERATIVE METHODS FOR SINGULAR LINEAR EQUATIONS AND
- * LEAST-SQUARES PROBLEMS'.
+ * @par References
+ * - Greenbaum, A. *Iterative Methods for Solving Linear Systems.*
+ *   SIAM Frontiers in Applied Mathematics, 17, 1997.
+ *   <https://doi.org/10.1137/1.9781611970937>
+ * - Choi, S.-C. T. *Iterative Methods for Singular Linear Equations and
+ *   Least-Squares Problems.*
+ *   PhD thesis, Stanford University, 2006.
+ *   <https://web.stanford.edu/group/SOL/dissertations/sou-cheng-choi-thesis.pdf>
  *
- * @note: The Minres solver only reports an approximation of the residual norm
+ * @note The Minres solver only reports an approximation of the residual norm
  *        directly to the stopping criteria. Neither the actual residual, nor
  *        the actual residual norm are reported. Thus, to get the minimal
  *        overhead, the gko::stop::ImplicitResidualNorm criteria should be used.

include/ginkgo/core/solver/multigrid.hpp

@@ -45,11 +45,13 @@ namespace multigrid {
 /**
  * cycle defines which kind of multigrid cycle can be used.
  * It contains V, W, and F cycle.
- * - V, W cycle uses the algorithm according to Briggs, Henson, and McCormick: A
- *   multigrid tutorial 2nd Edition.
- * - F cycle uses the algorithm according to Trottenberg, Oosterlee, and
- *   Schuller: Multigrid 1st Edition. F cycle first uses the recursive call but
- *   second uses the V-cycle call such that F-cycle is between V and W cycle.
+ * - V, W cycles use the algorithm from Briggs–Henson–McCormick
+ *   (*A Multigrid Tutorial*, 2nd ed., SIAM 2000).
+ * - F cycle uses the algorithm from Trottenberg–Oosterlee–Schüller
+ *   (*Multigrid*, 1st ed., Academic Press 2001); F-cycle first does the
+ *   recursive call then a V-cycle call, sitting between V and W in cost.
+ *
+ * See the @ref Multigrid class for the full reference list with DOIs.
  */
 enum class cycle { v, f, w };
 
@@ -82,11 +84,17 @@ class MultigridState;
 
 
 /**
- * Multigrid methods have a hierarchy of many levels, whose corase level is a
- * subset of the fine level, of the problem. The coarse level solves the system
- * on the residual of fine level and fine level will use the coarse solution to
- * correct its own result. Multigrid solves the problem by relatively cheap step
- * in each level and refining the result when prolongating back.
+ * Multigrid solves a linear system by combining cheap iterative sweeps
+ * (smoothers) on a hierarchy of progressively coarser representations of
+ * the operator with corrections transferred between adjacent levels.  A
+ * smoother on the fine level removes the high-frequency components of the
+ * error quickly; the remaining low-frequency error is well-resolved on a
+ * coarser space, where it is computed by a cheaper solve — or, recursively,
+ * by another multigrid call.  The correction is prolongated back to the
+ * fine level and a second smoothing sweep removes any high-frequency error
+ * introduced by the transfer.  Because each coarser level holds only a
+ * fraction of the unknowns of the next, the total work per cycle stays
+ * close to that of a single fine-level matrix-vector apply.
  *
  * Each level \f$ \ell \f$ holds a system matrix \f$ A_\ell \f$, a smoother
  * \f$ S_\ell \f$, a restriction operator
@@ -121,6 +129,13 @@ class MultigridState;
  * the coarsest level (the coarsest solver), and its level counts is N (N
  * multigrid level generation).
  *
+ * @par References
+ * - Briggs, W. L., Henson, V. E., McCormick, S. F.
+ *   *A %Multigrid Tutorial.* 2nd ed. SIAM, 2000.
+ *   <https://doi.org/10.1137/1.9780898719505>
+ * - Trottenberg, U., Oosterlee, C. W., Schüller, A.
+ *   *%Multigrid.* 1st ed. Academic Press, 2001. ISBN 978-0-12-701070-0.
+ *
  * @ingroup Multigrid
  * @ingroup solvers
  * @ingroup LinOp

include/ginkgo/core/solver/pipe_cg.hpp

@@ -62,9 +62,11 @@ namespace solver {
  * 3. As the CG itself, this method performs very well for symmetric positive
  * definite matrices but it is in general not suitable for general matrices.
  *
- * The implementation in Ginkgo is based on the following paper:
- * Pipelined, Flexible Krylov Subspace Methods, P. Sanan et. al, SISC, 2016,
- * doi: 10.1137/15M1049130
+ * @par References
+ * - Sanan, P., Schnepp, S. M., May, D. A.
+ *   *Pipelined, Flexible Krylov Subspace Methods.*
+ *   SIAM Journal on Scientific Computing, 38 (5), 2016.
+ *   <https://doi.org/10.1137/15M1049130>
  *
  * @tparam ValueType  precision of matrix elements
  *