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)
wheren
is the number of particles andk
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
orarray_like
, optional) – The unit cell dimensions of the system, which must be orthogonal and provided in the same format as returned byMDAnalysis.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 ofn
positions for one frame.out (
None
ornumpy.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 ofpos1 - 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()
orMDAnalysis.lib.distances.calc_bonds()
instead.If box is provided, the minimum image convention is taken into account using algorithm C4 from Deiters[1] (
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
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.]]])