vdist

mdtools.box.vdist(pos1, pos2, box=None, out=None)[source]

Calculate the distance vectors between two position arrays.

Parameters

pos1, pos2 (array_like) – The two position arrays between which to calculate the distance vectors. Position arrays must be of shape (3,), (n, 3) or (k, n, 3) where n is the number of particles and k is the number of frames. If pos1 and pos2 do not have the same shape, they must be broadcastable to a common shape (which becomes the shape of the output). The user is responsible to provide inputs that result in a physically meaningful broadcasting!
box (None or array_like, optional) – The unit cell dimensions of the system, which must be orthogonal and provided in the same format as returned by MDAnalysis.coordinates.base.Timestep.dimensions: [lx, ly, lz, alpha, beta, gamma]. If supplied, the minimum image convention is taken into account. Works currently only for orthogonal boxes. box can also be an array of boxes of shape (k, 6) (one box for each frame). In this case a 2-dimensional position array is interpreted to contain one position per frame instead of n positions for one frame.
out (None or numpy.ndarray, optional) – Preallocated array into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided, a freshly-allocated array is returned.

Returns

dist_vecs (numpy.ndarray) – Distance array containing the result of pos1 - pos2.

See also

MDAnalysis.lib.distances.distance_array(): Calculate all possible distances between a reference set and another configuration
MDAnalysis.lib.distances.self_distance_array(): Calculate all possible distances within a configuration
MDAnalysis.lib.distances.calc_bonds(): Calculate the bond lengths between pairs of atom positions from the two coordinate arrays
MDAnalysis.analysis.distances.dist(): Calculate the distance between atoms in two MDAnalysis AtomGroups
mdtools.numpy_helper_functions.subtract_mic(): Subtract two arrays element-wise respecting the minium image convention
mdtools.numpy_helper_functions.diff_mic(): Calculate the difference between array elements respecting the minimum image convention.

Notes

If your are only interested in the distances itself (i.e. the norm of the distance vectors), consider using MDAnalysis.analysis.distances.dist() or MDAnalysis.lib.distances.calc_bonds() instead.

If box is provided, the minimum image convention is taken into account using algorithm C4 from Deiters1 (dist_vecs -= numpy.floor(dist_vecs / box + 0.5) * box). This algorithm also works if the particle distances are an arbitrary multiple of the box length.

References

1: U. K. Deiters, “Efficient Coding of the Minimum Image Convention”, Zeitschrift für Physikalische Chemie, 2013, 227, 345-352.

Examples

Shape of pos1 and pos2 is (3,):

>>> pos1 = np.array([0, 2, 4])
>>> pos2 = np.array([5, 3, 1])
>>> mdt.box.vdist(pos1, pos2)
array([-5., -1.,  3.])
>>> box = np.array([3, 2, 2, 90, 90, 90])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([ 1., -1., -1.])

Shape of pos1 and pos2 is (n, 3):

>>> pos1 = np.array([[0, 2, 4],
...                  [5, 3, 1]])
>>> pos2 = np.array([[5, 3, 1],
...                  [0, 2, 4]])
>>> mdt.box.vdist(pos1, pos2)
array([[-5., -1.,  3.],
       [ 5.,  1., -3.]])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[ 1., -1., -1.],
       [-1., -1., -1.]])
>>> box = np.array([[3, 2, 2, 90, 90, 90],
...                 [2, 3, 4, 90, 90, 90]])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[ 1., -1., -1.],
       [-1.,  1.,  1.]])

Shape of pos1 and pos2 is (k, n, 3):

>>> pos1 = np.array([[[0, 2, 4],
...                   [5, 3, 1]],
...
...                  [[4, 0, 2],
...                   [5, 3, 1]]])
>>> pos2 = np.array([[[5, 3, 1],
...                   [0, 2, 4]],
...
...                  [[5, 3, 1],
...                   [4, 0, 2]]])
>>> mdt.box.vdist(pos1, pos2)
array([[[-5., -1.,  3.],
        [ 5.,  1., -3.]],

       [[-1., -3.,  1.],
        [ 1.,  3., -1.]]])
>>> box = np.array([3, 2, 2, 90, 90, 90])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[[ 1., -1., -1.],
        [-1., -1., -1.]],

       [[-1., -1., -1.],
        [ 1., -1., -1.]]])
>>> box = np.array([[3, 2, 2, 90, 90, 90],
...                 [2, 3, 4, 90, 90, 90]])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[[ 1., -1., -1.],
        [-1., -1., -1.]],

       [[-1.,  0.,  1.],
        [-1.,  0., -1.]]])

Shape of pos1 is (3,) and shape of pos2 is (n, 3):

>>> pos1 = np.array([0, 2, 4])
>>> pos2 = np.array([[5, 3, 1],
...                  [0, 2, 4]])
>>> mdt.box.vdist(pos1, pos2)
array([[-5., -1.,  3.],
       [ 0.,  0.,  0.]])
>>> box = np.array([3, 2, 2, 90, 90, 90])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[ 1., -1., -1.],
       [ 0.,  0.,  0.]])
>>> box = np.array([[3, 2, 2, 90, 90, 90],
...                 [2, 3, 4, 90, 90, 90]])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[ 1., -1., -1.],
       [ 0.,  0.,  0.]])

Shape of pos1 is (3,) and shape of pos2 is (k, n, 3):

>>> pos1 = np.array([0, 2, 4])
>>> pos2 = np.array([[[5, 3, 1],
...                   [0, 2, 4]],
...
...                  [[5, 3, 1],
...                   [4, 0, 2]]])
>>> mdt.box.vdist(pos1, pos2)
array([[[-5., -1.,  3.],
        [ 0.,  0.,  0.]],

       [[-5., -1.,  3.],
        [-4.,  2.,  2.]]])
>>> box = np.array([3, 2, 2, 90, 90, 90])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[[ 1., -1., -1.],
        [ 0.,  0.,  0.]],

       [[ 1., -1., -1.],
        [-1.,  0.,  0.]]])
>>> box = np.array([[3, 2, 2, 90, 90, 90],
...                 [2, 3, 4, 90, 90, 90]])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[[ 1., -1., -1.],
        [ 0.,  0.,  0.]],

       [[-1., -1., -1.],
        [ 0., -1., -2.]]])

Shape of pos1 is (n, 3) and shape of pos2 is (k, n, 3):

>>> pos1 = np.array([[0, 2, 4],
...                  [5, 3, 1]])
>>> pos2 = np.array([[[5, 3, 1],
...                   [0, 2, 4]],
...
...                  [[5, 3, 1],
...                   [4, 0, 2]]])
>>> mdt.box.vdist(pos1, pos2)
array([[[-5., -1.,  3.],
        [ 5.,  1., -3.]],

       [[-5., -1.,  3.],
        [ 1.,  3., -1.]]])
>>> box = np.array([3, 2, 2, 90, 90, 90])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[[ 1., -1., -1.],
        [-1., -1., -1.]],

       [[ 1., -1., -1.],
        [ 1., -1., -1.]]])
>>> box = np.array([[3, 2, 2, 90, 90, 90],
...                 [2, 3, 4, 90, 90, 90]])
>>> mdt.box.vdist(pos1, pos2, box=box)
array([[[ 1., -1., -1.],
        [-1., -1., -1.]],

       [[-1., -1., -1.],
        [-1.,  0., -1.]]])