Merged in arkopaldutt/pysph/doc-update (pull request #176)

Updates to docstrings in basic_equations.py

docs/source/conf.py

@@ -31,6 +31,8 @@
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax',
 'sphinx.ext.viewcode', 'sphinx.ext.napoleon']
 
+autodoc_default_flags = ['show-inheritance']
+autoclass_content = "both"
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True
 napoleon_include_private_with_doc = False

pysph/sph/basic_equations.py

@@ -1,4 +1,4 @@
-"""Basic SPH equations"""
+"""**Basic SPH Equations**"""
 
 from pysph.sph.equation import Equation
 
@@ -22,6 +22,18 @@ class BodyForce(Equation):
     """
     def __init__(self, dest, sources,
                  fx=0.0, fy=0.0, fz=0.0):
+
+        r"""
+        Parameters
+        ----------
+        fx : float
+            Body force per unit mass along the x-axis
+        fy : float
+            Body force per unit mass along the y-axis
+        fz : float
+            Body force per unit mass along the z-axis
+        """
+
         self.fx = fx
         self.fy = fy
         self.fz = fz
@@ -44,7 +56,9 @@ class VelocityGradient2D(Equation):
 
     :math:`\frac{\partial v^i}{\partial x^j} = \sum_{b}\frac{m_b}{\rho_b}(v_b
     - v_a)\frac{\partial W_{ab}}{\partial x_a^j}`
-
+    
+    Notes
+    -----
     The tensor properties are stored in the variables v_ij where 'i'
     refers to the velocity component and 'j' refers to the spatial
     component. Thus v_21 is :math:`\frac{\partial v}{\partial x}`
@@ -71,11 +85,23 @@ def loop(self, d_idx, s_idx, s_m, s_rho,
 class IsothermalEOS(Equation):
     r""" Compute the pressure using the Isothermal equation of state:
 
-    :math:`p = p_0 + c_0^2(\rho_0 - rho)`
+    :math:`p = p_0 + c_0^2(\rho_0 - \rho)`
 
     """
     def __init__(self, dest, sources=None,
                  rho0=1000.0, c0=1.0, p0=0.0):
+
+        r"""
+        Parameters
+        ----------
+        rho0 : float
+            Reference density of the fluid (:math:`\rho_0`)
+        c0 : float
+            Maximum speed of sound expected in the system (:math:`c0`)
+        p0 : float
+            Reference pressure in the system (:math:`p0`)
+        """
+
         self.rho0 = rho0
         self.c0 = c0
         self.c02 = c0 * c0
@@ -100,8 +126,46 @@ def loop(self, d_idx, d_arho, s_idx, s_m, DWIJ, VIJ):
         d_arho[d_idx] += s_m[s_idx]*vijdotdwij
 
 class MonaghanArtificialViscosity(Equation):
-    """Classical Monaghan style artificial viscosity"""
+    r"""Classical Monaghan style artificial viscosity [1]_
+    
+    .. math::
+    
+        \frac{d\mathbf{v}_{a}}{dt}&=&-\sum_{b}m_{b}\Pi_{ab}\nabla_{a}W_{ab}
+
+    where
+    
+    .. math::    
+        
+        \Pi_{ab}=\begin{cases}\frac{-\alpha_{\pi}\bar{c}_{ab}\phi_{ab}+
+        \beta_{\pi}\phi_{ab}^{2}}{\bar{\rho}_{ab}}, & \mathbf{v}_{ab}\cdot
+        \mathbf{r}_{ab}<0\\0, & \mathbf{v}_{ab}\cdot\mathbf{r}_{ab}\geq0
+        \end{cases}
+
+    with
+
+    .. math::
+
+        \phi_{ab}=\frac{h\mathbf{v}_{ab}\cdot\mathbf{r}_{ab}}
+        {|\mathbf{r}_{ab}|^{2}+\epsilon^{2}}\\
+        
+        \bar{c}_{ab}&=&\frac{c_{a}+c_{b}}{2}\\
+        
+        \bar{\rho}_{ab}&=&\frac{\rho_{a}+\rho_{b}}{2}
+    
+    References
+    ----------
+    .. [1] J. Monaghan, "Smoothed particle hydrodynamics", Reports on Progress 
+        in Physics, 68 (2005), pp. 1703-1759.    
+    """
     def __init__(self, dest, sources=None, alpha=1.0, beta=1.0):
+        r"""
+        Parameters
+        ----------
+        alpha : float
+            produces a shear and bulk viscosity
+        beta : float
+            used to handle high Mach number shocks
+        """
         self.alpha = alpha
         self.beta = beta
         super(MonaghanArtificialViscosity, self).__init__(dest, sources)
@@ -133,13 +197,31 @@ def loop(self, d_idx, s_idx, d_rho, d_cs, d_au, d_av, d_aw, s_m,
         d_aw[d_idx] += -s_m[s_idx] * piij * DWIJ[2]
 
 class XSPHCorrection(Equation):
-    """Position stepping with XSPH correction
+    r"""Position stepping with XSPH correction [2]_
     
-    This equation must be used to advect the particles. XSPH can be
-    turned off by setting the parameter ``eps = 0``.
-
+    .. math::
+    
+        \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
+    ----------
+    .. [2] J. MONAGHAN, Smoothed Particle Hydrodynamics, "Annual Review of 
+        Astronomy and Astrophysics", 30 (1992), pp. 543-574.
     """
     def __init__(self, dest, sources=None, eps=0.5):
+        r"""
+        Parameters
+        ----------
+        eps : float
+            :math:`\epsilon` as in the above equation
+        
+        Notes
+        -----
+        This equation must be used to advect the particles. XSPH can be
+        turned off by setting the parameter ``eps = 0``.
+        """
+
         self.eps = eps
         super(XSPHCorrection, self).__init__(dest, sources)
 

pysph/sph/equation.py

@@ -325,6 +325,14 @@ class Equation(object):
     # `object` interface.
     ##########################################################################
     def __init__(self, dest, sources=None, name=None):
+        r"""
+        Parameters
+        ----------
+        dest : str
+            name of the destination particle array
+        sources : list of str
+            names of the source particle arrays
+        """
         self.dest = dest
         self.sources = sources if sources is not None and len(sources) > 0 \
                                                                 else None