clean up the MG docs (#234)

Author: zingale

docs/source/multigrid.rst

@@ -1,7 +1,47 @@
 Multigrid Solvers
 =================
 
+pyro solves elliptic problems (like Laplace's equation or Poisson's
+equation) through multigrid. This accelerates the convergence of
+qsimple relaxation by moving the solution down and up through a series
+of grids. Chapter 9 of the `pdf notes <http://open-astrophysics-bookshelf.github.io/numerical_exercises/CompHydroTutorial.pdf>`_ gives an introduction to solving elliptic equations, including multigrid.
+
+There are three solvers:
+
+* The core solver, provided in the class :func:`MG.CellCenterMG2d <pyro.multigrid.MG.CellCenterMG2d>` solves constant-coefficient Helmholtz problems of the form
+
+  $$(\alpha - \beta \nabla^2) \phi = f$$
+
+* The class :func:`variable_coeff_MG.VarCoeffCCMG2d <pyro.multigrid.variable_coeff_MG.VarCoeffCCMG2d>` solves variable coefficient Poisson problems of the form
+
+  $$\nabla \cdot (\eta \nabla \phi ) = f`$$
+
+  This class inherits the core functionality from ``MG.CellCenterMG2d``.
+
+* The class :func:`general_MG.GeneralMG2d <pyro.multigrid.general_MG.GeneralMG2d>` solves a general elliptic
+  equation of the form
+
+  $$`\alpha \phi + \nabla \cdot ( \beta \nabla \phi) + \gamma \cdot \nabla \phi = f`$$
+
+  This class inherits
+  the core functionality from :func:`MG.CellCenterMG2d <pyro.multigrid.MG.CellCenterMG2d>`.
+
+  This solver is the only one to support inhomogeneous boundary
+  conditions.
+
+We simply use V-cycles in our implementation, and restrict ourselves
+to square grids with zoning a power of 2.
+
+.. note::
+
+   The multigrid solver is not controlled through ``pyro_sim.py``
+   since there is no time-dependence in pure elliptic problems. Instead,
+   there are a few scripts in the multigrid/ subdirectory that
+   demonstrate its use.
+
+
 .. toctree::
+   :hidden:
 
    multigrid_basics
    multigrid-constant-coefficients

docs/source/multigrid_basics.rst

@@ -1,40 +1,9 @@
-Multigrid Class Overview
-========================
+Simple Multigrid Examples
+=========================
 
-pyro solves elliptic problems (like Laplace's equation or Poisson's
-equation) through multigrid. This accelerates the convergence of
-simple relaxation by moving the solution down and up through a series
-of grids. Chapter 9 of the `pdf notes <http://open-astrophysics-bookshelf.github.io/numerical_exercises/CompHydroTutorial.pdf>`_ gives an introduction to solving elliptic equations, including multigrid.
 
-There are three solvers:
-
-* The core solver, provided in the class :func:`MG.CellCenterMG2d <pyro.multigrid.MG.CellCenterMG2d>` solves constant-coefficient Helmholtz problems of the form
-  :math:`(\alpha - \beta \nabla^2) \phi = f`
-
-* The class :func:`variable_coeff_MG.VarCoeffCCMG2d <pyro.multigrid.variable_coeff_MG.VarCoeffCCMG2d>` solves variable coefficient Poisson problems of the form
-  :math:`\nabla \cdot (\eta \nabla \phi ) = f`.  This class inherits the core functionality from ``MG.CellCenterMG2d``.
-
-* The class :func:`general_MG.GeneralMG2d <pyro.multigrid.general_MG.GeneralMG2d>` solves a general elliptic
-  equation of the form :math:`\alpha \phi + \nabla \cdot ( \beta
-  \nabla \phi) + \gamma \cdot \nabla \phi = f`.  This class inherits
-  the core functionality from :func:`MG.CellCenterMG2d <pyro.multigrid.MG.CellCenterMG2d>`.
-
-  This solver is the only one to support inhomogeneous boundary
-  conditions.
-
-We simply use V-cycles in our implementation, and restrict ourselves
-to square grids with zoning a power of 2.
-
-The multigrid solver is not controlled through ``pyro_sim.py`` since
-there is no time-dependence in pure elliptic problems. Instead, there
-are a few scripts in the multigrid/ subdirectory that demonstrate its
-use.
-
-Simple Examples
----------------
-
-multigrid test
-^^^^^^^^^^^^^^
+Known Solution
+--------------
 
 A basic multigrid test is run as (using a path relative to the root of the
 ``pyro2`` repository):
@@ -43,7 +12,7 @@ A basic multigrid test is run as (using a path relative to the root of the
 
    ./pyro/multigrid/examples/mg_test_simple.py
 
-The ``mg_test_simple.py`` script solves a Poisson equation with a
+The `mg_test_simple.py <https://github.com/python-hydro/pyro2/blob/main/pyro/multigrid/examples/mg_test_simple.py>`_ script solves a Poisson equation with a
 known analytic solution. This particular example comes from the text
 `A Multigrid Tutorial, 2nd Ed.`, by Briggs. The example is:
 
@@ -88,23 +57,25 @@ You can run this example locally by running the ``mg_vis.py`` script:
 
    ./pyro/multigrid/examples/mg_vis.py
 
-projection
-^^^^^^^^^^
+Projection
+----------
 
 Another example uses multigrid to extract the divergence free part of a velocity
-field.  This is run as:
+field.  The script to run this is `project_periodic.py <https://github.com/python-hydro/pyro2/blob/main/pyro/multigrid/examples/project_periodic.py>`_.  This is run as:
 
 .. prompt:: bash
 
    ./pyro/multigrid/examples/project_periodic.py
 
-Given a vector field, :math:`U`, we can decompose it into a divergence free part, :math:`U_d`, and the gradient of a scalar, :math:`\phi`:
+Given a vector field, :math:`U`, we can decompose it into a divergence
+free part, :math:`U_d`, and the gradient of a scalar, :math:`\phi`:
 
 .. math::
 
    U = U_d + \nabla \phi
 
-We can project out the divergence free part by taking the divergence, leading to an elliptic equation:
+We can project out the divergence free part by taking the divergence,
+leading to an elliptic equation:
 
 .. math::
 
@@ -120,6 +91,7 @@ results are shown below:
    :align: center
 
 
-Left is the original u velocity, middle is the modified field after adding the gradient of the scalar, and right is the recovered field.
+Left is the original u velocity, middle is the modified field after
+adding the gradient of the scalar, and right is the recovered field.