Previous topic

8.1. KDTree — MDAnalysis.KDTree.KDTree

This Page

8.2. Fast atom neighbor lookup using a KD tree (implemented in C++) — MDAnalysis.KDTree.NeighborSearch

One can use KD-Trees to speed up searches. MDAnalysis uses Thomas Hamelryck’s C++ implementation from Biopython. The following are fairly technical descriptions of the available classes.

If you know that you are using a specific selection repeatedly then may be faster to explicitly build the selection using the AtomNeighborSearch class instead of using MDAnalysis selections.

Example:

import MDAnalysis.KDTree.NeighborSearch as NS

u = Universe(psf,dcd)
water = u.selectAtoms('name OH2')
protein = u.selectAtoms('protein')

# when analyzing a trajectory, carry out the next two steps
# for every frame
ns_w = NS.AtomNeighborSearch(water)
solvation_shell = ns_w.search_list(protein,4.0)  # water oxygens within 4A of protein
class MDAnalysis.KDTree.NeighborSearch.AtomNeighborSearch(atom_list, bucket_size=10)

This class can be used for two related purposes:

1. To find all atoms/residues/segments within radius of a given query position.

2. To find all atoms/residues/segments that are within a fixed radius of each other.

AtomNeighborSearch makes use of the KDTree C++ module, so it’s fast.

Arguments :
atom_list

list of atoms (Atom) or a AtomGroup. This list is used in the queries. It can contain atoms from different structures.

bucket_size

bucket size of KD tree. You can play around with this to optimize speed if you feel like it.

search(center, radius, level='A')

Neighbor search.

Return all atoms/residues/segments that have at least one atom within radius of center.

Arguments :
center

numpy array of shape 3 (cartesian coordinates)

radius

float

level

char (A, R, S); what entitity level is returned (e.g. atoms or residues) is determined by level (A=atoms, R=residues, S=Segments).

In order to obtain the coordinates for the center argument from a AtomGroup one can simply provide the output of the centroid or centerOfMass functions.

search_all(radius, level='A')

All neighbor search.

Search all entities that have atoms pairs within radius.

Arguments :
radius

float

level

char (A, R, S); what entitity level is returned (e.g. atoms or residues) is determined by level (A=atoms, R=residues, S=Segments).

search_list(other, radius, level='A')

Search neighbours near all atoms in atoms.

Returns all atoms/residues/segments that contain atoms that are within radius of any other atom listed in other, i.e. “find all A within R of B” where A are the atoms used for setting up the AtomNeighborSearch and B are the other atoms.

Arguments :
other

AtomGroup or list of Atom instances

radius

float

level

char (A, R, S); what entitity level is returned (e.g. atoms or residues) is determined by level (A=atoms, R=residues, S=Segments).

class MDAnalysis.KDTree.NeighborSearch.CoordinateNeighborSearch(coordinates, bucket_size=10)

This class can be used for two related purposes:

1. To find all indices of a coordinate list within radius of a given query position.

2. To find all indices of a coordinate list that are within a fixed radius of each other.

CoordinateNeighborSearch makes use of the KDTree C++ module, so it’s fast.

Arguments :
coordinates

list of N coordinates (Nx3 numpy array)

bucket_size

bucket size of KD tree. You can play around with this to optimize speed if you feel like it.

search(center, radius, distances=False)

Neighbor search.

Return all indices in the coordinates list that have at least one atom within radius of center.

Arguments :
  • center

    numpy array

  • radius

    float

  • distances

    bool True: return (indices,distances); False: return indices only

search_all(radius, distances=False)

All neighbor search.

Return all index pairs corresponding to coordinates within the radius.

Arguments :
radius

float

distances

bool True: return (indices,distances); False: return indices only [False]

search_list(centers, radius)

Search neighbours near all centers.

Returns all indices that are within radius of any center listed in centers, i.e. “find all A within R of B” where A are the coordinates used for setting up the CoordinateNeighborSearch and B are the centers.

Arguments :
centers

Mx3 numpy array of M centers

radius

float