Quick update of several doc strings

chrisjonesBSU · chrisjonesBSU · commit 8ccf1012bc5e · 2025-10-31T13:48:42.000Z
diff --git a/mbuild/path/bias.py b/mbuild/path/bias.py
@@ -58,7 +58,7 @@ def __init__(self, site_type, weight, system_coordinates, new_coordinates):
         super(TargetType, self).__init__(system_coordinates, new_coordinates)
 
     def __call__(self):
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
 
 
 class AvoidType(Bias):
@@ -69,7 +69,7 @@ def __init__(self, site_type, weight, system_coordinates, new_coordinates):
         super(AvoidType, self).__init__(system_coordinates, new_coordinates)
 
     def __call__(self):
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
 
 
 class TargetEdge(Bias):
@@ -80,7 +80,7 @@ def __init__(self, weight, system_coordinates, volume_constraint, new_coordinate
         super(TargetEdge, self).__init__(system_coordinates, new_coordinates)
 
     def __call__(self):
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
 
 
 class AvoidEdge(Bias):
@@ -91,7 +91,7 @@ def __init__(self, weight, system_coordinates, volume_constraint, new_coordinate
         super(AvoidEdge, self).__init__(system_coordinates, new_coordinates)
 
     def __call__(self):
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
 
 
 class TargetDirection(Bias):
@@ -102,7 +102,7 @@ def __init__(self, direction, weight, system_coordinates, new_coordinates):
         super(TargetDirection, self).__init__(system_coordinates, new_coordinates)
 
     def __call__(self):
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
 
 
 class AvoidDirection(Bias):
@@ -113,7 +113,7 @@ def __init__(self, direction, weight, system_coordinates, new_coordinates):
         super(AvoidDirection, self).__init__(system_coordinates, new_coordinates)
 
     def __call__(self):
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
 
 
 class TargetPath(Bias):
@@ -124,4 +124,4 @@ def __init__(self, target_path, weight, system_coordinates, new_coordinates):
         super(TargetPath, self).__init__(system_coordinates, new_coordinates)
 
     def __call__(self):
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
diff --git a/mbuild/path/path.py b/mbuild/path/path.py
@@ -13,6 +13,19 @@
 
 
 class Path:
+    """Creates a path from a given set of coordinates and a bond graph.
+    This class is designed to be use in mbuild.polymer.Polymer.build_from_path().
+    This also serves as the base class from which other paths inherit from.
+
+    Parameters
+    ----------
+    N : int, optional
+        The number of sites belonging to the path.
+    coordinates : array-like, optional
+        Creates a path from a pre-defined set of coordinates
+    bond_graph : networkx.Graph, optional
+       The graph defining the edges between coordinates 
+    """
     def __init__(self, N=None, coordinates=None, bond_graph=None):
         self.bond_graph = bond_graph
         # Only N is defined, make empty coordinates array with size N
@@ -67,10 +80,10 @@ def add_edge(self, u, v):
             length=float(bond_length),
             bond_type=(u_name, v_name),
         )
-
+    
     def get_bonded_sites(self):
         """Get all bonded pairs and their bond-vector orientations."""
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
 
     def get_coordinates(self):
         if isinstance(self.coordinates, list):
@@ -99,6 +112,7 @@ def apply_mapping(self):
         """Mapping other compounds onto a Path's coordinates
 
         mapping = {"A": "c1ccccc1C=C", "B": "C=CC=C"}
+        mapping = {"A": mb.Compound, "B": mb.Compound}
 
         for bond in bond graph edges:
             site u: add compound
@@ -108,7 +122,7 @@ def apply_mapping(self):
             set orientation and separation for site v tail port
 
         """
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
 
     def _path_history(self):
         """Maybe this is a method that can be used optionally.
@@ -117,7 +131,7 @@ def _path_history(self):
         computation time and resources.
         Might be useful for more complicated random walks/branching algorithms
         """
-        pass
+        raise NotImplementedError("This feature of mBuild 2.0 has not been implemented yet.")
 
 
 class HardSphereRandomWalk(Path):
@@ -159,6 +173,23 @@ def __init__(
         max_angle : float, required
             Maximum angle (radians) used when randomly selecting angle
             for the next step.
+        bead_name : str, default = "_A"
+            The name assigned to each site in this random walk.
+        volume_constraint : mbuild.utils.volumes.Constraint, optional
+            Used to reject moves which are outside of the volume constraint
+        start_from_path : mbuild.path.Path, optional
+            An instance of a previous Path to start the random walk from.
+            This path's sites are used in checking for overlapping sites.
+        start_from_path_index : int, optional
+            An index of `start_from_path` used as the starting point for this random walk.
+        attach_paths : bool, default = False 
+            If True, adds an edge between the starting point of the last path and the first
+            point of this path.
+        initial_point : array-like, optional
+            Used as the coordinate for the first site in this random walk path.
+        include_compound : mb.Compound, optional
+            An mBuild compound that is considered in this random walk.
+            This random walk with reject new points that overlap with the Compound's coordinates.
         seed : int, default = 42
             Random seed
         trial_batch_size : int, default = 5
@@ -167,15 +198,7 @@ def __init__(
             random walks.
         max_attempts : int, default = 1e5
             The maximum number of trial moves to attempt before quiting.
-        start_from_path : mbuild.path.Path, optional
-            An instance of a previous Path to start the random walk from.
-        start_from_path_index : int, optional
-            The index of `start_from_path` to use as the initial point
             for the random walk.
-        attach_paths : bool, default = False
-            If True, an edge will be created in the bond graph between
-            the last point of `start_from_path` and the first point of
-            this random walk.
         tolerance : float, default = 1e-4
             Tolerance used for rounding and checking for overlaps.
 
@@ -776,12 +799,28 @@ def generate(self):
 
 
 class ZigZag(Path):
+    """Generates a path following a zig-zag pattern in a given plane.
+
+    Parameters
+    ----------
+    spacing : float, default = 1.0
+        The distance between consecutive sites along the path.
+    angle_deg : float, default = 120.
+        The rotation applied between segments
+    sites_per_segment : int, default = 4 
+        The number of sites before rotating and beginning next segment.
+    plane : str, default = "xy"
+        The plane that the sites in the path occupy
+    bond_graph : networkx.Graph
+        Defines connectivity between sites
+
+    """
     def __init__(
         self,
         N,
         spacing=1.0,
         angle_deg=120.0,
-        sites_per_segment=1,
+        sites_per_segment=4,
         plane="xy",
         bond_graph=None,
     ):
diff --git a/mbuild/utils/volumes.py b/mbuild/utils/volumes.py
@@ -3,6 +3,21 @@
 
 
 class Constraint:
+    """
+    Defines a volume that acts as a constraint in mbuild.path.HardSphereRandomWalk.
+    This is the base class from which all constraints inherit from.
+
+    Notes
+    -----
+    Design and implement your own volume constraint by inheriting from this class
+    and implementing the constraint check in an `is_inside` method. 
+
+    `is_inside` is expected to return a mask of booleans.
+
+    The existing contraints of CuboidConstraint, SphereConstraint, and CylinderConstraint
+    call numba methods from their respectice `is_inside` method, but that is not a required
+    implementation to design your own constraint.
+    """
     def __init__(self):
         pass
 
@@ -12,32 +27,89 @@ def is_inside(self, points, buffer):
 
 
 class CuboidConstraint(Constraint):
+    """Creates a cuboid constraint.
+
+    Parameters
+    ----------
+    Lx : float, required
+        The length of the volume along the x-axis.
+    Ly : float, required
+        The length of the volume along the y-axis.
+    Lz : float, required
+        The length of the volume along the z-axis.
+    center : array-like (1,3), default = (0, 0, 0)
+        Defines the center of the volume.
+    """
     def __init__(self, Lx, Ly, Lz, center=(0, 0, 0)):
         self.center = np.asarray(center)
         self.mins = self.center - np.array([Lx / 2, Ly / 2, Lz / 2])
         self.maxs = self.center + np.array([Lx / 2, Ly / 2, Lz / 2])
 
     def is_inside(self, points, buffer):
-        """Points and buffer are passed in from HardSphereRandomWalk"""
+        """Check a set of coordinates against the volume constraint.
+
+        Parameters
+        ----------
+        points : ndarray (N, 3), required
+            The set of points to check against the volume constraint.
+        buffer : float, required
+            Buffer used for rounding
+
+        Returns
+        -------
+        Mask of booleans of length N corresponding to each point.
+        """
         return is_inside_cuboid(
             mins=self.mins, maxs=self.maxs, points=points, buffer=buffer
         )
 
 
 class SphereConstraint(Constraint):
+    """Creates a spherical constraint.
+
+    Parameters
+    ----------
+    radius : float, required
+        The radius of the sphere
+    center : array-like (1,3), default = (0, 0, 0)
+        Defines the center point of the sphere.
+    """
     def __init__(self, center, radius):
         self.center = np.array(center)
         self.radius = radius
         self.mins = self.center - self.radius
         self.maxs = self.center + self.radius
 
     def is_inside(self, points, buffer):
-        """Points and buffer are passed in from HardSphereRandomWalk"""
+        """Check a set of coordinates against the volume constraint.
+
+        Parameters
+        ----------
+        points : ndarray (N, 3), required
+            The set of points to check against the volume constraint.
+        buffer : float, required
+            Buffer used for rounding
+
+        Returns
+        -------
+        Mask of booleans of length N corresponding to each point.
+        """
         return is_inside_sphere(points=points, sphere_radius=self.radius, buffer=buffer)
 
 
 class CylinderConstraint(Constraint):
-    def __init__(self, center, radius, height):
+    """Creates a cylindrical constraint.
+
+    Parameters
+    ----------
+    radius : float, required
+        The radius of the cylinder
+    height : float, required
+        The height  of the cylinder
+    center : array-like (1,3), default = (0, 0, 0)
+        Defines the center point of the sphere.
+    """
+    def __init__(self, radius, height, center=(0, 0, 0)):
         self.center = np.array(center)
         self.height = height
         self.radius = radius
@@ -57,7 +129,19 @@ def __init__(self, center, radius, height):
         )
 
     def is_inside(self, points, buffer):
-        """Points and buffer are passed in from HardSphereRandomWalk"""
+        """Check a set of coordinates against the volume constraint.
+
+        Parameters
+        ----------
+        points : ndarray (N, 3), required
+            The set of points to check against the volume constraint.
+        buffer : float, required
+            Buffer used for rounding
+
+        Returns
+        -------
+        Mask of booleans of length N corresponding to each point.
+        """
         return is_inside_cylinder(
             points=points,
             center=self.center,
