add lib.pkdtree (and related) docs

package/CHANGELOG

@@ -13,12 +13,13 @@ The rules for this file:
   * release numbers follow "Semantic Versioning" http://semver.org
 
 ------------------------------------------------------------------------------
-mm/dd/18
+mm/dd/18 orbeckst
   * 0.19.1
 
 Enhancements
 
 Fixes
+   * added missing docs for lib.pkdtree (#2104)
 
 Changes
 

package/MDAnalysis/coordinates/base.py

@@ -1959,7 +1959,7 @@ def transformations(self, transformations):
             raise ValueError("Transformations are already set")
 
     def add_transformations(self, *transformations):
-        """ Add all transformations to be applied to the trajectory.
+        """Add all transformations to be applied to the trajectory.
 
         This function take as list of transformations as an argument. These
         transformations are functions that will be called by the Reader and given
@@ -1976,14 +1976,27 @@ def add_transformations(self, *transformations):
           workflow = [some_transform, another_transform, this_transform]
           u.trajectory.add_transformations(*workflow)
 
+        The transformations are applied in the order given in the list
+        `transformations`, i.e., the first transformation is the first
+        or innermost one to be applied to the :class:`Timestep`. The
+        example above would be equivalent to
+
+        .. code-block:: python
+
+          for ts in u.trajectory:
+             ts = this_transform(another_transform(some_transform(ts)))
+
+
         Parameters
         ----------
         transform_list : list
             list of all the transformations that will be applied to the coordinates
+            in the order given in the list
 
         See Also
         --------
         :mod:`MDAnalysis.transformations`
+
         """
 
         try:

package/MDAnalysis/lib/pkdtree.py

@@ -21,7 +21,7 @@
 #
 """
 PeriodicKDTree --- :mod:`MDAnalysis.lib.pkdtree`
-===============================================================================
+================================================
 
 This module contains a class to allow searches on a KDTree involving periodic
 boundary conditions.
@@ -45,7 +45,7 @@
 
 
 class PeriodicKDTree(object):
-    """Wrapper around scipy.spatial.cKDtree
+    """Wrapper around :class:`scipy.spatial.cKDTree`
 
     Creates an object which can handle periodic as well as
     non periodic boundary condtions depending on the parameters
@@ -55,10 +55,12 @@ class PeriodicKDTree(object):
     provided. Periodic Boundary conditions are implemented by creating
     duplicates of the particles which are within the specified cutoff
     distance from the boundary. These duplicates along with the
-    original particle coordinates are used with the cKDTree
-    without any special treatment due to PBC beyond this point.
-    The final results after any operation with duplicate particle indices
-    can be traced back to the original particle using undo augment function.
+    original particle coordinates are used with the cKDTree without
+    any special treatment due to PBC beyond this point.  The final
+    results after any operation with duplicate particle indices can be
+    traced back to the original particle using the
+    :func:`MDAnalysis.lib.distances.undo_augment` function.
+
     """
     def __init__(self, box=None, leafsize=10):
         """
@@ -85,6 +87,13 @@ def __init__(self, box=None, leafsize=10):
 
     @property
     def pbc(self):
+        """Flag to indicate the presence of periodic boundaries.
+
+        - ``True`` if PBC are taken into account
+        - ``False`` if no unitcell dimension is available.
+
+        This is a managed attribute and can only be read.
+        """
         return self.box is not None
 
     def set_coords(self, coords, cutoff=None):
@@ -115,7 +124,7 @@ def set_coords(self, coords, cutoff=None):
 
         See Also
         --------
-        MDAnalysis.lib._augment.augment_coordinates
+        MDAnalysis.lib.distances.augment_coordinates
 
         """
         # If no cutoff distance is provided but PBC aware
@@ -154,8 +163,8 @@ def search(self, centers, radius):
         to enable distance evaluations from points in the tree
         and their images.
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         centers: array_like (N,3)
           coordinate array to search for neighbors
         radius: float
@@ -195,7 +204,8 @@ def search(self, centers, radius):
         return self._indices
 
     def get_indices(self):
-        """
+        """Return the neighbors from the last query.
+
         Returns
         ------
         indices : list
@@ -238,14 +248,14 @@ def search_pairs(self, radius):
 
     def search_tree(self, centers, radius):
         """
-        Searches all the pairs within radius between ``centers``
+        Searches all the pairs within `radius` between `centers`
         and ``coords``
 
         ``coords`` are the already initialized coordinates in the tree
-        during ``set_coords(coords, cutoff)``.
-         ``centers`` are wrapped around the primary unit cell
+        during :meth:`set_coords`.
+        ``centers`` are wrapped around the primary unit cell
         if PBC is desired. Minimum image convention (PBC) is
-        activated if ``box`` argument is provided during
+        activated if the `box` argument is provided during
         class initialization
 
         Parameters
@@ -263,8 +273,8 @@ class initialization
         Note
         ----
         This method constructs another tree from the ``centers``
-        and queries the previously built tree (Built in
-        ``PeriodicKDTree.set_coords(...)``)
+        and queries the previously built tree (built in
+        :meth:`set_coords`)
         """
 
         if not self._built:

package/MDAnalysis/transformations/translate.py

@@ -28,7 +28,12 @@
 The vector can either be user defined, using the function :func:`translate`
 or defined by centering an AtomGroup in the unit cell using the function
 :func:`center_in_box`
-
+
+.. autofunction:: translate
+
+.. autofunction:: center_in_box
+
+
 """
 from __future__ import absolute_import, division
 
@@ -41,31 +46,31 @@ def translate(vector):
     """
     Translates the coordinates of a given :class:`~MDAnalysis.coordinates.base.Timestep`
     instance by a given vector.
-    
+
     Example
     -------
-        ts = MDAnalysis.transformations.translate([1,2,3])(ts)    
-    
+        ts = MDAnalysis.transformations.translate([1,2,3])(ts)
+
     Parameters
     ----------
     vector: array-like
         coordinates of the vector to which the coordinates will be translated
-        
+
     Returns
     -------
     :class:`~MDAnalysis.coordinates.base.Timestep` object
-    
+
     """
     if len(vector)>2:
         vector = np.float32(vector)
     else:
         raise ValueError("{} vector is too short".format(vector))
-    
+
     def wrapped(ts):
         ts.positions += vector
-        
+
         return ts
-    
+
     return wrapped
 
 
@@ -74,16 +79,16 @@ def center_in_box(ag, center='geometry', point=None, wrap=False):
     Translates the coordinates of a given :class:`~MDAnalysis.coordinates.base.Timestep`
     instance so that the center of geometry/mass of the given :class:`~MDAnalysis.core.groups.AtomGroup`
     is centered on the unit cell. The unit cell dimensions are taken from the input Timestep object.
-    If a point is given, the center of the atomgroup will be translated to this point instead. 
-    
+    If a point is given, the center of the atomgroup will be translated to this point instead.
+
     Example
     -------
-    
+
     .. code-block:: python
-    
+
         ag = u.residues[1].atoms
         ts = MDAnalysis.transformations.center(ag,center='mass')(ts)
-    
+
     Parameters
     ----------
     ag: AtomGroup
@@ -98,14 +103,14 @@ def center_in_box(ag, center='geometry', point=None, wrap=False):
     wrap: bool, optional
         If `True`, all the atoms from the given AtomGroup will be moved to the unit cell
         before calculating the center of mass or geometry. Default is `False`, no changes
-        to the atom coordinates are done before calculating the center of the AtomGroup. 
-    
+        to the atom coordinates are done before calculating the center of the AtomGroup.
+
     Returns
     -------
     :class:`~MDAnalysis.coordinates.base.Timestep` object
-    
+
     """
-    
+
     pbc_arg = wrap
     if point:
         point = np.asarray(point, np.float32)
@@ -123,19 +128,19 @@ def center_in_box(ag, center='geometry', point=None, wrap=False):
             raise AttributeError('{} is not an AtomGroup object with masses'.format(ag))
         else:
             raise ValueError('{} is not an AtomGroup object'.format(ag))
-  
+
     def wrapped(ts):
         if point is None:
             boxcenter = np.sum(ts.triclinic_dimensions, axis=0) / 2
         else:
             boxcenter = point
-    
+
         ag_center = center_method()
 
         vector = boxcenter - ag_center
         ts.positions += vector
-        
+
         return ts
-    
+
     return wrapped
-    
+

package/doc/sphinx/source/documentation_pages/lib/pkdtree.rst

@@ -0,0 +1,2 @@
+.. automodule:: MDAnalysis.lib.pkdtree
+   :members:

package/doc/sphinx/source/documentation_pages/lib_modules.rst

@@ -33,10 +33,16 @@ superposition by minimizing the RMSD.
 functions whereas mathematical functions are to be found in
 :mod:`MDAnalysis.lib.mdamath`.
 
-:mod:`MDAnalysis.lib.NeighborSearch` contains classes to do neighbor
-searches with MDAnalysis objects.
+A number of modules are concerned with finding
+neighbors. :mod:`MDAnalysis.lib.NeighborSearch` contains high-level
+classes to do neighbor searches with MDAnalysis
+objects. :mod:`MDAnalysis.lib.nsgrid` contains a fast implementation
+of grid neighbor search whereas :mod:`MDAnalysis.lib.pkdtree` uses
+KDTrees (with periodic images) for neighbor searching. Some of the
+functions in :mod:`MDAnalysis.lib.distances` user either of these
+algorithms to speed up distance calculations.
+
 
-:mod:`MDAnalysis.lib.nsgrid` contains a fast implementation of grid neighbor search.
 
 List of modules
 ---------------
@@ -46,12 +52,13 @@ List of modules
 
    ./lib/distances
    ./lib/NeighborSearch
+   ./lib/nsgrid
+   ./lib/pkdtree	      
    ./lib/log
    ./lib/mdamath
    ./lib/transformations
    ./lib/qcprot
    ./lib/util
-   ./lib/nsgrid
 
 Low level file formats
 ----------------------