Comments: make AB linear solver convention match documentation

[eebasso]

Summary

This PR adjusts comments to conform to the A-B-alpha-beta linear solver convention stated in the documentation: A and B are the scalar constants, while alpha and beta are the coefficient fields.

Additional background

The convention is established throughout the Linear Solver chapter of the documentation.

From line 18 of LinearSolvers_Chapers.rst:

In this Chapter we give an overview of the linear solvers in AMReX
that solve linear systems in the canonical form

.. math:: (A \alpha - B \nabla \cdot \beta \nabla ) \phi = f,
🏷️ eqn::abeclap

where :math:A and :math:B are scalar constants,
:math:\alpha and :math:\beta are coefficient fields,
:math:\phi is the unknown,
and :math:f is the right-hand side of the equation.

From line 71 of `LinearSolvers.rst':

The :cpp:setScalars function sets the scalar constants :math:A and :math:B
.. code-block::
void setScalars (Real a, Real b) noexcept;

For the general case where :math:\alpha and :math:\beta are scalar fields, we use
.. code-block::
void setACoeffs (int amrlev, const MultiFab& alpha);
void setBCoeffs (int amrlev, const Array<MultiFab const*,AMREX_SPACEDIM>& beta);

We can also see this convention in code comments such as line 62 in AMReX_MLEBABecLap.H:

/**
* Set scalar constants A and B in the equation:
* (A \alpha - B \nabla \cdot \beta \nabla ) \phi = f
* for the Multi-Level AB Laplacian Solver.
*/

However, several code comments contradict this, with A and B being the coefficient fields, and alpha and beta as the scalar constants, including on line 10 of the same file AMReX_MLEBABecLap.H:

// (alpha * a - beta * (del dot b grad)) phi

I assume this is a hold-over when the opposite convention was used. From first hand experience, I can say this can be very confusing when reading the comments to understand how these linear operators work.

A forthcoming PR renames the Real variables alpha and beta to ascalar and bscalar, where appropriate.

Checklist

The proposed changes:

• include documentation in the code and/or rst files, if appropriate

[WeiqunZhang]

I wonder if it would be easier to fix it the other way. It seems that the A \alpha convention is mostly used in the sphinx documentation, whereas the alpha A convention is mostly used in the code.

[eebasso]

The code confusingly uses both conventions.

Examples in the code of the Greek letters referring to the coefficients (A \alpha convention) include the following:

• Most instances of setACoeffs have alpha as its main argument, found in (AMReX_)Hypre.H, PETSc.H, MLABecLaplacian.H, MLALaplacian.H, MLEBABecLap.H. The only exception is in MLNodeABecLaplacian.H, where the argument is a_acoef which works with either convention in my opinion.
• Most instances of setBCoeffs have beta as its main argument, found in Hypre.H, PETSc.H, MLABecLaplacian.H, MLEBABecLap.H, MLEBTensorOp.H, and MLTensorOp.H. The only exception is in MLNodeABecLaplacian.H, where the argument is called a_bcoef which works with either convention in my opinion.
• No instance of the setScalars method has alpha or beta as its arguments. It always either a and b or sa and sb.
• The variables named beta_on_center and beta_on_centroid in the MLEBABecLap files refers to the cell position of the coefficient field.

I have another branch already made that renames all instances of alpha and beta that refers to the scalar constants as ascalar and bscalar, respectively. I just wanted to start out by changing the comments and agreeing on a convention.