3.1.3. Distance analysis — MDAnalysis.analysis.distances

This module provides functions to rapidly compute distances between atoms or groups of atoms.

dist() and between() can take atom groups that do not even have to be from the same Universe.

MDAnalysis.analysis.distances.distance_array()

Calculate all distances between a reference set and another configuration.

d = distance_array(ref,conf[,box[,result=d]])

Arguments:
ref

reference coordinate array

conf

configuration coordinate array

box

cell dimensions (minimum image convention is applied) or None [None]

result

optional preallocated result array which must have the shape (len(ref), len(conf)) and dtype=numpy.float64. Avoids creating the array which saves time when the function is called repeatedly. [None]

Returns:
d

(len(ref),len(conf)) numpy array with the distances d[i,j] between ref coordinates i and conf coordinates j

Note

This method is slower than it could be because internally we need to make copies of the ref and conf arrays.

MDAnalysis.analysis.distances.self_distance_array()

Calculate all distances d_ij between atoms i and j within a configuration ref.

d = self_distance_array(ref[,box[,result=d]])

Arguments:
ref

reference coordinate array with N=len(ref) coordinates

box

cell dimensions (minimum image convention is applied) or None [None]

result
optional preallocated result array which must have the shape

(N*(N-1)/2,) and dtype numpy.float64. Avoids creating the array which saves time when the function is called repeatedly. [None]

Returns:
d
N*(N-1)/2 numpy 1D array with the distances dist[i,j] between ref

coordinates i and j at position d[k]. Loop through d:

for i in xrange(N):
   for j in xrange(i+1, N):
       k += 1
       dist[i,j] = d[k]

Note

This method is slower than it could be because internally we need to make copies of the coordinate arrays.

MDAnalysis.analysis.distances.contact_matrix(coord, cutoff=15.0, returntype='numpy', box=None, progress_meter_freq=100, suppress_progmet=False)[source]

Calculates a matrix of contacts between a list of coordinates.

There is a fast, high-memory-usage version for small systems (returntype = ‘numpy’), and a slower, low-memory-usage version for larger systems (returntype = ‘sparse’).

If box dimensions are passed (box = [Lx, Ly, Lz]), then periodic boundary conditions are applied. Only orthorhombic boxes are currently supported.

Change progress_meter_freq to alter frequency of progress meter updates. Or switch suppress_progmet to True to suppress it completely.

MDAnalysis.analysis.distances.dist(A, B, offset=0)[source]

Return distance between atoms in two atom groups.

The distance is calculated atom-wise. The residue ids are also returned because a typical use case is to look at CA distances before and after an alignment. Using the offset keyword one can also add a constant offset to the resids which facilitates comparison with PDB numbering.

Arguments:
A, B

AtomGroup with the same number of atoms

Keywords:
offset : integer

The offset is added to resids_A and resids_B (see below) in order to produce PDB numbers. The default is 0.

offset : tuple

offset[0] is added to resids_A and offset[1] to resids_B. Note that one can actually supply numpy arrays of the same length as the atom group so that an individual offset is added to each resid.

Returns:

NumPy array([resids_A, resids_B, distances])