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)[source]¶ 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: -
search
(center, radius, level='A')[source]¶ 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 thecentroid
orcenterOfMass
functions.
-
search_all
(radius, level='A')[source]¶ 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')[source]¶ 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:
-
-
class
MDAnalysis.KDTree.NeighborSearch.
CoordinateNeighborSearch
(coordinates, bucket_size=10)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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