Merge pull request mosdef-hub#291 from mattwthompson/docs-1

Improve docstrings for Potential and subclasses

gmso/core/angle_type.py

@@ -8,25 +8,39 @@
 
 
 class AngleType(Potential):
-    """A Potential between 3-bonded partners.
+    """A descripton of the interaction between 3 bonded partners.
+
+    This is a subclass of the gmso.core.Potential superclass.
+
+    AngleType represents an angle type and includes the functional form
+    describing its interactions. The functional form of the potential is stored
+    as a `sympy` expression and the parameters, with units, are stored
+    explicitly.  The AtomTypes that are used to define the angle type are
+    stored as `member_types`.
 
     Parameters
     ----------
-    name : str
+    name : str, optional
+        A name uniquely representing the angle type
     expression : str or sympy.Expression
         See `Potential` documentation for more information
     parameters : dict {str, unyt.unyt_quantity}
         See `Potential` documentation for more information
     independent vars : set of str
         See `Potential` documentation for more information
-    member_types : list of gmso.AtomType.name (str)
-    gmso: gmso.core.Topology, the gmso of which this angle_type is a part of, default=None
-    set_ref: (str), the string name of the bookkeeping set in gmso class.
+    member_types : list-like of str
+        List-like of of gmso.AtomType.name defining the members of this
+        angle type
+    gmso: gmso.core.Topology, default=None
+        The Topology of which this angle_type is a part of
+    set_ref: str
+        The string name of the bookkeeping set in gmso class.
 
     Notes
     ----
     Inherits many functions from gmso.Potential:
         __eq__, _validate functions
+
     """
 
     def __init__(self,
@@ -73,7 +87,7 @@ def __repr__(self):
 
 
 def _validate_three_member_type_names(types):
-    """Ensure 3 partners are involved in AngleType"""
+    """Ensure exactly 3 partners are involved in AngleType"""
     if len(types) != 3 and len(types) != 0:
         raise GMSOError("Trying to create an AngleType "
                             "with {} constituent types".format(len(types)))

gmso/core/atom_type.py

@@ -1,4 +1,5 @@
 import warnings
+
 import unyt as u
 
 from gmso.core.potential import Potential
@@ -8,7 +9,9 @@
 
 
 class AtomType(Potential):
-    """An atom type, inheriting from the Potential class.
+    """A description of non-bonded interacitons between sites.
+
+    This is a subclass of the gmso.core.Potential superclass.
 
     AtomType represents an atom type and includes the functional form
     describing its interactions and, optionally, other properties such as mass
@@ -39,15 +42,18 @@ class AtomType(Potential):
     atomclass : str, default=''
         The class of the atomtype
     doi : str
-        Digital Object Identifier of publication where this atom type was specified
+        Digital Object Identifier of publication where this atom type was
+        specified
     desc : str
         Simple description of the atom type
     overrides : set of str
         Set of other atom types that this atom type overrides
     definition : str
         SMARTS string defining this atom type
-    topology: gmso.core.Topology, the topology of which this atom_type is a part of, default=None
-    set_ref: (str), the string name of the bookkeeping set in topology class.
+    topology: gmso.core.Topology, default=None
+        The topology of which this atom_type is a part of, default=None
+    set_ref: str
+        The string name of the bookkeeping set in gmso class.
 
     """
 
@@ -177,6 +183,7 @@ def __repr__(self):
 
 
 def _validate_charge(charge):
+    """Check to see that a charge is a unyt array of the right dimension"""
     if not isinstance(charge, u.unyt_array):
         warnings.warn("Charges are assumed to be elementary charge")
         charge *= u.elementary_charge
@@ -190,6 +197,7 @@ def _validate_charge(charge):
 
 
 def _validate_mass(mass):
+    """Check to see that a mass is a unyt array of the right dimension"""
     if not isinstance(mass, u.unyt_array):
         warnings.warn("Masses are assumed to be g/mol")
         mass *= u.gram / u.mol
@@ -203,12 +211,14 @@ def _validate_mass(mass):
 
 
 def _validate_str(val):
+    """Check to see that a string is a str type"""
     if not isinstance(val, str):
         raise ValueError("Passed value {} is not a string".format(val))
     return val
 
 
 def _validate_set(val):
+    """Check to see that a set is a set type"""
     if not isinstance(val, set):
         raise ValueError("Passed value {} is not a set".format(val))
     if not all([isinstance(char, str) for char in val]):

gmso/core/bond_type.py

@@ -8,24 +8,36 @@
 
 
 class BondType(Potential):
-    """A Potential between 2-bonded partners.
+    """A descripton of the interaction between 2 bonded partners.
+
+    This is a subclass of the gmso.core.Potential superclass.
+
+    BondType represents a bond type and includes the functional form describing
+    its interactions. The functional form of the potential is stored as a
+    `sympy` expression and the parameters, with units, are stored explicitly.
+    The AtomTypes that are used to define the bond type are stored as
+    `member_types`.
 
     Parameters
     ----------
     name : str
+        The name of the potential.
     expression : str or sympy.Expression
         See `Potential` documentation for more information
     parameters : dict {str, unyt.unyt_quantity}
         See `Potential` documentation for more information
     independent vars : set of str
         see `Potential` documentation for more information
-    member_types : list of gmso.AtomType.name (str)
+    member_types : list-like of str
+        List-like of of gmso.AtomType.name defining the members of this
+        bond type
 
     Notes
     ----
     Inherits many functions from gmso.Potential:
         __eq__, _validate functions
-        """
+
+    """
 
     def __init__(self,
                  name='BondType',
@@ -73,7 +85,7 @@ def __repr__(self):
 
 
 def _validate_two_member_type_names(types):
-    """Ensure 2 partners are involved in BondType"""
+    """Ensure exactly 2 partners are involved in BondType"""
     if len(types) != 2 and len(types) != 0:
         raise GMSOError("Trying to create a BondType "
                             "with {} constituent types".format(len(types)))

gmso/core/dihedral_type.py

@@ -6,7 +6,15 @@
 from gmso.utils._constants import DIHEDRAL_TYPE_DICT
 
 class DihedralType(Potential):
-    """A Potential between 4-bonded partners.
+    """A descripton of the interaction between 4 bonded partners.
+
+    This is a subclass of the gmso.core.Potential superclass.
+
+    DihedralType represents a dihedral type and includes the functional form
+    describing its interactions. The functional form of the potential is stored
+    as a `sympy` expression and the parameters, with units, are stored
+    explicitly.  The AtomTypes that are used to define the dihedral type are
+    stored as `member_types`.
 
     Parameters
     ----------
@@ -17,14 +25,19 @@ class DihedralType(Potential):
         See `Potential` documentation for more information
     independent vars : set of str
         See `Potential` documentation for more information
-    member_types : list of gmso.AtomType.name (str)
-    topology: gmso.core.Topology, the topology of which this dihedral type is a part of, default=None
-    set_ref: (str), the string name of the bookkeeping set in topology class.
+    member_types : list-like of str
+        List-like of of gmso.AtomType.name defining the members of this
+        dihedral type
+    topology: gmso.core.Topology, default=None
+        The topology of which this dihedral type is a part of
+    set_ref: str
+        The string name of the bookkeeping set in topology class.
 
     Notes
     ----
     Inherits many functions from gmso.Potential:
         __eq__, _validate functions
+
     """
 
     def __init__(self,
@@ -73,7 +86,7 @@ def __repr__(self):
 
 
 def _validate_four_member_type_names(types):
-    """Ensure 4 partners are involved in DihedralType"""
+    """Ensure exactly 4 partners are involved in DihedralType"""
     if len(types) != 4 and len(types) != 0:
         raise GMSOError("Trying to create an DihedralType "
                             "with {} constituent types".format(len(types)))

gmso/core/potential.py

@@ -1,4 +1,5 @@
 import warnings
+
 import sympy
 import unyt as u
 
@@ -210,6 +211,7 @@ def __repr__(self):
 
 
 def _validate_parameters(parameters):
+    """Check to see that parameters is a valid dictionary with units"""
     if not isinstance(parameters, dict):
         raise ValueError("Please enter dictionary for parameters")
     for key, val in parameters.items():
@@ -227,6 +229,7 @@ def _validate_parameters(parameters):
 
 
 def _validate_independent_variables(indep_vars):
+    """Check to see that independent_variables is a set of valid sympy symbols"""
     if isinstance(indep_vars, str):
         indep_vars = {sympy.symbols(indep_vars)}
     elif isinstance(indep_vars, sympy.symbol.Symbol):
@@ -249,6 +252,7 @@ def _validate_independent_variables(indep_vars):
 
 
 def _validate_expression(expression):
+    """Check to see that an expression is a valid sympy expression"""
     if expression is None or isinstance(expression, sympy.Expr):
         pass
     elif isinstance(expression, str):