4.2.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
.
See also
-
MDAnalysis.analysis.distances.
distance_array
(reference, configuration, box=None, result=None, backend=’serial’)[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.Parameters: - reference (numpy.array of numpy.float32) – Reference coordinate array.
- configuration (numpy.array of numpy.float32) – Configuration coordinate array.
- box (numpy.array or None) – Dimensions of the cell; if provided, the minimum image convention is
applied. The dimensions must be provided in the same format as returned
by by
MDAnalysis.coordinates.base.Timestep.dimensions
:[lx, ly, lz, alpha, beta, gamma]
. - result (numpy.array of numpy.float64, optional) – Preallocated result array which must have the
shape
(len(ref), len(conf))
anddtype=numpy.float64
. Avoids creating the array which saves time when the function is called repeatedly. [None
] - backend – Select the type of acceleration; “serial” is always available. Other possibilities are “OpenMP” (OpenMP).
Returns: d –
(len(reference),len(configuration))
numpy array with the distancesd[i,j]
between reference coordinates i and configuration coordinates j.Return type: Note
This method is slower than it could be because internally we need to make copies of the ref and conf arrays.
Changed in version 0.13.0: Added backend keyword.
-
MDAnalysis.analysis.distances.
self_distance_array
(reference, box=None, result=None, backend=’serial’)[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: - reference (array) – Reference coordinate array with
N=len(ref)
coordinates. - box (array or None) – Dimensions of the cell; if provided, the minimum image convention is
applied. The dimensions must be provided in the same format as returned
by
MDAnalysis.coordinates.base.Timestep.dimensions
:[lx, ly, lz, alpha, beta, gamma]
. - result (array, optional) – Preallocated result array which must have the shape
(N*(N-1)/2,)
and dtypenumpy.float64
. Avoids creating the array which saves time when the function is called repeatedly. [None
] - backend – Select the type of acceleration; “serial” is always available. Other possibilities are “OpenMP” (OpenMP).
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 range(N): for j in range(i+1, N): k += 1 dist[i,j] = d[k]
Return type: Note
This method is slower than it could be because internally we need to make copies of the coordinate arrays.
Changed in version 0.13.0: Added backend keyword.
- reference (array) – Reference coordinate array with
-
MDAnalysis.analysis.distances.
contact_matrix
(coord, cutoff=15.0, returntype=’numpy’, box=None)[source]¶ Calculates a matrix of contacts.
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 then periodic boundary conditions are applied.
Parameters: - coord (array) – Array of coordinates of shape
(N, 3)
and dtype float32. - cutoff (float, optional, default 15) – Particles within cutoff are considered to form a contact.
- returntype (string, optional, default "numpy") – Select how the contact matrix is returned.
*
"numpy"
: return as an(N. N)
numpy.ndarray
*"sparse"
: return as ascipy.sparse.lil_matrix
- box (array-like or
None
, optional, defaultNone
) – Simulation cell dimensions in the form ofMDAnalysis.trajectory.base.Timestep.dimensions
when periodic boundary conditions should be taken into account for the calculation of contacts.
Returns: The contact matrix is returned in a format determined by the returntype keyword.
Return type: array or sparse matrix
See also
Changed in version 0.11.0: Keyword suppress_progmet and progress_meter_freq were removed.
- coord (array) – Array of coordinates of shape
-
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 atoms - offset (integer or tuple, optional, default 0) –
An integer offset is added to resids_A and resids_B (see below) in order to produce PDB numbers.
If offset is
tuple
thenoffset[0]
is added to resids_A andoffset[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: - resids_A (array) – residue ids of the A group (possibly changed with offset)
- resids_B (array) – residue ids of the B group (possibly changed with offset)
- distances (array) – distances between the atoms
- B (A,) –
-
MDAnalysis.analysis.distances.
between
(group, A, B, distance)[source]¶ Return sub group of group that is within distance of both A and B
This function is not aware of periodic boundary conditions.
Can be used to find bridging waters or molecules in an interface.
Similar to “group and (AROUND A distance and AROUND B distance)”.
Parameters: - group (AtomGroup) – Find members of group that are between A and B
- A (AtomGroup) –
- B (AtomGroup) – A and B are the groups of atoms between which atoms in group are searched for. The function works is more efficient if group is bigger than either A or B.
- distance (float) – maximum distance for an atom to be counted as in the vicinity of A or B
Returns: AtomGroup
of atoms that fulfill the criterionReturn type: