12.2.1. Fast distance array computation — MDAnalysis.lib.distances

Fast C-routines to calculate distance arrays from coordinate arrays. Many of the functions also exist in parallel versions, that typically provide higher performance than the serial code. The boolean attribute MDAnalysis.lib.distances.USED_OPENMP can be checked to see if OpenMP was used in the compilation of MDAnalysis.

12.2.1.1. Selection of acceleration (“backend”)

All functions take the optional keyword backend, which determines the type of acceleration. Currently, the following choices are implemented (backend is case-insensitive):

Available backends for accelerated distance functions.
backend module description
“serial” c_distances serial implementation in C/Cython
“OpenMP” c_distances_openmp parallel implementation in C/Cython with OpenMP

New in version 0.13.0.

12.2.1.2. Functions

MDAnalysis.lib.distances.distance_array(reference, configuration[, box[, result[, backend]]])[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)) and dtype=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 distances d[i,j] between reference coordinates i and configuration coordinates j.

Return type:

numpy.array

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.lib.distances.self_distance_array(reference[, box[, result[, backend]]])[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 dtype 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:

dN*(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:

array

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.

MDAnalysis.lib.distances.calc_bonds(atom1, atom2[, box[, result[, backend]]])[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 with len(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]])

Parameters:
  • coords1 (array) – An array of coordinates for one half of the bond.
  • coords2 (array) – An array of coordinates for the other half of bond
  • box (array) – The unitcell dimesions for this system. 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 be same length as coord arrays and dtype=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:

bondlengths – The length between each pair in coords1 and coords2

Return type:

array

New in version 0.8.

Changed in version 0.13.0: Added backend keyword.

MDAnalysis.lib.distances.calc_angles(atom1, atom2, atom3[, box[, result[, backend]]])[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 with len(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])

Parameters:
  • coords1 (array) – Coordinate array of one side of angles.
  • coords2 (array) – Coordinate array of apex of angles.
  • coords3 (array) – Coordinate array of other side of angles.
  • box (array) – The unitcell dimesions for this system. 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 be same length as coord arrays and dtype=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:

angles – A numpy.array of angles in radians.

Return type:

array

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.13.0: Added backend keyword.

MDAnalysis.lib.distances.calc_dihedrals(atom1, atom2, atom3, atom4[, box[, result[, backend]]])[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 with len(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])
Parameters:
  • coords1 (array) – Coordinate array of 1st atom in dihedrals.
  • coords2 (array) – Coordinate array of 2nd atom in dihedrals.
  • coords3 (array) – Coordinate array of 3rd atom in dihedrals.
  • coords4 (array) – Coordinate array of 4th atom in dihedrals.
  • box (array) – The unitcell dimesions for this system. 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 be same length as coord arrays and dtype=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:

angles – A numpy.array of angles in radians.

Return type:

array

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

Changed in version 0.13.0: Added backend keyword.

MDAnalysis.lib.distances.apply_PBC(coordinates, box[, backend])[source]

Moves a set of coordinates to all be within the primary unit cell

newcoords = apply_PBC(coords, box)

Parameters:
  • coords (array) – Coordinate array (of type numpy.float32).
  • box (array) – The unitcell dimesions for this system; can be either orthogonal or triclinic information. The dimensions must be provided in the same format as returned by MDAnalysis.coordinates.base.Timestep.dimensions: [lx, ly, lz, alpha, beta, gamma].
  • backend – Select the type of acceleration; “serial” is always available. Other possibilities are “OpenMP” (OpenMP).
Returns:

newcoords – Coordinates that are now all within the primary unit cell, as defined by box.

Return type:

array

New in version 0.8.

Changed in version 0.13.0: Added backend keyword.

MDAnalysis.lib.distances.transform_RtoS(coordinates, box[, backend])[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()

Parameters:
  • inputcoords (array) – A (3,) coordinate or (n x 3) array of coordinates, type np.float32.
  • box (array) – The unitcell dimesions for this system. The dimensions must be provided in the same format as returned by MDAnalysis.coordinates.base.Timestep.dimensions: [lx, ly, lz, alpha, beta, gamma].
  • backend – Select the type of acceleration; “serial” is always available. Other possibilities are “OpenMP” (OpenMP).
Returns:

  • outcoords (array) – A n x 3 array of fractional coordiantes.
  • .. versionchanged:: 0.13.0 – Added backend keyword.

MDAnalysis.lib.distances.transform_StoR(coordinates, box[, backend])[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()

Parameters:
  • inputcoords (array) – A (3,) coordinate or (n x 3) array of coordinates, type np.float32.
  • box (array) – The unitcell dimesions for this system. The dimensions must be provided in the same format as returned by MDAnalysis.coordinates.base.Timestep.dimensions: [lx, ly, lz, alpha, beta, gamma].
  • backend – Select the type of acceleration; “serial” is always available. Other possibilities are “OpenMP” (OpenMP).
Returns:

outcoords – A n x 3 array of fracional coordiantes.

Return type:

array

Changed in version 0.13.0: Added backend keyword.

MDAnalysis.lib.distances.apply_PBC(incoords, box, backend='serial')[source]

Moves a set of coordinates to all be within the primary unit cell

newcoords = apply_PBC(coords, box)

Parameters:
  • coords (array) – Coordinate array (of type numpy.float32).
  • box (array) – The unitcell dimesions for this system; can be either orthogonal or triclinic information. The dimensions must be provided in the same format as returned by MDAnalysis.coordinates.base.Timestep.dimensions: [lx, ly, lz, alpha, beta, gamma].
  • backend – Select the type of acceleration; “serial” is always available. Other possibilities are “OpenMP” (OpenMP).
Returns:

newcoords – Coordinates that are now all within the primary unit cell, as defined by box.

Return type:

array

New in version 0.8.

Changed in version 0.13.0: Added backend keyword.

MDAnalysis.lib.distances.calc_angles(coords1, coords2, coords3, box=None, result=None, backend='serial')[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 with len(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])

Parameters:
  • coords1 (array) – Coordinate array of one side of angles.
  • coords2 (array) – Coordinate array of apex of angles.
  • coords3 (array) – Coordinate array of other side of angles.
  • box (array) – The unitcell dimesions for this system. 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 be same length as coord arrays and dtype=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:

angles – A numpy.array of angles in radians.

Return type:

array

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.13.0: Added backend keyword.

MDAnalysis.lib.distances.calc_bonds(coords1, coords2, box=None, result=None, backend='serial')[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 with len(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]])

Parameters:
  • coords1 (array) – An array of coordinates for one half of the bond.
  • coords2 (array) – An array of coordinates for the other half of bond
  • box (array) – The unitcell dimesions for this system. 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 be same length as coord arrays and dtype=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:

bondlengths – The length between each pair in coords1 and coords2

Return type:

array

New in version 0.8.

Changed in version 0.13.0: Added backend keyword.

MDAnalysis.lib.distances.calc_dihedrals(coords1, coords2, coords3, coords4, box=None, result=None, backend='serial')[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 with len(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])
Parameters:
  • coords1 (array) – Coordinate array of 1st atom in dihedrals.
  • coords2 (array) – Coordinate array of 2nd atom in dihedrals.
  • coords3 (array) – Coordinate array of 3rd atom in dihedrals.
  • coords4 (array) – Coordinate array of 4th atom in dihedrals.
  • box (array) – The unitcell dimesions for this system. 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 be same length as coord arrays and dtype=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:

angles – A numpy.array of angles in radians.

Return type:

array

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

Changed in version 0.13.0: Added backend keyword.

MDAnalysis.lib.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)) and dtype=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 distances d[i,j] between reference coordinates i and configuration coordinates j.

Return type:

numpy.array

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.lib.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 dtype 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:

dN*(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:

array

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.

MDAnalysis.lib.distances.transform_RtoS(inputcoords, box, backend='serial')[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()

Parameters:
  • inputcoords (array) – A (3,) coordinate or (n x 3) array of coordinates, type np.float32.
  • box (array) – The unitcell dimesions for this system. The dimensions must be provided in the same format as returned by MDAnalysis.coordinates.base.Timestep.dimensions: [lx, ly, lz, alpha, beta, gamma].
  • backend – Select the type of acceleration; “serial” is always available. Other possibilities are “OpenMP” (OpenMP).
Returns:

  • outcoords (array) – A n x 3 array of fractional coordiantes.
  • .. versionchanged:: 0.13.0 – Added backend keyword.

MDAnalysis.lib.distances.transform_StoR(inputcoords, box, backend='serial')[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()

Parameters:
  • inputcoords (array) – A (3,) coordinate or (n x 3) array of coordinates, type np.float32.
  • box (array) – The unitcell dimesions for this system. The dimensions must be provided in the same format as returned by MDAnalysis.coordinates.base.Timestep.dimensions: [lx, ly, lz, alpha, beta, gamma].
  • backend – Select the type of acceleration; “serial” is always available. Other possibilities are “OpenMP” (OpenMP).
Returns:

outcoords – A n x 3 array of fracional coordiantes.

Return type:

array

Changed in version 0.13.0: Added backend keyword.

12.2.2. Low-level modules for MDAnalysis.lib.distances

MDAnalysis.lib._distances contains low level access to the serial MDAnalysis Cython functions in distances. These have little to no error checking done on inputs so should be used with caution. Similarly, MDAnalysis.lib._distances_openmp contains the OpenMP-enable functions.