add available problems and their runtime parameters to the docs (#269)

this adds a script to the build process to generate the problem definitions.
This also fixes a bunch of docs errors and makes the solver pages more consistent

Author: zingale

.gitignore

@@ -9,6 +9,8 @@ dist/
 inputs.auto
 .noseids
 
+*problems.inc
+
 .ipynb_checkpoints/
 
 *.pdf

docs/Makefile

@@ -17,4 +17,5 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	./document_problems.py
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/document_problems.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python
+
+import importlib
+from pathlib import Path
+
+SOLVERS = ["advection",
+           "advection_fv4",
+           "advection_nonuniform",
+           "advection_rk",
+           "advection_weno",
+           "burgers",
+           "burgers_viscous",
+           "compressible",
+           "compressible_fv4",
+           "compressible_react",
+           "compressible_rk",
+           "compressible_sdc",
+           "diffusion",
+           "incompressible",
+           "incompressible_viscous",
+           "lm_atm",
+           "swe"]
+
+MAX_LEN = 36
+
+
+def doit(pyro_home):
+
+    for s in SOLVERS:
+
+        # check it the problems/ directory is not a softlink to
+        # a different solver
+
+        p = Path(f"{pyro_home}/pyro/{s}/problems").resolve()
+
+        with open(f"{pyro_home}/docs/source/{s}_problems.inc", "w") as finc:
+
+            finc.write("supported problems\n")
+            finc.write("------------------\n")
+
+            if (parent_solver := p.parts[-2]) == s:
+
+                # find all the problems
+                for prob in p.glob("*.py"):
+                    if prob.name == "__init__.py":
+                        continue
+
+                    mprob = importlib.import_module(f"pyro.{s}.problems.{prob.stem}")
+
+                    if "init_data" not in dir(mprob):
+                        # not a problem setup
+                        continue
+
+                    finc.write(f"``{prob.stem}``\n")
+                    finc.write("^" * (len(prob.stem)+4) + "\n\n")
+
+                    if mprob.__doc__:
+                        finc.write(mprob.__doc__)
+
+                    finc.write("\n")
+
+                    try:
+                        params = mprob.PROBLEM_PARAMS
+                    except AttributeError:
+                        params = {}
+
+                    if params:
+                        finc.write("parameters: \n\n")
+
+                        finc.write("="*MAX_LEN + " " + "="*MAX_LEN + "\n")
+                        finc.write(f"{'name':{MAX_LEN}} {'default':{MAX_LEN}}\n")
+                        finc.write("="*MAX_LEN + " " + "="*MAX_LEN + "\n")
+
+                        for k, v in params.items():
+                            pname = "``" + k + "``"
+                            finc.write(f"{pname:{MAX_LEN}} {v:{MAX_LEN}}\n")
+
+                        finc.write("="*MAX_LEN + " " + "="*MAX_LEN + "\n")
+
+
+                    finc.write("\n\n")
+
+            else:
+                finc.write(f"``{s}`` uses the problems defined by ``{parent_solver}``.")
+
+
+if __name__ == "__main__":
+    doit("..")

docs/source/advection_basics.rst

@@ -1,5 +1,6 @@
-Advection solvers
-=================
+*********
+Advection
+*********
 
 The linear advection equation:
 
@@ -14,7 +15,7 @@ pyro has several solvers for linear advection, which solve the equation
 with different spatial and temporal integration schemes.
 
 ``advection`` solver
---------------------
+====================
 
 :py:mod:`pyro.advection` implements the directionally unsplit corner
 transport upwind algorithm :cite:`colella:1990` with piecewise linear reconstruction.
@@ -29,9 +30,10 @@ The parameters for this solver are:
 
 .. include:: advection_defaults.inc
 
+.. include:: advection_problems.inc
 
 ``advection_fv4`` solver
-------------------------
+========================
 
 :py:mod:`pyro.advection_fv4` uses a fourth-order accurate finite-volume
 method with RK4 time integration, following the ideas in
@@ -50,8 +52,10 @@ The parameters for this solver are:
 
 .. include:: advection_fv4_defaults.inc
 
+.. include:: advection_fv4_problems.inc
+
 ``advection_nonuniform`` solver
--------------------------------
+===============================
 
 :py:mod:`pyro.advection_nonuniform` models advection with a non-uniform
 velocity field.  This is used to implement the slotted disk problem
@@ -62,8 +66,11 @@ The parameters for this solver are:
 
 .. include:: advection_nonuniform_defaults.inc
 
+.. include:: advection_nonuniform_problems.inc
+
+
 ``advection_rk`` solver
------------------------
+=======================
 
 :py:mod:`pyro.advection_rk` uses a method of lines time-integration
 approach with piecewise linear spatial reconstruction for linear
@@ -76,8 +83,10 @@ The parameter for this solver are:
 
 .. include:: advection_rk_defaults.inc
 
+.. include:: advection_rk_problems.inc
+
 ``advection_weno`` solver
--------------------------
+=========================
 
 :py:mod:`pyro.advection_weno` uses a WENO reconstruction and method of
 lines time-integration
@@ -87,9 +96,11 @@ The main parameters that affect this solver are:
 
 .. include:: advection_weno_defaults.inc
 
+.. include:: advection_weno_problems.inc
+
 
 General ideas
--------------
+=============
 
 The main use for the advection solver is to understand how Godunov
 techniques work for hyperbolic problems. These same ideas will be used
@@ -108,10 +119,10 @@ reconstruction, evolution, and averaging steps:
 
 
 Examples
---------
+========
 
 smooth
-^^^^^^
+------
 
 The smooth problem initializes a Gaussian profile and advects it with
 :math:`u = v = 1` through periodic boundaries for a period. The result is that
@@ -147,22 +158,15 @@ with the ``advection_fv4`` solver.  Departures from perfect scaling
 are likely due to the use of limiters.
 
 
-tophat
-^^^^^^
-
-The tophat problem initializes a circle in the center of the domain
-with value 1, and 0 outside. This has very steep jumps, and the
-limiters will kick in strongly here.
-
 Exercises
----------
+=========
 
 The best way to learn these methods is to play with them yourself. The
 exercises below are suggestions for explorations and features to add
 to the advection solver.
 
 Explorations
-^^^^^^^^^^^^
+------------
 
 * Test the convergence of the solver for a variety of initial
   conditions (tophat hat will differ from the smooth case because of
@@ -175,7 +179,7 @@ Explorations
   problem?)
 
 Extensions
-^^^^^^^^^^
+----------
 
 * Implement a dimensionally split version of the advection
   algorithm. How does the solution compare between the unsplit and

docs/source/burgers_basics.rst

@@ -1,10 +1,13 @@
+*****************
 Burgers' Equation
-==================
+*****************
 
-Burgers' Equation is a nonlinear hyperbolic equation. It has the same form as the advection equation, except that the quantity being advected is the velocity itself.
+Burgers' Equation is a nonlinear hyperbolic equation. It has the same
+form as the advection equation, except that the quantity being
+advected is the velocity itself.
 
 ``Inviscid Burgers``
---------------------------------
+====================
 
 A 2D inviscid Burgers' Equation has the following form:
 
@@ -29,14 +32,25 @@ The parameters for this solver are:
 
 .. include:: burgers_defaults.inc
 
+.. include:: burgers_problems.inc
+
+Example
+-------
 
 .. image:: burgers.png
    :align: center
 
-The figure above is generated using ``burgers/problems/test.py``, which is used to test the validity of the solver. Bottom-left of the domain has a higher velocity than the top-right domain. With :math:`u_{i,j}=v_{i,j}`, the wave travels diagonally to the top-right with a constant velocity that is equal to the shock speed. ``burgers/problem/verify.py`` can be used to calculate the wave speed using outputs from ``test.py`` and compare to the theoretical shock speed.
+The figure above is generated using ``burgers/problems/test.py``,
+which is used to test the validity of the solver. Bottom-left of the
+domain has a higher velocity than the top-right domain. With
+:math:`u_{i,j}=v_{i,j}`, the wave travels diagonally to the top-right
+with a constant velocity that is equal to the shock
+speed. ``burgers/problem/verify.py`` can be used to calculate the wave
+speed using outputs from ``test.py`` and compare to the theoretical
+shock speed.
 
 ``Viscous Burgers``
---------------------------------
+===================
 
 A 2D viscous Burgers' Equation has the following form:
 
@@ -60,6 +74,10 @@ The parameters for this solver are:
 
 .. include:: burgers_viscous_defaults.inc
 
+.. include:: burgers_problems.inc
+
+Example
+-------
 
 .. image:: viscous_burgers.png
    :align: center