9.1. Fast distance array computation — MDAnalysis.lib.distances
¶
Fast C-routines to calculate distance arrays from coordinate arrays.
9.1.1. Functions¶
-
MDAnalysis.lib.distances.
distance_array
(reference, configuation[, box[, result]])[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]])
Arguments: - 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.lib.distances.
self_distance_array
(reference[, box[, result]])[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.Arguments: - 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.lib.distances.
calc_bonds
(atom1, atom2[, box[, result]])[source]¶ Calculate all distances between a pair of atoms. atom1 and atom2 are both arrays of coordinates, where atom1[i] and atom2[i] represent a bond.
In comparison to distance_array and self_distance_array which calculate distances between all combinations of coordinates, calc_bonds can be used to calculate distance between pairs of objects, similar to:
numpy.linalg.norm(a - b) for a, b in zip(coords1, coords2)
The optional argument box applies minimum image convention if supplied. box can be either orthogonal or triclinic
If a 1D numpy array of dtype
numpy.float64
withlen(atom1)
elements is provided in result then this preallocated array is filled. This can speed up calculations.bondlengths = calc_bonds(coords1, coords2 [, box [,result=bondlengths]])
Arguments: - coords1
An array of coordinates for one half of the bond
- coords2
An array of coordinates for the other half of bond
- box
Unit cell information if periodic boundary conditions are required [None] Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]- result
optional preallocated result array which must be same length as coord arrays and dtype=numpy.float64. Avoids creating the array which saves time when the function is called repeatedly. [None]
Returns: - bondlengths
Numpy array with the length between each pair in coords1 and coords2
New in version 0.8.
-
MDAnalysis.lib.distances.
calc_angles
(atom1, atom2, atom3[, box[, result]])[source]¶ Calculates the angle formed between three atoms, over a list of coordinates. All atom inputs are lists of coordinates of equal length, with atom2 representing the apex of the angle.
If a 1D numpy array of dtype
numpy.float64
withlen(atom1)
elements is provided in result then this preallocated array is filled. This can speed up calculations.The optional argument
box
ensures that periodic boundaries are taken into account when constructing the connecting vectors between atoms, ie that the vector between atoms 1 & 2 goes between coordinates in the same image.angles = calc_angles(coords1, coords2, coords3, [[box=None],result=angles])
Arguments: - coords1
coordinate array of one side of angles
- coords2
coordinate array of apex of angles
- coords3
coordinate array of other side of angles
- box
optional unit cell information. This ensures that the connecting vectors between atoms respect minimum image convention. This is import when the angle might be between atoms in different images. Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]- result
optional preallocated results array which must have same length as coordinate array and dtype=numpy.float64.
Returns: - angles
A numpy.array of angles in radians
New in version 0.8.
Changed in version 0.9.0: Added optional box argument to account for periodic boundaries in calculation
-
MDAnalysis.lib.distances.
calc_dihedrals
(atom1, atom2, atom3, atom4[, box[, result]])[source]¶ Calculate the dihedral angle formed by four atoms, over a list of coordinates.
Dihedral angle around axis connecting atoms 1 and 2 (i.e. the angle between the planes spanned by atoms (0,1,2) and (1,2,3)):
3 | 1-----2 / 0
If a 1D numpy array of dtype
numpy.float64
withlen(atom1)
elements is provided in result then this preallocated array is filled. This can speed up calculations.The optional argument
box
ensures that periodic boundaries are taken into account when constructing the connecting vectors between atoms, ie that the vector between atoms 1 & 2 goes between coordinates in the same image.angles = calc_dihedrals(coords1, coords2, coords3, coords4 [,box=box, result=angles])
Arguments: - coords1
coordinate array of 1st atom in dihedrals
- coords2
coordinate array of 2nd atom in dihedrals
- coords3
coordinate array of 3rd atom in dihedrals
- coords4
coordinate array of 4th atom in dihedrals
- box
optional unit cell information. This ensures that the connecting vectors between atoms respect minimum image convention. This is import when the angle might be between atoms in different images. Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]- result
optional preallocated results array which must have same length as coordinate array and dtype=numpy.float64.
Returns: - angles
A numpy.array of angles in radians
New in version 0.8.
Changed in version 0.9.0: Added optional box argument to account for periodic boundaries in calculation
Changed in version 0.11.0: Renamed from calc_torsions to calc_dihedrals
-
MDAnalysis.lib.distances.
apply_PBC
(coordinates, box)[source]¶ Moves a set of coordinates to all be within the primary unit cell
newcoords = apply_PBC(coords, box)
Arguments: - coords
coordinate array (of type numpy.float32)
- box
box dimensions, can be either orthogonal or triclinic information Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]
Returns: - newcoords
coordinates that are now all within the primary unit cell, as defined by box
New in version 0.8.
-
MDAnalysis.lib.distances.
transform_RtoS
(coordinates, box)[source]¶ Transform an array of coordinates from real space to S space (aka lambda space)
S space represents fractional space within the unit cell for this system
Reciprocal operation to
transform_StoR()
Arguments: - inputcoords
An n x 3 array of coordinate data, of type np.float32
- box
The unitcell dimesions for this system Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]
Returns: - outcoords
An n x 3 array of fractional coordiantes
-
MDAnalysis.lib.distances.
transform_StoR
(coordinates, box)[source]¶ Transform an array of coordinates from S space into real space.
S space represents fractional space within the unit cell for this system
Reciprocal operation to
transform_RtoS()
Arguments: - inputcoords
An n x 3 array of coordinate data, of type np.float32
- box
The unitcell dimesions for this system Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]
Returns: - outcoords
An n x 3 array of fracional coordiantes
-
MDAnalysis.lib.distances.
apply_PBC
(incoords, box)[source] Moves a set of coordinates to all be within the primary unit cell
newcoords = apply_PBC(coords, box)
Arguments: - coords
coordinate array (of type numpy.float32)
- box
box dimensions, can be either orthogonal or triclinic information Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]
Returns: - newcoords
coordinates that are now all within the primary unit cell, as defined by box
New in version 0.8.
-
MDAnalysis.lib.distances.
calc_angles
(coords1, coords2, coords3, box=None, result=None)[source] Calculates the angle formed between three atoms, over a list of coordinates. All atom inputs are lists of coordinates of equal length, with atom2 representing the apex of the angle.
If a 1D numpy array of dtype
numpy.float64
withlen(atom1)
elements is provided in result then this preallocated array is filled. This can speed up calculations.The optional argument
box
ensures that periodic boundaries are taken into account when constructing the connecting vectors between atoms, ie that the vector between atoms 1 & 2 goes between coordinates in the same image.angles = calc_angles(coords1, coords2, coords3, [[box=None],result=angles])
Arguments: - coords1
coordinate array of one side of angles
- coords2
coordinate array of apex of angles
- coords3
coordinate array of other side of angles
- box
optional unit cell information. This ensures that the connecting vectors between atoms respect minimum image convention. This is import when the angle might be between atoms in different images. Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]- result
optional preallocated results array which must have same length as coordinate array and dtype=numpy.float64.
Returns: - angles
A numpy.array of angles in radians
New in version 0.8.
Changed in version 0.9.0: Added optional box argument to account for periodic boundaries in calculation
-
MDAnalysis.lib.distances.
calc_bonds
(coords1, coords2, box=None, result=None)[source] Calculate all distances between a pair of atoms. atom1 and atom2 are both arrays of coordinates, where atom1[i] and atom2[i] represent a bond.
In comparison to distance_array and self_distance_array which calculate distances between all combinations of coordinates, calc_bonds can be used to calculate distance between pairs of objects, similar to:
numpy.linalg.norm(a - b) for a, b in zip(coords1, coords2)
The optional argument box applies minimum image convention if supplied. box can be either orthogonal or triclinic
If a 1D numpy array of dtype
numpy.float64
withlen(atom1)
elements is provided in result then this preallocated array is filled. This can speed up calculations.bondlengths = calc_bonds(coords1, coords2 [, box [,result=bondlengths]])
Arguments: - coords1
An array of coordinates for one half of the bond
- coords2
An array of coordinates for the other half of bond
- box
Unit cell information if periodic boundary conditions are required [None] Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]- result
optional preallocated result array which must be same length as coord arrays and dtype=numpy.float64. Avoids creating the array which saves time when the function is called repeatedly. [None]
Returns: - bondlengths
Numpy array with the length between each pair in coords1 and coords2
New in version 0.8.
-
MDAnalysis.lib.distances.
calc_dihedrals
(coords1, coords2, coords3, coords4, box=None, result=None)[source] Calculate the dihedral angle formed by four atoms, over a list of coordinates.
Dihedral angle around axis connecting atoms 1 and 2 (i.e. the angle between the planes spanned by atoms (0,1,2) and (1,2,3)):
3 | 1-----2 / 0
If a 1D numpy array of dtype
numpy.float64
withlen(atom1)
elements is provided in result then this preallocated array is filled. This can speed up calculations.The optional argument
box
ensures that periodic boundaries are taken into account when constructing the connecting vectors between atoms, ie that the vector between atoms 1 & 2 goes between coordinates in the same image.angles = calc_dihedrals(coords1, coords2, coords3, coords4 [,box=box, result=angles])
Arguments: - coords1
coordinate array of 1st atom in dihedrals
- coords2
coordinate array of 2nd atom in dihedrals
- coords3
coordinate array of 3rd atom in dihedrals
- coords4
coordinate array of 4th atom in dihedrals
- box
optional unit cell information. This ensures that the connecting vectors between atoms respect minimum image convention. This is import when the angle might be between atoms in different images. Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]- result
optional preallocated results array which must have same length as coordinate array and dtype=numpy.float64.
Returns: - angles
A numpy.array of angles in radians
New in version 0.8.
Changed in version 0.9.0: Added optional box argument to account for periodic boundaries in calculation
Changed in version 0.11.0: Renamed from calc_torsions to calc_dihedrals
-
MDAnalysis.lib.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]])
Arguments: - 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.lib.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.Arguments: - 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.lib.distances.
transform_RtoS
(inputcoords, box)[source] Transform an array of coordinates from real space to S space (aka lambda space)
S space represents fractional space within the unit cell for this system
Reciprocal operation to
transform_StoR()
Arguments: - inputcoords
An n x 3 array of coordinate data, of type np.float32
- box
The unitcell dimesions for this system Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]
Returns: - outcoords
An n x 3 array of fractional coordiantes
-
MDAnalysis.lib.distances.
transform_StoR
(inputcoords, box)[source] Transform an array of coordinates from S space into real space.
S space represents fractional space within the unit cell for this system
Reciprocal operation to
transform_RtoS()
Arguments: - inputcoords
An n x 3 array of coordinate data, of type np.float32
- box
The unitcell dimesions for this system Cell dimensions must be in an identical to format to those returned by
MDAnalysis.coordinates.base.Timestep.dimensions
, [lx, ly, lz, alpha, beta, gamma]
Returns: - outcoords
An n x 3 array of fracional coordiantes