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
(reference, configuration, box=None, result=None)[source]¶ Calculate all distances between a reference set and another configuration.
If there are i positions in reference, and j positions in configuration, will calculate a i x j array of distances If an box is supplied then a minimum image convention is used when calculating distances.
If a 2D numpy array of dtype
numpy.float64
with the shape(len(reference), len(configuration))
is provided in result then this preallocated array is filled. This can speed up calculations.d = distance_array(reference, configuration[,box[,result=d]])
Parameters: - *reference* – reference coordinate array (must be numpy.float32)
- *configuration* – configuration coordinate array (must be numpy.float32)
- *box* – cell dimensions (minimum image convention is applied)
or None [
None
]. Cell dimensions must be in an identical to format to those returned byMDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma] - *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(reference),len(configuration)) numpy array with the distances d[i,j] between reference coordinates i and configuration 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
(reference, box=None, result=None)[source]¶ Calculate all distances within a configuration reference.
If a box is supplied then a minimum image convention is used before calculating distances.
If a 1D numpy array of dtype
numpy.float64
with the shape(N*(N-1)/2)
is provided in result then this preallocated array is filled. This can speed up calculations.Parameters: - *ref* – reference coordinate array with N=len(ref) coordinates
- *box* – cell dimensions (minimum image convention is applied)
or None [
None
] Cell dimensions must be in an identical to format to those returned byMDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma] - *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)[source]¶ Calculates a matrix of contacts within a numpy array of type float32.
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.Changed in version 0.11.0: Keyword suppress_progmet and progress_meter_freq were removed.
-
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.
Parameters: B (*A*,) –
AtomGroup
with the same number of atomsKeywords: - 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])