Minor docs improvements (#172)

yut23 · web-flow · commit 5315369f9ad4 · 2023-04-26T14:17:22.000-04:00
* Add full citations for papers referenced in incompressible examples
* Fix some broken links in the README
* Lots of spelling fixes from codespell
diff --git a/README.md b/README.md
@@ -83,14 +83,14 @@ https://python-hydro.github.io/pyro2
       ```python
       import matplotlib.pyplot
       print matplotlib.pyplot.get_backend()
-       ```
+      ```
 
  - If you want to run the unit tests, you need to have `pytest` installed.
 
  - Finally, you can run a quick test of the advection solver:
 
    ```
-   pyro-sim.py advection smooth inputs.smooth
+   pyro_sim.py advection smooth inputs.smooth
    ```
 
    you should see a graphing window pop up with a smooth pulse
@@ -102,13 +102,13 @@ https://python-hydro.github.io/pyro2
 The main data structures that describe the grid and the data the lives
 on the grid are described in a jupyter notebook:
 
-https://github.com/python-hydro/pyro2/blob/main/mesh/mesh-examples.ipynb
+https://github.com/python-hydro/pyro2/blob/main/pyro/mesh/mesh-examples.ipynb
 
 
 Many of the methods here rely on multigrid.  The multigrid solver is
 demonstrated in the juputer notebook:
 
-https://github.com/python-hydro/pyro2/blob/main/multigrid/multigrid-examples.ipynb
+https://github.com/python-hydro/pyro2/blob/main/pyro/multigrid/multigrid-examples.ipynb
 
 
 ## Solvers
@@ -136,16 +136,16 @@ pyro provides the following solvers (all in 2-d):
 
   - `compressible`: a second-order unsplit solver for the Euler
     equations of compressible hydrodynamics.  This uses characteristic
-	tracing and corner coupling for the prediction of the interface
-	states and a 2-shock or HLLC approximate Riemann solver.
+    tracing and corner coupling for the prediction of the interface
+    states and a 2-shock or HLLC approximate Riemann solver.
 
   - `compressible_fv4`: a fourth-order accurate finite-volume compressible
      hydro solver that uses RK4 time integration.  This is built from the
      method of McCourquodale and Colella (2011).
 
   - `compressible_rk`: a second-order unsplit solver for Euler
      equations that uses Runge-Kutta integration instead of
-	 characteristic tracing.
+     characteristic tracing.
 
   - `compressible_sdc`: a fourth-order compressible solver,
      using spectral-deferred correction (SDC) for the time integration.
diff --git a/docs/source/_defaults.inc b/docs/source/_defaults.inc
@@ -35,7 +35,7 @@
   +----------------------------------+----------------+----------------------------------------------------+
   | option                           | value          | description                                        |
   +==================================+================+====================================================+
-  | xmin                             | ``0.0``        | domain minumum x-coordinate                        |
+  | xmin                             | ``0.0``        | domain minimum x-coordinate                        |
   +----------------------------------+----------------+----------------------------------------------------+
   | xmax                             | ``1.0``        | domain maximum x-coordinate                        |
   +----------------------------------+----------------+----------------------------------------------------+
diff --git a/docs/source/ack.rst b/docs/source/ack.rst
@@ -37,7 +37,7 @@ Bell, and Andy Nonaka.
 History
 =======
 
-The original pyro code was written in 2003-4 to help developmer
+The original pyro code was written in 2003-4 to help developer
 Zingale understand these methods for himself. It was originally written
 using the Numeric array package and handwritten C extensions for the
 compute-intensive kernels.  It was ported to numarray when that
diff --git a/docs/source/advection_basics.rst b/docs/source/advection_basics.rst
@@ -11,7 +11,7 @@ compressible hydrodynamics. Chapter 4 of the notes summarizes the
 numerical methods for advection that we implement in pyro.
 
 pyro has several solvers for linear advection, which solve the equation
-with different spatial and temporal intergration schemes.
+with different spatial and temporal integration schemes.
 
 ``advection`` solver
 --------------------
@@ -58,7 +58,7 @@ velocity field.  This is used to implement the slotted disk problem
 from :cite:`ZALESAK1979335`.  The basic method is similar to the
 algorithm used by the main ``advection`` solver.
 
-The paramters for this solver are:
+The parameters for this solver are:
 
 .. include:: advection_nonuniform_defaults.inc
 
diff --git a/docs/source/advection_rk_defaults.inc b/docs/source/advection_rk_defaults.inc
@@ -9,7 +9,7 @@
   +----------------------------------+----------------+----------------------------------------------------+
   | limiter                          | ``2``          | limiter (0 = none, 1 = 2nd order, 2 = 4th order)   |
   +----------------------------------+----------------+----------------------------------------------------+
-  | temporal_method                  | ``RK4``        | integration method (see mesh/integrators/.py)      |
+  | temporal_method                  | ``RK4``        | integration method (see mesh/integrators.py)       |
   +----------------------------------+----------------+----------------------------------------------------+
 
 * section: [driver]
diff --git a/docs/source/advection_weno_defaults.inc b/docs/source/advection_weno_defaults.inc
@@ -12,7 +12,7 @@
   +----------------------------------+----------------+----------------------------------------------------+
   | weno_order                       | ``3``          | k in WENO scheme                                   |
   +----------------------------------+----------------+----------------------------------------------------+
-  | temporal_method                  | ``RK4``        | integration method (see mesh/integrators/.py)      |
+  | temporal_method                  | ``RK4``        | integration method (see mesh/integrators.py)       |
   +----------------------------------+----------------+----------------------------------------------------+
 
 * section: [driver]
diff --git a/docs/source/analysis.rst b/docs/source/analysis.rst
@@ -26,7 +26,8 @@ with their data.
     resolutions (one a factor of N-times, (default is 2 times or ``N=2``) finer
     than the other). It coarsens the finer data and then computes the
     norm of the difference.  The default variable being compared is
-    density, ``var_name=density`` by default. but it takes arbitary variable name as input.
+    density, but a different variable can be selected with the
+    ``var_name`` argument.
     This is used to test the convergence of solvers.
 
     usage: ``./convergence.py fine_file coarse_file var_name N``
@@ -47,7 +48,7 @@ with their data.
     when there is no analytical solutions.
 
     usage: ``./convergence_plot.py files* -o out -n order -r resolution``
-  
+
   * ``dam_compare.py``: this takes an output file from the
     shallow water dam break problem and plots a slice through the domain
     together with the analytic solution (calculated in the script).
@@ -83,7 +84,7 @@ with their data.
 
   * ``smooth_error.py``: this takes an output file from the advection
     solver's smooth problem and compares to the analytic solution,
-    outputing the L2 norm of the error.
+    outputting the L2 norm of the error.
 
     usage: ``./smooth_error.py file``
 
diff --git a/docs/source/compressible_defaults.inc b/docs/source/compressible_defaults.inc
@@ -11,7 +11,7 @@
   +----------------------------------+----------------+----------------------------------------------------+
   | delta                            | ``0.33``       | flattening delta parameter                         |
   +----------------------------------+----------------+----------------------------------------------------+
-  | cvisc                            | ``0.1``        | artifical viscosity coefficient                    |
+  | cvisc                            | ``0.1``        | artificial viscosity coefficient                   |
   +----------------------------------+----------------+----------------------------------------------------+
   | limiter                          | ``2``          | limiter (0 = none, 1 = 2nd order, 2 = 4th order)   |
   +----------------------------------+----------------+----------------------------------------------------+
diff --git a/docs/source/compressible_fv4_defaults.inc b/docs/source/compressible_fv4_defaults.inc
@@ -11,7 +11,7 @@
   +----------------------------------+----------------+----------------------------------------------------+
   | delta                            | ``0.33``       | flattening delta parameter                         |
   +----------------------------------+----------------+----------------------------------------------------+
-  | cvisc                            | ``0.1``        | artifical viscosity coefficient                    |
+  | cvisc                            | ``0.1``        | artificial viscosity coefficient                   |
   +----------------------------------+----------------+----------------------------------------------------+
   | limiter                          | ``2``          | limiter (0 = none, 1 = 2nd order, 2 = 4th order)   |
   +----------------------------------+----------------+----------------------------------------------------+
diff --git a/docs/source/compressible_react_defaults.inc b/docs/source/compressible_react_defaults.inc
@@ -11,7 +11,7 @@
   +----------------------------------+----------------+----------------------------------------------------+
   | delta                            | ``0.33``       | flattening delta parameter                         |
   +----------------------------------+----------------+----------------------------------------------------+
-  | cvisc                            | ``0.1``        | artifical viscosity coefficient                    |
+  | cvisc                            | ``0.1``        | artificial viscosity coefficient                   |
   +----------------------------------+----------------+----------------------------------------------------+
   | limiter                          | ``2``          | limiter (0 = none, 1 = 2nd order, 2 = 4th order)   |
   +----------------------------------+----------------+----------------------------------------------------+
diff --git a/docs/source/compressible_rk_defaults.inc b/docs/source/compressible_rk_defaults.inc
@@ -11,7 +11,7 @@
   +----------------------------------+----------------+----------------------------------------------------+
   | delta                            | ``0.33``       | flattening delta parameter                         |
   +----------------------------------+----------------+----------------------------------------------------+
-  | cvisc                            | ``0.1``        | artifical viscosity coefficient                    |
+  | cvisc                            | ``0.1``        | artificial viscosity coefficient                   |
   +----------------------------------+----------------+----------------------------------------------------+
   | limiter                          | ``2``          | limiter (0 = none, 1 = 2nd order, 2 = 4th order)   |
   +----------------------------------+----------------+----------------------------------------------------+
diff --git a/docs/source/compressible_sdc_defaults.inc b/docs/source/compressible_sdc_defaults.inc
@@ -11,7 +11,7 @@
   +----------------------------------+----------------+----------------------------------------------------+
   | delta                            | ``0.33``       | flattening delta parameter                         |
   +----------------------------------+----------------+----------------------------------------------------+
-  | cvisc                            | ``0.1``        | artifical viscosity coefficient                    |
+  | cvisc                            | ``0.1``        | artificial viscosity coefficient                   |
   +----------------------------------+----------------+----------------------------------------------------+
   | limiter                          | ``2``          | limiter (0 = none, 1 = 2nd order, 2 = 4th order)   |
   +----------------------------------+----------------+----------------------------------------------------+
diff --git a/docs/source/compressible_sr_defaults.inc b/docs/source/compressible_sr_defaults.inc
@@ -11,7 +11,7 @@
   +----------------------------------+----------------+----------------------------------------------------+
   | delta                            | ``0.33``       | flattening delta parameter                         |
   +----------------------------------+----------------+----------------------------------------------------+
-  | cvisc                            | ``0.1``        | artifical viscosity coefficient                    |
+  | cvisc                            | ``0.1``        | artificial viscosity coefficient                   |
   +----------------------------------+----------------+----------------------------------------------------+
   | limiter                          | ``2``          | limiter (0 = none, 1 = 2nd order, 2 = 4th order)   |
   +----------------------------------+----------------+----------------------------------------------------+
diff --git a/docs/source/diffusion_basics.rst b/docs/source/diffusion_basics.rst
@@ -66,9 +66,9 @@ Explorations
 Extensions
 ^^^^^^^^^^
 
-* Switch from Crank-Nicolson (2nd order in time) to backward's Euler
+* Switch from Crank-Nicolson (2nd order in time) to backward Euler
   (1st order in time) and compare the solution and convergence. This
-  should only require changing the source term and coefficents used in
+  should only require changing the source term and coefficients used in
   setting up the multigrid solve. It does not require changes to the
   multigrid solver itself.
 
diff --git a/docs/source/help.rst b/docs/source/help.rst
@@ -43,7 +43,7 @@ used for a squashed commit message.*
 Discussions
 -----------
 
-We us github discussions:
+We use github discussions:
 https://github.com/python-hydro/pyro2/discussions
 for support.  You are encouraged to post in the discussions
 to ask questions.
diff --git a/docs/source/incompressible_basics.rst b/docs/source/incompressible_basics.rst
@@ -29,8 +29,8 @@ shear
 The shear problem initializes a shear layer in a domain with
 doubly-periodic boundaries and looks at the development of two
 vortices as the shear layer rolls up. This problem was explored in a
-number of papers, for example, Bell, Colella, & Glaz (1989) and Martin
-& Colella (2000). This is run as:
+number of papers, for example, :cite:`bellcolellaglaz:1989` and
+:cite:`martincolella:2000`. This is run as:
 
 .. prompt:: bash
 
@@ -51,9 +51,9 @@ The convergence test initializes a simple velocity field on a periodic
 unit square with known analytic solution. By evolving at a variety of
 resolutions and comparing to the analytic solution, we can measure the
 convergence rate of the algorithm. The particular set of initial
-conditions is from Minion (1996). Limiting can be disabled by adding
-``incompressible.limiter=0`` to the run command. The basic set of tests
-shown below are run as:
+conditions is from :cite:`minion:1996`. Limiting can be disabled by
+adding ``incompressible.limiter=0`` to the run command. The basic set of
+tests shown below are run as:
 
 .. prompt:: bash
 
@@ -109,7 +109,7 @@ Extensions
 
 * Switch to a variable density system. This will require adding a mass
   continuity equation that is advected and switching the projections
-  to a variable-coeffient form (since ρ now enters).
+  to a variable-coefficient form (since ρ now enters).
 
 Going further
 -------------
diff --git a/docs/source/particles_basics.rst b/docs/source/particles_basics.rst
@@ -42,7 +42,7 @@ The particles can be initialized in a number of ways:
   :func:`Particles <pyro.particles.particles.Particles>` constructor. This function takes the number of particles to be
   generated and returns a dictionary of :func:`Particle <pyro.particles.particles.Particle>` objects.
 
-We can turn on/off the particles solver using the following runtime paramters:
+We can turn on/off the particles solver using the following runtime parameters:
 
 +--------------------------------------------------------------------------------+
 |``[particles]``                                                                 |
diff --git a/docs/source/refs.bib b/docs/source/refs.bib
@@ -58,3 +58,46 @@ @article{chao:1999
   pages = {1210-1215},
   year = {1999}
 }
+
+@ARTICLE{bellcolellaglaz:1989,
+       author = {{Bell}, John B. and {Colella}, Phillip and {Glaz}, Harland M.},
+        title = "{A Second Order Projection Method for the Incompressible Navier-Stokes Equations}",
+      journal = {Journal of Computational Physics},
+         year = 1989,
+        month = dec,
+       volume = {85},
+       number = {2},
+        pages = {257-283},
+          doi = {10.1016/0021-9991(89)90151-4},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/1989JCoPh..85..257B},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@ARTICLE{martincolella:2000,
+       author = {{Martin}, Daniel F. and {Colella}, Phillip},
+        title = "{A Cell-Centered Adaptive Projection Method for the Incompressible Euler Equations}",
+      journal = {Journal of Computational Physics},
+     keywords = {adaptive mesh refinement},
+         year = 2000,
+        month = sep,
+       volume = {163},
+       number = {2},
+        pages = {271-312},
+          doi = {10.1006/jcph.2000.6575},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2000JCoPh.163..271M},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@ARTICLE{minion:1996,
+       author = {{Minion}, Michael L.},
+        title = "{A Projection Method for Locally Refined Grids}",
+      journal = {Journal of Computational Physics},
+         year = 1996,
+        month = aug,
+       volume = {127},
+       number = {1},
+        pages = {158-178},
+          doi = {10.1006/jcph.1996.0166},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/1996JCoPh.127..158M},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
diff --git a/docs/source/swe_basics.rst b/docs/source/swe_basics.rst
@@ -26,11 +26,11 @@ Example problems
 dam
 ^^^
 
-The dam break problem is a standard hydrodynamics problem, analagous to the Sod
+The dam break problem is a standard hydrodynamics problem, analogous to the Sod
 shock tube problem in compressible hydrodynamics. It considers a one-multidimensional
 problem of two regions of fluid at different heights, initially separated by a dam.
 The problem then models the evolution of the system when this dam is removed.
-As for the Sod problem, there exists an exact solution for the dam break probem,
+As for the Sod problem, there exists an exact solution for the dam break problem,
 so we can check our solution against the exact solutions. See Toro's shallow water
 equations book for details on this problem and the exact Riemann solver.
 
@@ -44,7 +44,7 @@ y-directions. It can be run as:
 
 A simple script, ``dam_compare.py`` in ``analysis/`` will read a pyro
 output file and plot the solution over the exact dam break solution
-(as given by :cite:`stoker:1958` and :cite:`chao:1999`.  Below we see
+(as given by :cite:`stoker:1958` and :cite:`chao:1999`).  Below we see
 the result for a dam break run with 128 points in the x-direction, and
 run until t = 0.3 s.
 
diff --git a/docs/source/swe_defaults.inc b/docs/source/swe_defaults.inc
@@ -23,7 +23,7 @@
   +==================================+================+====================================================+
   | use_flattening                   | ``0``          | apply flattening at shocks (1)                     |
   +----------------------------------+----------------+----------------------------------------------------+
-  | cvisc                            | ``0.1``        | artifical viscosity coefficient                    |
+  | cvisc                            | ``0.1``        | artificial viscosity coefficient                   |
   +----------------------------------+----------------+----------------------------------------------------+
   | limiter                          | ``2``          | limiter (0 = none, 1 = 2nd order, 2 = 4th order)   |
   +----------------------------------+----------------+----------------------------------------------------+
diff --git a/pyro/_defaults b/pyro/_defaults
@@ -25,7 +25,7 @@ store_images = 0           ; store vis images to files (1=yes, 0=no)
 
 [mesh]
 
-xmin = 0.0                ; domain minumum x-coordinate
+xmin = 0.0                ; domain minimum x-coordinate
 xmax = 1.0                ; domain maximum x-coordinate
 ymin = 0.0                ; domain minimum y-coordinate
 ymax = 1.0                ; domain maximum y-coordinate
diff --git a/pyro/advection_rk/_defaults b/pyro/advection_rk/_defaults
@@ -8,6 +8,6 @@ v = 1.0      ; advective velocity in y-direction
 
 limiter = 2  ; limiter (0 = none, 1 = 2nd order, 2 = 4th order)
 
-temporal_method = RK4        ; integration method (see mesh/integrators/.py)
+temporal_method = RK4        ; integration method (see mesh/integrators.py)
 
 
diff --git a/pyro/advection_weno/_defaults b/pyro/advection_weno/_defaults
@@ -10,4 +10,4 @@ limiter = 0  ; Unused here, but needed to inherit from advection base class
 
 weno_order = 3  ; k in WENO scheme
 
-temporal_method = RK4        ; integration method (see mesh/integrators/.py)
+temporal_method = RK4        ; integration method (see mesh/integrators.py)
diff --git a/pyro/compressible/_defaults b/pyro/compressible/_defaults
@@ -13,7 +13,7 @@ z0 = 0.75                 ; flattening z0 parameter
 z1 = 0.85                 ; flattening z1 parameter
 delta = 0.33              ; flattening delta parameter
 
-cvisc = 0.1               ; artifical viscosity coefficient
+cvisc = 0.1               ; artificial viscosity coefficient
 
 limiter = 2               ; limiter (0 = none, 1 = 2nd order, 2 = 4th order)
 
diff --git a/pyro/compressible_fv4/_defaults b/pyro/compressible_fv4/_defaults
diff --git a/pyro/compressible_react/_defaults b/pyro/compressible_react/_defaults
diff --git a/pyro/compressible_rk/_defaults b/pyro/compressible_rk/_defaults
diff --git a/pyro/compressible_sdc/_defaults b/pyro/compressible_sdc/_defaults
diff --git a/pyro/compressible_sr/_defaults b/pyro/compressible_sr/_defaults
diff --git a/pyro/mesh/face-centered-data-examples.ipynb b/pyro/mesh/face-centered-data-examples.ipynb
diff --git a/pyro/mesh/mesh-examples.ipynb b/pyro/mesh/mesh-examples.ipynb
diff --git a/pyro/multigrid/README.md b/pyro/multigrid/README.md
diff --git a/pyro/multigrid/multigrid-general-linear.ipynb b/pyro/multigrid/multigrid-general-linear.ipynb
diff --git a/pyro/swe/_defaults b/pyro/swe/_defaults
