Table Of Contents

Previous topic

7.4. Compute observable timeseries from trajectories — MDAnalysis.core.Timeseries

Next topic

7.6. Homogeneous Transformation Matrices and Quaternions — MDAnalysis.core.transformations

This Page

7.5. Fast distance array computation — MDAnalysis.core.distances

Fast C-routines to calculate distance arrays from coordinate arrays.

7.5.1. Overview

MDAnalysis.core.distances.distance_array(ref, conf[, box[, result]])

Calculate all distances d_ij between the coordinates ref[i] and conf[j] in the numpy arrays ref and conf. If an orthorhombic box is supplied then a minimum image convention is used before calculating distances.

If a 2D numpy array of dtype numpy.float64 with the shape (len(ref), len(conf)) is provided in result then this preallocated array is filled. This can speed up calculations.

MDAnalysis.core.distances.self_distance_array(ref[, box[, result]])

Calculate all distances d_ij between atoms i and j in the reference coordinates ref for all N coordinates. Other options as in distance_array().

If a 1D numpy array of dtype numpy.float64 with N*(N-1)/2 elements is provided in result then this preallocated array is filled. This can speed up calculations.

7.5.2. Functions

MDAnalysis.core.distances.boxCheck(box)

Take a box input and deduce what type of system it represents based on the shape of the array and whether all angles are 90.

Arguments:
box

box information of unknown format

Returns:
  • ortho orthogonal box
  • tri_vecs triclinic box vectors
  • tri_box triclinic box lengths and angles
  • unknown boxCheck default, indicates no match found
MDAnalysis.core.distances.calc_bonds(atom1, atom2[, box[, result]])

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]])

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]

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.core.distances.calc_angles(atom1, atom2, atom3[, box[, result]])

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])

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.

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.core.distances.calc_torsions(atom1, atom2, atom3, atom4[, box[, result]])

Calculate the torsional angle formed by four atoms, over a list of coordinates.

Torsional 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_torsions(coords1, coords2, coords3, coords4 [,box=box, result=angles])

Arguments:
coords1

coordinate array of 1st atom in torsions

coords2

coordinate array of 2nd atom in torsions

coords3

coordinate array of 3rd atom in torsions

coords4

coordinate array of 4th atom in torsions

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.

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.core.distances.applyPBC(coordinates, box)

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

newcoords = applyPBC(coords, box)

Arguments:
coords

coordinate array (of type numpy.float32)

box

box dimensions, can be either orthogonal or triclinic information

Returns:
newcoords

coordinates that are now all within the primary unit cell, as defined by box

New in version 0.8.

MDAnalysis.core.distances.transform_RtoS(coordinates, box)

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

Returns:
outcoords

An n x 3 array of fracional coordiantes

MDAnalysis.core.distances.transform_StoR(coordinates, box)

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

Returns:
outcoords

An n x 3 array of fracional coordiantes