Notes on how agglomeration works in MLMG (#4602)

Notes on how agglomeration works in MLMG

---------

Co-authored-by: Weiqun Zhang <[email protected]>

Author: ajnonaka

Docs/sphinx_documentation/source/LinearSolvers.rst

@@ -359,7 +359,7 @@ biconjugate gradient stabilized method, but can easily be changed with the :cpp:
 
     void setBottomSolver (BottomSolver s);
 
-Available choices are
+Available choices the bottom solver are
 
 - :cpp:`MLMG::BottomSolver::bicgstab`: The default.
 
@@ -379,18 +379,30 @@ Available choices are
 
 - :cpp:`MLMG::BottomSolver::petsc`: Currently for cell-centered only.
 
+The :cpp:`LPInfo` class can be used control the agglomeration and
+consolidation strategy for multigrid coarsening.
+
 - :cpp:`LPInfo::setAgglomeration(bool)` (by default true) can be used
-  continue to coarsen the multigrid by copying what would have been the
-  bottom solver to a new :cpp:`MultiFab` with a new :cpp:`BoxArray` with
-  fewer, larger grids, to allow for additional coarsening.
+  to copy the current level of multigrid data to fewer, larger
+  boxes. Two advantages of using this option is that the bottom solver will become
+  smaller, and communication overhead is reduced.
+
+- :cpp:`LPInfo::setAgglomerationGridSize(int)` controls the grid-length
+  threshold used for agglomeration. By default, the threshold length is set
+  to 32 for GPU builds, and 8, 16 and 32 for CPU builds in 1D, 2D and 3D,
+  respectively. The corresponding volume threshold is :math:`L^D`, where
+  :math:`L` is the length threshold and :math:`D` is
+  :cpp:`AMREX_SPACEDIM`. When the average box volume falls below this volume
+  threshold, boxes are agglomerated until this is no longer the case. Note
+  that this action is recursive and can happen at several different levels
+  in the multigrid hierarchy.
 
 - :cpp:`LPInfo::setConsolidation(bool)` (by default true) can be used
   continue to transfer a multigrid problem to fewer MPI ranks.
   There are more setting such as :cpp:`LPInfo::setConsolidationGridSize(int)`,
   :cpp:`LPInfo::setConsolidationRatio(int)`, and
   :cpp:`LPInfo::setConsolidationStrategy(int)`, to give control over how this
-  process works.
-
+  process works.  If agglomeration is used, consolidation is ignored.
 
 :cpp:`MLMG::setThrowException(bool)` controls whether multigrid failure results
 in aborting (default) or throwing an exception, whereby control will return to the calling