From 12d6af2f76ec2914d583993d539c952947b3d906 Mon Sep 17 00:00:00 2001
From: Weiqun Zhang <WeiqunZhang@lbl.gov>
Date: Thu, 21 Nov 2024 18:24:40 -0800
Subject: [PATCH] Update GMRES Comments (#4243)

Forgot to list `void scale(V& v, RT fac)` in the list of required
functions.
---
 Src/LinearSolvers/AMReX_GMRES.H | 62 +++++++++++++++++++++------------
 1 file changed, 40 insertions(+), 22 deletions(-)

diff --git a/Src/LinearSolvers/AMReX_GMRES.H b/Src/LinearSolvers/AMReX_GMRES.H
index 5ccc68cd231..a5105dc3a41 100644
--- a/Src/LinearSolvers/AMReX_GMRES.H
+++ b/Src/LinearSolvers/AMReX_GMRES.H
@@ -26,35 +26,53 @@ namespace amrex {
  * \tparam V linear algebra vector. It must be default constructible, move
  *           constructible, and move assignable.
  * \tparam M linear operator. A list of required member functions for M is
- *           shown below. Here RT (typename V::value_type) is either double
- *           or float.
- *             - void apply(V& lhs, V const& rhs)\n
- *               lhs = L(rhs), where L is the linear operator performing matrix
- *               vector product.
- *             - void assign(V& lhs, V const& rhs)\n
- *               lhs = rhs.
- *             - RT dotProduct(V const& v1, V const& v2)\n
- *               returns v1 * v2.
- *             - void increment(V& lhs, V const& rhs, RT a)\n
- *               lhs += a * rhs.
- *             - void linComb(V& lhs, RT a, V const& rhs_a, RT b, V const& rhs_b)\n
- *               lhs = a * rhs_a + b * rhs_b.
- *             - V makeVecRHS()\n
+ *           shown below. Here RT (`typename M::RT`) is either double or float.
+ *           Examples of implementation for V being a single-component `MultiFab`
+ *           are also given below.
+ *             - `void apply(V& Ax, V const& x)`\n
+ *               Ax = A(x), where A is the linear operator performing matrix
+ *               vector product. Here x is made with the makeVecLHS function.
+ *               Therefore, it may have ghost cells and it's safe to cast it with
+ *               const_cast<V&>(x) and do ghost cell exchange, if necessary.
+ *
+ *             - `void assign(V& lhs, V const& rhs)`\n
+ *               lhs = rhs. For example, `MultiFab::Copy(lhs,rhs,0,0,1,0)`.
+ *
+ *             - `RT dotProduct(V const& v1, V const& v2)`\n
+ *               returns v1 * v2. For example, `MultiFab::Dot(v1,0,v2,0,1,0)`.
+ *
+ *             - `void increment(V& lhs, V const& rhs, RT a)`\n
+ *               lhs += a * rhs. For example, `MultiFab::Saxpy(lhs,a,rhs,0,0,1,0)`.
+ *
+ *             - `void linComb(V& lhs, RT a, V const& rhs_a, RT b, V const& rhs_b)`\n
+ *               lhs = a * rhs_a + b * rhs_b. For example,
+ *               `MultiFab::LinComb(lhs,a,rhs_a,0,b,rhs_b,0,0,1,0)`.
+ *
+ *             - `V makeVecRHS()`\n
  *               returns a V object that is suitable as RHS in M x = b. The reason
  *               we distinguish between LHS and RHS is M might need the distinction
  *               for efficiency. For example, if V is MultiFab, we might need the x
  *               in the LHS of M x = b to have ghost cells for efficiency, whereas
- *               no ghost cells are needed for the RHS (i.e., b).
- *             - V makeVecLHS()\n
+ *               no ghost cells are needed for the RHS (i.e., b). An example of the
+ *               implementation might be `return MultiFab(grids,dmap,1,0)`.
+ *
+ *             - `V makeVecLHS()`\n
  *               returns a V object that is suitable as LHS in M x = b. See the
- *               description for makeVecRHS for more details.
- *             - RT norm2(V const& v)\n
- *               returns the 2-norm of v.
- *             - void precond(V& lhs, V const& rhs)\n
+ *               description for makeVecRHS for more details. An example of the
+ *               implementation might be `return MultiFab(grids,dmap,1,1)`.
+ *
+ *             - `RT norm2(V const& v)`\n
+ *               returns the 2-norm of v. For example, `return v.norm2()`.
+ *
+ *             - `void precond(V& lhs, V const& rhs)`\n
  *               applies preconditioner to rhs. If there is no preconditioner,
  *               this function should do lhs = rhs.
- *             - void setToZero(V& v)\n
- *               v = 0.
+ *
+ *             - `void scale(V& v, RT fac)`\n
+ *               scales v by fac. For example, `v.mult(fac)`.
+ *
+ *             - `void setToZero(V& v)`\n
+ *               v = 0. For example, `v.setVal(0)`.
  */
 template <typename V, typename M>
 class GMRES