better API styling (#32)

this uses the numpydoc standard

Author: zingale

docs/_config.yml

@@ -25,8 +25,8 @@ repository:
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
 html:
-  use_issues_button: true
-  use_repository_button: true
+  use_issues_button: True
+  use_repository_button: True
   extra_footer: |
     <p>
     &copy; 2024; CC-BY-NC-SA 4.0
@@ -35,13 +35,12 @@ html:
 sphinx:
   extra_extensions:
   - 'sphinx.ext.autodoc'
-  - 'sphinx.ext.autosummary'
+  - 'sphinx.ext.napoleon'
+  - 'sphinx.ext.viewcode'
   config:
-    html_show_copyright: false
-    nbsphinx_timeout: 300
+    add_module_names: False
+    html_show_copyright: False
     nb_execution_timeout: 300
-    linkcheck_ignore: "https://ieeexplore.ieee.org/document/9994215"
-    autosummary_generate: True
 
 launch_buttons:
    binderhub_url: "https://mybinder.org"

docs/api.rst

@@ -8,9 +8,29 @@
 
 def eigen(rho, u, p, gamma):
     """Compute the left and right eigenvectors and the eigenvalues for
-    the Euler equations.  q is a single zone primitive variable state,
-    v is a FluidVars object that identifies the components of q
+    the Euler equations.
 
+    Parameters
+    ----------
+    rho : ndarray
+        density
+    u : ndarray
+        velocity
+    p : ndarray
+        pressure
+    gamma : float
+        ratio of specific heats
+
+    Returns
+    -------
+    ev : ndarray
+        array of eigenvalues
+    lvec : ndarray
+        matrix of left eigenvectors, `lvec(iwave, :)` is
+        the eigenvector for wave iwave
+    rvec : ndarray
+        matrix of right eigenvectors, `rvec(iwave, :)` is
+        the eigenvector for wave iwave
     """
 
     # The Jacobian matrix for the primitive variable formulation of the

ppmpy/eigen.py

@@ -33,6 +33,44 @@ class Euler:
     """A 1D compressible Euler solver using the piecewise parabolic method
     (PPM), following the original Colella & Woodward ideas
 
+    Parameters
+    ----------
+    nx : int
+        the number of zones
+    C : float
+        the CFL number
+    fixed_dt : float, optional
+        a fixed timestep to use for every step.  In this case we
+        do not estimate the timestep using the CFL criteria.
+    bc_left_type : str
+        boundary condition type at the left edge.  Allowed values
+        are: "reflect", "outflow", "periodic"
+    bc_left_type : str
+        boundary condition type at the right edge.  Allowed values
+        are: "reflect", "outflow", "periodic"
+    gamma : float
+        the ratio of specific heats
+    init_cond : function
+        the function to call to initialize the conserved state.
+        This has the signature `init_cond(grid, v, gamma, U, params)`
+        where `grid` is a `FVGrid`, `v` is a `FluidVars`, and `params`
+        is a `dict` with any optional parameters needed for
+        initialization.
+    grav_func : function
+        the function to call to compute the gravitational acceleration.
+        This has the signature: `g = grav_func(grid, rho, params)`, where
+        `grid` is a FVGrid`, `rho` is the density (array), and `params`
+        is a `dict` of option parameters needed to interpret gravity.
+    params : dict, optional
+        a dictionary of parameters that is passed to the initial condition
+        and gravity functions.
+    use_hse_reconstruction : bool, optional
+        do we subtract off HSE from pressure before doing the parabolic
+        reconstruction?
+    use_limiting : bool, optional
+        do we limit the parabola coefficients?
+    use_flattening : bool, optional
+        do we apply flattening to the shock to smear them out?
     """
 
     def __init__(self, nx, C, *,
@@ -111,7 +149,13 @@ def estimate_dt(self):
         self.dt = self.C * self.grid.dx / np.max(np.abs(q[:, self.v.qu]) + cs)
 
     def cons_to_prim(self):
-        """Convert the conserved variable state to primitive variables"""
+        """Convert the conserved variable state to primitive variables
+
+        Returns
+        -------
+        q : ndarray
+            the primitive variable array.
+        """
 
         q = self.grid.scratch_array(nc=self.v.nvar)
 
@@ -163,6 +207,13 @@ def construct_parabola(self):
     def interface_states(self):
         """Trace the primitive variables to the interfaces by integrating
         under the parabola and doing a characteristic projection
+
+        Returns
+        -------
+        q_left : ndarray
+            the left primitive variable state on the interface.
+        q_right : ndarray
+            the right primitive variable state on the interface.
         """
 
         # convert to primitive variables
@@ -266,7 +317,18 @@ def interface_states(self):
         return q_left, q_right
 
     def cons_flux(self, state):
-        """ given an interface state, return the conservative flux"""
+        """ given an interface state, return the conservative flux
+
+        Parameters
+        ----------
+        state : RiemannState
+            the interface state from the Riemann solver.
+
+        Returns
+        -------
+        flux : ndarray
+            the conserved flux through the interface for the input state.
+        """
 
         flux = np.zeros((self.v.nvar), dtype=np.float64)
 
@@ -278,7 +340,20 @@ def cons_flux(self, state):
 
     def compute_fluxes(self, q_left, q_right):
         """given the left and right states, solve the Riemann
-        problem to get the interface state and return the fluxes"""
+        problem to get the interface state and return the fluxes
+
+        Parameters
+        ----------
+        q_left : ndarray
+            the left primitive variable state on the interface.
+        q_right : ndarray
+            the right primitive variable state on the interface.
+
+        Returns
+        -------
+        flux : ndarray
+            the conserved flux through each interface.
+        """
 
         flux = self.grid.scratch_array(nc=self.v.nvar)
 
@@ -327,7 +402,15 @@ def advance_step(self):
                                                         self.U[:, self.v.umx] * g_new)
 
     def evolve(self, tmax, *, verbose=True):
-        """The main evolution driver to advance the state to time tmax"""
+        """The main evolution driver to advance the state to time tmax
+
+        Parameters
+        ----------
+        tmax : float
+            maximum simulation time to evolve to
+        verbose : bool, optional
+            enable / disable verbosity
+        """
 
         while self.t < tmax:
 
@@ -360,7 +443,15 @@ def evolve(self, tmax, *, verbose=True):
                                  bc_right_type=self.bcs_right[n])
 
     def draw_prim(self, gp, ivar):
-        """Draw the parabola for a primitive variable (ivar) on a GridPlot object"""
+        """Draw the parabola for a primitive variable (ivar) on a GridPlot object
+
+        Parameters
+        ----------
+        gp : GridPlot
+            the grid plot object for the figure
+        ivar : int
+            the index of the primitive variable to plot
+        """
 
         self.construct_parabola()
         self.q_parabola[ivar].draw_parabola(gp)

ppmpy/euler.py

@@ -8,20 +8,50 @@
 
 
 class GridPlot:
-    """a container to hold info about the grid figure"""
+    """a container to hold info about the grid figure
+
+    Parameters
+    ----------
+    fig : matplotlib.pyplot.Figure
+         the figure object.
+    ax : matplotlib.pyplot.Axes
+         the axis object.
+    lo_index : int, optional
+         the 0-based zone index for the left edge of the plot.
+    hi_index : int, optional
+         the 0-based zone index for the right edge of the plot.
+    """
+
     def __init__(self, *, fig=None, ax=None, lo_index=None, hi_index=None):
         self.fig = fig
         self.ax = ax
         self.lo_index = lo_index
         self.hi_index = hi_index
 
     def show_fig(self):
-        """return the Figure object"""
+        """return the Figure object
+
+        Returns
+        -------
+        matplotlib.pyplot.Figure
+        """
         return self.fig
 
 
 class FVGrid:
-    """The main finite-volume grid class for holding our fluid state."""
+    """The main finite-volume grid class for holding our fluid state.
+
+    Parameters
+    ----------
+    nx : int
+        number of zones on the grid.
+    ng : int
+        number of ghost cells on each end of the grid.
+    xmin : float, optional
+        minimum x-coordinate.
+    xmax : float, optional
+        maximum x-coordinate.
+    """
 
     def __init__(self, nx, ng, *,
                  xmin=0.0, xmax=1.0):
@@ -43,13 +73,33 @@ def __init__(self, nx, ng, *,
         self.x = xmin + (np.arange(nx+2*ng)-ng+0.5)*self.dx
 
     def scratch_array(self, nc=1):
-        """ return a scratch array dimensioned for our grid """
+        """ return a scratch array dimensioned for our grid
+
+        Parameters
+        ----------
+        nc : int
+            number of components.
+
+        Returns
+        -------
+        ndarray
+        """
         return np.squeeze(np.zeros((self.nq, nc), dtype=np.float64))
 
     def ghost_fill(self, atmp, *,
                    bc_left_type="outflow", bc_right_type="outflow"):
         """fill all ghost cells with zero-gradient boundary
-        conditions"""
+        conditions.
+
+        Parameters
+        ----------
+        atmp : ndarray
+             the array of data defined on the `FVGrid` to fill ghost cells in
+        bc_left_type : string
+             boundary condition type on the left edge of the domain.
+        bc_right_type : string
+             boundary condition type on the left edge of the domain.
+        """
 
         # left
 
@@ -83,15 +133,38 @@ def ghost_fill(self, atmp, *,
             raise ValueError("invalid boundary condition")
 
     def norm(self, e):
-        """compute the L2 norm of array e defined on this grid"""
+        """compute the L2 norm of array e defined on this grid
+
+        Parameters
+        ----------
+        e : ndarray
+             array of data defined on the grid whose norm we want to
+             compute
+
+        Returns
+        -------
+        float
+        """
 
         assert len(e) == self.nq
         return np.sqrt(self.dx * np.sum(e[self.lo:self.hi+1]**2))
 
     def coarsen(self, fdata):
         """coarsen an array fine defined on this grid down to a grid
         with 1/2 the number of zones (but the same number of ghost
-        cells
+        cells.
+
+        Parameters
+        ----------
+        fdata : ndarray
+            The data defined on this `FVGrid` object.
+
+        Returns
+        -------
+        FVGrid
+            The coarse grid object.
+        ndarray
+            The coarsened data on the coarse grid.
 
         """
 
@@ -106,7 +179,22 @@ def coarsen(self, fdata):
 
     def draw(self, *, lo_index=None, hi_index=None, stretch=1):
         """Draw a finite volume representation of the grid and return the
-        figure and axis objects"""
+        figure and axis objects
+
+
+        Parameters
+        ----------
+        lo_index : int
+            0-based zone index to start the grid plot.
+        hi_index : int
+            0-based zone index to end the grid plot.
+        stretch : float
+            factor by which to stretch the vertical axis
+
+        Returns
+        -------
+        GridPlot
+        """
 
         fig, ax = plt.subplots()
 
@@ -120,6 +208,8 @@ def draw(self, *, lo_index=None, hi_index=None, stretch=1):
         else:
             nstop = hi_index
 
+        assert nstop > nstart
+
         ax.plot([self.xl[nstart], self.xr[nstop]], [0, 0], color="0.25", lw=2)
 
         # draw edges