diff --git a/package/CHANGELOG b/package/CHANGELOG index c27020dc097..43178cdedca 100644 --- a/package/CHANGELOG +++ b/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 diff --git a/package/MDAnalysis/coordinates/base.py b/package/MDAnalysis/coordinates/base.py index 8d9fa216bfd..48c40de9e9f 100644 --- a/package/MDAnalysis/coordinates/base.py +++ b/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: diff --git a/package/MDAnalysis/lib/pkdtree.py b/package/MDAnalysis/lib/pkdtree.py index 087bd1d88cd..9b2119ce5a8 100644 --- a/package/MDAnalysis/lib/pkdtree.py +++ b/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: diff --git a/package/MDAnalysis/transformations/translate.py b/package/MDAnalysis/transformations/translate.py index f3728294df3..c94fe6f8128 100644 --- a/package/MDAnalysis/transformations/translate.py +++ b/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 - \ No newline at end of file + diff --git a/package/doc/sphinx/source/documentation_pages/lib/pkdtree.rst b/package/doc/sphinx/source/documentation_pages/lib/pkdtree.rst new file mode 100644 index 00000000000..b9d710fdf34 --- /dev/null +++ b/package/doc/sphinx/source/documentation_pages/lib/pkdtree.rst @@ -0,0 +1,2 @@ +.. automodule:: MDAnalysis.lib.pkdtree + :members: diff --git a/package/doc/sphinx/source/documentation_pages/lib_modules.rst b/package/doc/sphinx/source/documentation_pages/lib_modules.rst index f918f37137e..0394d3fa28e 100644 --- a/package/doc/sphinx/source/documentation_pages/lib_modules.rst +++ b/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 ---------------------- diff --git a/package/doc/sphinx/source/documentation_pages/trajectory_transformations.rst b/package/doc/sphinx/source/documentation_pages/trajectory_transformations.rst index 6ed38cdcf62..1e103e6e681 100644 --- a/package/doc/sphinx/source/documentation_pages/trajectory_transformations.rst +++ b/package/doc/sphinx/source/documentation_pages/trajectory_transformations.rst @@ -7,17 +7,45 @@ Trajectory transformations .. module:: MDAnalysis.transformations -The transformations submodule contains a collection of functions to modify the -trajectory. Coordinate transformations, such as PBC corrections and molecule fitting -are often required for some analyses and visualization, and the functions in this -module allow transformations to be applied on-the-fly. -These transformation functions can be called by the user for any given -timestep of the trajectory, added as a workflow using :meth:`add_transformations` -of the :mod:`~MDAnalysis.coordinates.base` module, or upon Universe creation using -the keyword argument `transformations`. Note that in the two latter cases, the -workflow cannot be changed after being defined. - -A simple transformation that takes no other arguments but the `Timestep` can be defined +The transformations submodule :mod:`MDAnalysis.transformations` contains a +collection of functions to modify the trajectory. Coordinate transformations, +such as PBC corrections and molecule fitting are often required for some +analyses and visualization, and the functions in this module allow +transformations to be applied on-the-fly. These transformation functions +(``transformation_1`` and ``transformation_2`` in the following example) can be +called by the user for any given :class:`Timestep` of the trajectory, + +.. code-block:: python + + u = MDAnalysis.Universe(topology, trajectory) + + for ts in u.trajectory: + ts = transformation_2(transformation_1(ts)) + +where they change the coordinates of the timestep ``ts`` in place. However, it +is much more convenient to associate a whole workflow of transformations with a +trajectory and have the transformations be called automatically. One can add a +workflow (a sequence of transformations) using the +:meth:`Universe.trajectory.add_transformations +` method of a +trajectory, + +.. code-block:: python + + workflow = [transformation_1, transformation_2] + u.trajectory.add_transformations(*workflow) + +or upon :class:`Universe ` +creation using the keyword argument `transformations`: + +.. code-block:: python + + u = MDAnalysis.Universe(topology, trajectory, transformations=workflow) + +Note that in the two latter cases, the workflow cannot be changed after having +being added. + +A simple transformation that takes no other arguments but a :class:`Timestep` can be defined as the following example: .. code-block:: python @@ -30,8 +58,8 @@ as the following example: return ts -If the transformation requires other arguments besides the `Timestep`, the transformation -takes these arguments, while a wrapped function takes the `Timestep` object as +If the transformation requires other arguments besides the :class:`Timestep`, the transformation +takes these arguments, while a wrapped function takes the :class:`Timestep` object as argument. So, a transformation can be roughly defined as follows: @@ -80,7 +108,7 @@ e.g. create a workflow and adding it to the trajectory: u = MDAnalysis.Universe(topology, trajectory) workflow = [MDAnalysis.transformations.translate([1,1,1]), MDAnalysis.transformations.translate([1,2,3])] - u.trajcetory.add_transformations(*workflow) + u.trajectory.add_transformations(*workflow) e.g. giving a workflow as a keyword argument when defining the universe: @@ -88,7 +116,7 @@ e.g. giving a workflow as a keyword argument when defining the universe: workflow = [MDAnalysis.transformations.translate([1,1,1]), MDAnalysis.transformations.translate([1,2,3])] - u = MDAnalysis.Universe(topology, trajectory, transformations = *workflow) + u = MDAnalysis.Universe(topology, trajectory, transformations=workflow) .. rubric:: Currently implemented transformations @@ -96,4 +124,4 @@ e.g. giving a workflow as a keyword argument when defining the universe: .. toctree:: ./transformations/translate - ./transformations/rotate \ No newline at end of file + ./transformations/rotate