DOC: Fix miscellaneous documentation errors.

pypr · Jan 10, 2021 · 5606c0f · 5606c0f
1 parent eff4f26
commit 5606c0f
Show file tree

Hide file tree

Showing 12 changed files with 96 additions and 80 deletions.
diff --git a/docs/source/reference/tools.rst b/docs/source/reference/tools.rst
@@ -63,9 +63,9 @@ Mayavi Viewer
    :undoc-members:
 
 Mesh Converter
--------------
+--------------
 
 The following functions can be used to convert a mesh file supported by
-'meshio<https://github.com/nschloe/meshio>'_ to a set of surface points.
+`meshio <https://github.com/nschloe/meshio>`_ to a set of surface points.
 
 .. autofunction:: pysph.tools.read_mesh.mesh2points
diff --git a/pysph/solver/application.py b/pysph/solver/application.py
@@ -164,15 +164,15 @@ def create_scheme(self):
       :py:class:`pysph.parallel.parallel_manager.ParallelManager`.
 
     - ``particles``: list of
-      :py:class:`pysph.base.particle_array.ParticleArray`s.
+      :py:class:`pysph.base.particle_array.ParticleArray`.
 
     - ``rank``: Rank of this process.
 
     - ``scheme``: the optional :py:class:`pysph.sph.scheme.Scheme` instance.
 
     - ``solver``: the solver instance, :py:class:`pysph.solver.solver.Solver`.
 
-    - ``tools``: a list of possible :py:class:`pysph.solver.tools.Tool`s.
+    - ``tools``: a list of possible :py:class:`pysph.solver.tools.Tool`.
 
     """
 

diff --git a/pysph/sph/basic_equations.py b/pysph/sph/basic_equations.py
@@ -1,6 +1,16 @@
-"""
-Basic SPH Equations
+"""Basic SPH Equations
 ###################
+
+
+References
+----------
+
+.. [Monaghan1992] J. Monaghan, Smoothed Particle Hydrodynamics, "Annual Review
+    of Astronomy and Astrophysics", 30 (1992), pp. 543-574.
+
+.. [Monaghan2005] J. Monaghan, "Smoothed particle hydrodynamics", Reports on
+    Progress in Physics, 68 (2005), pp. 1703-1759.
+
 """
 
 from pysph.sph.equation import Equation
@@ -209,10 +219,6 @@ class MonaghanArtificialViscosity(Equation):
 
         \bar{\rho}_{ab}&=&\frac{\rho_{a}+\rho_{b}}{2}
 
-    References
-    ----------
-    .. [Monaghan2005] J. Monaghan, "Smoothed particle hydrodynamics",
-        Reports on Progress in Physics, 68 (2005), pp. 1703-1759.
     """
     def __init__(self, dest, sources, alpha=1.0, beta=1.0):
         r"""
@@ -259,10 +265,6 @@ class XSPHCorrection(Equation):
         \frac{d\mathbf{r}_{a}}{dt}=\mathbf{\hat{v}}_{a}=\mathbf{v}_{a}-
         \epsilon\sum_{b}m_{b}\frac{\mathbf{v}_{ab}}{\bar{\rho}_{ab}}W_{ab}
 
-    References
-    ----------
-    .. [Monaghan1992] J. Monaghan, Smoothed Particle Hydrodynamics, "Annual
-        Review of Astronomy and Astrophysics", 30 (1992), pp. 543-574.
     """
     def __init__(self, dest, sources, eps=0.5):
         r"""
@@ -309,10 +311,6 @@ class XSPHCorrectionForLeapFrog(Equation):
         \frac{d\mathbf{r}_{a}}{dt}=\mathbf{\hat{v}}_{a}= -
         \epsilon\sum_{b}m_{b}\frac{\mathbf{v}_{ab}}{\bar{\rho}_{ab}}W_{ab}
 
-    References
-    ----------
-    .. [Monaghan1992] J. Monaghan, Smoothed Particle Hydrodynamics, "Annual
-        Review of Astronomy and Astrophysics", 30 (1992), pp. 543-574.
     """
     def __init__(self, dest, sources, eps=0.5):
         r"""

diff --git a/pysph/sph/bc/inlet_outlet_manager.py b/pysph/sph/bc/inlet_outlet_manager.py
@@ -14,9 +14,9 @@ class InletInfo(object):
     def __init__(self, pa_name, normal, refpoint, has_ghost=True,
                  update_cls=None, equations=None, umax=1.0,
                  props_to_copy=None):
-        """Create object with information of inlets, all the others parameters
-           which are not passed here get evaluated by `InletOutletManager`once
-           the inlet is created.
+        """Create object with information of inlets, all the others parameters which
+           are not passed here get evaluated by `InletOutletManager` once the
+           inlet is created.
 
         Parameters
         ----------
@@ -35,6 +35,7 @@ def __init__(self, pa_name, normal, refpoint, has_ghost=True,
             List of equations (optional)
         props_to_copy : array
             properties to copy
+
         """
 
         self.pa_name = pa_name
@@ -353,8 +354,8 @@ def __init__(self, dest, sources, x, y, z, xn, yn, zn,
            1 : particle is inside the inlet/outlet
            2 : particle is out of inlet/outlet
 
-        parameters:
-        ----------
+        Parameters
+        -----------
 
         dest : str
             destination particle array name
@@ -410,7 +411,7 @@ def __init__(self, dest, sources, xn, yn, zn, xo, yo, zo):
         """Update normal and perpendicular distance from the interface
         for the inlet/outlet particles
 
-        parameters:
+        Parameters
         ----------
 
         dest : str

diff --git a/pysph/sph/gas_dynamics/basic.py b/pysph/sph/gas_dynamics/basic.py
@@ -272,12 +272,15 @@ def loop(self, d_idx, s_idx, d_rho, s_rho, d_p, s_p, d_cs, s_cs,
 
 
 class ADKEAccelerations(Equation):
-    """
-    Reference
-    ---------
-    ..  A comparison of SPH schemes for the compressible Euler equations,
+    """ADKE as discussed in the reference [KP14].
+
+    References
+    ----------
+
+    .. [KP14] A comparison of SPH schemes for the compressible Euler equations,
         2014, Journal of Computational Physics, 256, pp 308 -- 333
-            (http://dx.doi.org/10.1016/j.jcp.2013.08.060)
+        (http://dx.doi.org/10.1016/j.jcp.2013.08.060)
+
     """
     def __init__(self, dest, sources, alpha, beta, g1, g2, k, eps):
         self.alpha = alpha

diff --git a/pysph/sph/integrator.py b/pysph/sph/integrator.py
@@ -390,8 +390,10 @@ class EPECIntegrator(Integrator):
 
     In the EPEC mode, the final corrector can be modified to:
 
-    :math:`y^{n+1} = y^n + \frac{\Delta t}{2}\left( F(y^n) +
-                                F(y^{n+\frac{1}{2}}) \right)`
+    .. math::
+
+        y^{n+1} = y^n + \frac{\Delta t}{2}\left( F(y^n) +
+                                F(y^{n+\frac{1}{2}}) \right)
 
     This would require additional storage for the accelerations.
 

diff --git a/pysph/sph/solid_mech/basic.py b/pysph/sph/solid_mech/basic.py
@@ -388,7 +388,7 @@ def loop(self, d_idx, s_idx, d_rho, s_rho, s_m, d_p, s_p, d_s00, d_s01,
 
 
 class HookesDeviatoricStressRate(Equation):
-    r""" **Rate of change of stress **
+    r""" Rate of change of stress
 
     .. math::
         \frac{dS^{ij}}{dt} = 2\mu\left(\epsilon^{ij} - \frac{1}{3}\delta^{ij}

diff --git a/pysph/sph/surface_tension.py b/pysph/sph/surface_tension.py
@@ -1,19 +1,21 @@
-"""
-Implementation of the equations used for surface tension modelling,
-for example in KHI simulations. The references are as under:
+"""Implementation of the equations used for surface tension modelling, for
+example in KHI simulations. The references are [SY11], [JM00], [A10], [XA06].
+
 
- - M. Shadloo, M. Yildiz, "Numerical modelling of Kelvin-Helmholtz
-   isntability using smoothed particle hydrodynamics", IJNME, 2011,
-   87, pp 988--1006 [SY11]
+References
+----------
 
- - Joseph P. Morris "Simulating surface tension with smoothed particle
-   hydrodynamics", JCP, 2000, 33, pp 333--353 [JM00]
+.. [SY11] M. Shadloo, M. Yildiz, "Numerical modelling of Kelvin-Helmholtz
+   instability using smoothed particle hydrodynamics", IJNME, 2011, 87, pp
+   988--1006
 
- - Adami et al. "A new surface-tension formulation for multi-phase SPH
-   using a reproducing divergence approximation", JCP 2010, 229, pp
-   5011--5021 [A10]
+.. [JM00] Joseph P. Morris "Simulating surface tension with smoothed particle
+   hydrodynamics", JCP, 2000, 33, pp 333--353
 
- - X.Y.Hu, N.A. Adams. "A multi-phase SPH method for macroscopic and
+.. [A10] Adami et al. "A new surface-tension formulation for multi-phase SPH
+   using a reproducing divergence approximation", JCP 2010, 229, pp 5011--5021
+
+.. [XA06] X.Y.Hu, N.A. Adams. "A multi-phase SPH method for macroscopic and
    mesoscopic flows", JCP 2006, 213, pp 844-861 [XA06]
 
 """
@@ -848,12 +850,12 @@ def post_loop(self, d_idx, d_cx, d_cy, d_cz, d_h,
 def get_surface_tension_equations(fluids, solids, scheme, rho0, p0, c0, b,
                                   factor1, factor2, nu, sigma, d, epsilon,
                                   gamma, real=False):
-    """
-    This function returns the required equations for the multiphase
-    formulation taking inputs of the fluid particles array, solid particles
-    array, the scheme to be used and other physical parameters
+    """This function returns the required equations for the multiphase formulation
+    taking inputs of the fluid particles array, solid particles array, the
+    scheme to be used and other physical parameters
+
     Parameters
-    ------------------
+    -----------
 
     fluids: list
         List of names of fluid particle arrays
@@ -862,17 +864,19 @@ def get_surface_tension_equations(fluids, solids, scheme, rho0, p0, c0, b,
     scheme: string
         The scheme with which the equations are to be setup.
         Supported Schemes:
-            1. TVF scheme with Morris' surface tension.
-            String to be used: "tvf"
-            2. Adami's surface tension implementation which doesn't involve
-            calculation of curvature. String to be used: "adami_stress"
-            3. Adami's surface tension implementation which involves
-            calculation of curvature. String to be used: "adami"
-            4. Shadloo Yildiz surface tension formulation.
-            String to be used: "shadloo"
-            5. Morris' surface tension formulation. This is the default scheme
-            which will be used if none of the above strings are input as
-            scheme.
+
+        1. TVF scheme with Morris' surface tension.
+           String to be used: "tvf"
+        2. Adami's surface tension implementation which doesn't involve
+           calculation of curvature. String to be used: "adami_stress"
+        3. Adami's surface tension implementation which involves
+           calculation of curvature. String to be used: "adami"
+        4. Shadloo Yildiz surface tension formulation.
+           String to be used: "shadloo"
+        5. Morris' surface tension formulation. This is the default scheme
+           which will be used if none of the above strings are input as
+           scheme.
+
     rho0 : float
         The reference density of the medium (Currently multiple reference
         densities for different particles is not supported)
@@ -901,6 +905,7 @@ def get_surface_tension_equations(fluids, solids, scheme, rho0, p0, c0, b,
     epsilon: float
         Put this option false if the equations are supposed to be evaluated
         for the ghost particles, else keep it True
+
     """
     if scheme == 'tvf':
         result = []

diff --git a/pysph/sph/wc/gtvf.py b/pysph/sph/wc/gtvf.py
@@ -394,6 +394,7 @@ class DeviatoricStressRate(Equation):
             - \frac{1}{3} \text{Tr}(\boldsymbol{\epsilon})\textbf{I}) +
             \boldsymbol{\sigma}' \cdot \boldsymbol{\Omega}^{T} +
             \boldsymbol{\Omega} \cdot \boldsymbol{\sigma}'
+
     where,
 
     .. math::

diff --git a/pysph/sph/wc/viscosity.py b/pysph/sph/wc/viscosity.py
@@ -114,13 +114,16 @@ def loop(self, d_idx, s_idx, d_m, s_m, d_rho, s_rho, d_h, s_h, d_cs, s_cs,
 
 
 class LaminarViscosityDeltaSPH(Equation):
-    r"""
-    See section 2 of the below reference
+    r"""See section 2 of the below reference [Sun2017]
+
+    References
+    ----------
+
+    .. [Sun2017] P. Sun, A. Colagrossi, S. Marrone, A. Zhang "The $\delta$
+       plus-SPH model: simple procedures for a further improvement of the SPH
+       scheme", Computer Methods in Applied Mechanics and Engineering 315
+       (2017), pp. 25-49.
 
-    - P. Sun, A. Colagrossi, S. Marrone, A. Zhang
-    "The plus-SPH model: simple procedures for a further improvement of the SPH
-    scheme", Computer Methods in Applied Mechanics and Engineering 315 (2017),
-    pp. 25-49.
     """
     def __init__(self, dest, sources, dim, rho0, nu):
         self.dim = dim

diff --git a/pysph/tools/interpolator.py b/pysph/tools/interpolator.py
@@ -81,21 +81,21 @@ def loop(self, d_idx, s_idx, d_h, s_h, s_x, s_y, s_z, d_x, d_y, d_z, s_rho,
 
 
 class SPHFirstOrderApproximation(Equation):
-    """ First order SPH approximation
-        -------------
-        The method used to solve the linear system in this function is not same
-        as in the reference. In the function `Ax=b` is solved where `A :=
-        moment` (Moment matrix) and `b := p_sph` (Property calculated using
-        basic SPH).
-        The calculation need the `moment` to be evaluated before this step
-        which is done in `SPHFirstOrderApproximationPreStep`
-
-        References
-        ----------
+    """First order SPH approximation.
+
+    The method used to solve the linear system in this function is not same as
+    in the reference. In the function :math:`Ax=b` is solved where :math:`A :=
+    moment` (Moment matrix) and :math:`b := p_sph` (Property calculated using
+    basic SPH). The calculation need the "moment" to be evaluated before this
+    step which is done in `SPHFirstOrderApproximationPreStep`
+
+    References
+    -----------
+
+    .. [Liu2006] M.B. Liu, G.R. Liu, "Restoring particle consistency in
+       smoothed particle hydrodynamics", Applied Numerical Mathematics
+       Volume 56, Issue 1 2006, Pages 19-36, ISSN 0168-9274
 
-        .. [Liu2006] M.B. Liu, G.R. Liu, "Restoring particle consistency in
-           smoothed particle hydrodynamics", Applied Numerical Mathematics
-           Volume 56, Issue 1 2006, Pages 19-36, ISSN 0168-9274
     """
     def _get_helpers_(self):
         return [gj_solve, augmented_matrix]

diff --git a/pysph/tools/read_mesh.py b/pysph/tools/read_mesh.py
@@ -59,8 +59,10 @@ def mesh2points(file_name, dx, file_format=None, uniform=False):
     Supported file formats: Refer to https://github.com/nschloe/meshio
 
     Only works with triangle meshes.
+
     Parameters
     ----------
+
     file_name : string
         Mesh file name
     dx : float
@@ -69,6 +71,7 @@ def mesh2points(file_name, dx, file_format=None, uniform=False):
         Mesh file format
     uniform : bool
         If True generates points on a grid of spacing dx
+
     Returns
     -------
     xf, yf, zf : ndarray