iQ dZddlZddlmZddlmZmZmZddlm Z e rddl m Z ddl m Z mZdd lmZdd lmZmZdd lmZdd lmZmZdd lmZddlZiZejdded< ejdded<n #e$rYnwxYwerejdded<[ dJdedee dee!dedef dZ"ddlm#Z#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z-m.Z.m/Z/m0Z0m1Z1m2Z2m3Z3m4Z4m5Z5ddl6m7Z8deej9de dej9fd Z:e d!d"d#d#d$% dJd!eej9d&fd"eej9d&fd'eej9deej9dedej9f d(Z;e d!d#d$) dJd!eej9d&fd'eej9deej9dedej9f d*Z<e d!d"d#d#d#d$+ dKd!eej9d&fd"eej9d&fd,e=d-ee=d'eej9d.eed/ee>deefd0Z? dLd!ej9d"ej9d,e=d-ee=d'eej9d.eedefd1Z@e d!d"d#d#d#d$+ dMd!eej9d&fd"eej9d&fd,e=d-ee=d'eej9d/ee>deefd2ZAe d!d"d#d#d#d$+ dMd!eej9d&fd"eej9d&fd,e=d-ee=d'eej9d/ee>deefd3ZBe d!d"d#d#d#d$+ dNd!eej9d&fd"eej9d&fd,e=d-ee=d'eej9d/ee>f d4ZCe d!d#d#d#d$+ dKd!eej9d&fd,e=d-ee=d'eej9d.eed/ee>deefd5ZD dLd!ej9d,e=d-ee=d'eej9d.eef d6ZEe d!d#d#d$7 dMd!eej9d&fd,e=d-ee=d'eej9d/ee>deef d8ZFe d!d#d#d$7 dMd!eej9d&fd,e=d-ee=d'eej9d/ee>deef d9ZGe d!d#d#d$7 dNd!eej9d&fd,e=d-ee=d'eej9d/ee>f d:ZHe d;dOd<ZIe d;dOd=ZJe d>d?d$@ dJd>eej9d&fd?eej9d&fd'eej9deej9dedej9f dAZKe d>d?dBd$@ dJd>eej9d&fd?eej9d&fdBeej9d&fd'eej9deej9dedej9fdCZLe d>d?dBdDd$@ dJd>eej9d&fd?eej9d&fdBeej9d&fdDeej9d&fd'eej9deej9dedej9fdEZMe d;d$@ dPd;eej9d&fd'eej9dedej9fdFZNe dGd#d#HdGej9d'ej9dej9fdIZOdS)Qu;Fast distance array computation --- :mod:`MDAnalysis.lib.distances` =================================================================== Fast C-routines to calculate arrays of distances or angles from coordinate arrays. Distance functions can accept a NumPy :class:`np.ndarray` or an :class:`~MDAnalysis.core.groups.AtomGroup`. Many of the functions also exist in parallel versions, which 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. 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): .. Table:: Available *backends* for accelerated distance functions. ========== ========================= ====================================== *backend* module description ========== ========================= ====================================== "serial" :mod:`c_distances` serial implementation in C/Cython "OpenMP" :mod:`c_distances_openmp` parallel implementation in C/Cython with OpenMP "distopia" `_distopia` SIMD-accelerated implementation with the `distopia`_ library ========== ========================= ====================================== Use of the distopia library --------------------------- MDAnalysis has developed a standalone library, `distopia`_ for accelerating the distance functions in this module using explicit SIMD vectorisation. This can provide many-fold speedups in calculating distances. Distopia is under active development and as such only a selection of functions in this module are covered. Consult the following table to see if the function you wish to use is covered by distopia. For more information see the `distopia documentation`_. .. table:: Functions available using the `distopia`_ backend. :align: center +-------------------------------------------------------+ | Functions | +=======================================================+ | :func:`MDAnalysis.lib.distances.calc_bonds` | +-------------------------------------------------------+ | :func:`MDAnalysis.lib.distances.calc_angles` | +-------------------------------------------------------+ | :func:`MDAnalysis.lib.distances.calc_dihedrals` | +-------------------------------------------------------+ | :func:`MDAnalysis.lib.distances.distance_array` | +-------------------------------------------------------+ | :func:`MDAnalysis.lib.distances.self_distance_array` | +-------------------------------------------------------+ If `distopia`_ is installed, the functions in this table will accept the key 'distopia' for the `backend` keyword argument. The variable :data:`HAS_DISTOPIA` is set to ``True`` if distopia is available. If the distopia backend is selected the `distopia` library will be used to calculate the distances. Note that for functions listed in this table **distopia is not the default backend and must be explicitly selected.** .. Note:: Due to the use of Instruction Set Architecture (`ISA`_) specific SIMD intrinsics in distopia via `HWY`_, the precision of your results may depend on the ISA available on your machine. However, in all tested cases distopia satisfied the accuracy thresholds used to the functions in this module. Please document any issues you encounter with distopia's accuracy in the `relevant distopia issue`_ on the MDAnalysis GitHub repository. .. _distopia: https://github.com/MDAnalysis/distopia .. _distopia documentation: https://www.mdanalysis.org/distopia .. _ISA: https://en.wikipedia.org/wiki/Instruction_set_architecture .. _HWY: https://github.com/google/highway .. _relevant distopia issue: https://github.com/MDAnalysis/mdanalysis/issues/3915 .. versionadded:: 0.13.0 .. versionchanged:: 2.3.0 Distance functions can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` or an :class:`np.ndarray` .. versionchanged:: 2.5.0 Interface to the `distopia`_ package added. .. versionchanged:: 2.9.0 Distopia support greatly expanded (with distopia ≥ 0.4.0). Constants --------- .. data:: HAS_DISTOPIA This variable is ``True`` if the :mod:`distopia` package has been installed and is available as a `backend`. Otherwise it is ``False``. Functions --------- .. autofunction:: distance_array .. autofunction:: self_distance_array .. autofunction:: capped_distance .. autofunction:: self_capped_distance .. autofunction:: calc_bonds .. autofunction:: calc_angles .. autofunction:: calc_dihedrals .. autofunction:: apply_PBC .. autofunction:: transform_RtoS .. autofunction:: transform_StoR .. autofunction:: augment_coordinates(coordinates, box, r) .. autofunction:: undo_augment(results, translation, nreal) .. autofunction:: minimize_vectors(vectors, box) N)UnionOptionalCallable) TYPE_CHECKING) AtomGroup) check_coords check_box)triclinic_vectors)augment_coordinates undo_augment)FastNS)_minimize_vectors_ortho_minimize_vectors_triclinic) HAS_DISTOPIAz .c_distanceszMDAnalysis.lib)packageserialz.c_distances_openmpopenmpz ._distopiadistopiafuncnameargskwargsbackendreturnc<||n t}||n t}|} tt||}n@#t $r3d|d|dt}t|dwxYw||i|S)z8Helper function to select a backend function `funcname`.Nz Function z not available with backend z try one of: )tupledictlowergetattr _distancesKeyErrorkeys ValueError)rrrrfuncerrmsgs b/srv/www/vhosts/g4struct/public_html/venv/lib/python3.11/site-packages/MDAnalysis/lib/distances.py_runr(s#44D)VVtvvFmmooG+z'*H55 +++ / / /g / /%??,, / /   d* + 4   s A=B) _UINT64_MAXcalc_distance_arraycalc_distance_array_orthocalc_distance_array_tricliniccalc_self_distance_arraycalc_self_distance_array_ortho"calc_self_distance_array_tricliniccoord_transformcalc_bond_distancecalc_bond_distance_orthocalc_bond_distance_triclinic calc_anglecalc_angle_orthocalc_angle_triclinic calc_dihedralcalc_dihedral_orthocalc_dihedral_triclinic ortho_pbc triclinic_pbc)OPENMP_ENABLEDresultshapec(| tj|tjS|j|kr(t d||j|jtjkr'td|j|S)a'Check if the result array is ok to use. The `result` array must meet the following requirements: * Must have a shape equal to `shape`. * Its dtype must be ``numpy.float64``. Paramaters ---------- result : numpy.ndarray or None The result array to check. If `result` is `None``, a newly created array of correct shape and dtype ``numpy.float64`` will be returned. shape : tuple The shape expected for the `result` array. Returns ------- result : numpy.ndarray (``dtype=numpy.float64``, ``shape=shape``) The input array or a newly created array if the input was ``None``. Raises ------ ValueError If `result` is of incorrect shape. TypeError If the dtype of `result` is not ``numpy.float64``. Ndtypez9Result array has incorrect shape, should be {0}, got {1}.z3Result array must be of type numpy.float64, got {}.)npzerosfloat64r>r$formatrA TypeError)r=r>s r'_check_result_arrayrGs:~xRZ0000 |u 6%..   |rz!! vfl##    M reference configurationFT)reduce_result_if_singlecheck_lengths_matchallow_atomgrouprboxc|jd}|jd}||ztkrtd||zdt|||f}t |dkr|S|dkrT|t j}|1t j|t jnd}|Ft|\}}|dkrtd||||f|n,td ||||f|ntd |||f||dkr(|t j }|||dd<|S) a Calculate all possible distances between a reference set and another configuration. If there are ``n`` positions in `reference` and ``m`` positions in `configuration`, a distance array of shape ``(n, m)`` will be computed. If the optional argument `box` is supplied, the minimum image convention is applied when calculating distances. Either orthogonal or triclinic boxes are supported. If a 2D numpy array of dtype ``numpy.float64`` with the shape ``(n, m)`` is provided in `result`, then this preallocated array is filled. This can speed up calculations. Parameters ---------- reference :numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Reference coordinate array of shape ``(3,)`` or ``(n, 3)`` (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. configuration : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Configuration coordinate array of shape ``(3,)`` or ``(m, 3)`` (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. box : array_like, optional The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. result : numpy.ndarray, optional Preallocated result array which must have the shape ``(n, m)`` and dtype ``numpy.float64``. Avoids creating the array which saves time when the function is called repeatedly. backend : {'serial', 'OpenMP', 'distopia'}, optional Keyword selecting the type of acceleration. Returns ------- d : numpy.ndarray (``dtype=numpy.float64``, ``shape=(n, m)``) Array containing the distances ``d[i,j]`` between reference coordinates ``i`` and configuration coordinates ``j``. .. versionchanged:: 0.13.0 Added *backend* keyword. .. versionchanged:: 0.19.0 Internal dtype conversion of input coordinates to ``numpy.float32``. Now also accepts single coordinates as input. .. versionchanged:: 2.3.0 Can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` as an argument in any position and checks inputs using type hinting. .. versionchanged:: 2.9.0 Added support for the `distopia` backend. rSize of resulting array - elements larger than size of maximum integerrNorthor+rrr,r* r>r)r$rGlenastyperBfloat32asarrayr r(rD) rIrJrNr=rconfnumrefnum distancesboxtypes r'distance_arrayr]sJ!!$G _Q F+%% 3v'7 3 3 3   $FVW,=>>I 9~~*$$RZ00 47Objoo$$RZ000  ~~  g   +Y?      /Y?      !]I6    *$$RZ00  !F111I rH)rKrMc|jd}||dz zdz}|tkrtd|dt||f}t |dkr|S|dkrT|t j}|1t j|t jnd}|Dt|\}}|dkrtd |||f| n*td |||f| ntd ||f| |dkr(|t j }|||dd<|S) aCalculate all possible distances within a configuration `reference`. If the optional argument `box` is supplied, the minimum image convention is applied when calculating distances. Either orthogonal or triclinic boxes are supported. 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 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Reference coordinate array of shape ``(3,)`` or ``(n, 3)`` (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. box : array_like, optional The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. result : numpy.ndarray, 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. backend : {'serial', 'OpenMP', 'distopia'}, optional Keyword selecting the type of acceleration. Returns ------- d : numpy.ndarray (``dtype=numpy.float64``, ``shape=(n*(n-1)/2,)``) Array containing the distances ``dist[i,j]`` between reference coordinates ``i`` and ``j`` at position ``d[k]``. Loop through ``d``: .. code-block:: python for i in range(n): for j in range(i + 1, n): dist[i, j] = dist[j, i] = d[k] k += 1 .. versionchanged:: 0.13.0 Added *backend* keyword. .. versionchanged:: 0.19.0 Internal dtype conversion of input coordinates to ``numpy.float32``. .. versionchanged:: 2.3.0 Can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` as an argument in any position and checks inputs using type hinting. .. versionchanged:: 2.9.0 Added support for the `distopia` backend. rr rrPrQrNrRr.rSr/r-rT)rIrNr=rrZdistnumr[r\s r'self_distance_arrayr`st_Q F #q(G ,w , , ,   $FWJ77I 9~~*$$RZ00 47Objoo$$RZ000  ~~  g   0i0      4i0      &Y'    *$$RZ00  !F111I rH) enforce_copyrKrLrM max_cutoff min_cutoffmethodreturn_distancesc |@tj|tj}|jddkrt d|}|} t || ||||} | jdkr| ||||||S| ||||||| S) aCalculates pairs of indices corresponding to entries in the `reference` and `configuration` arrays which are separated by a distance lying within the specified cutoff(s). Optionally, these distances can be returned as well. If the optional argument `box` is supplied, the minimum image convention is applied when calculating distances. Either orthogonal or triclinic boxes are supported. An automatic guessing of the optimal method to calculate the distances is included in the function. An optional keyword for the method is also provided. Users can enforce a particular method with this functionality. Currently brute force, grid search, and periodic KDtree methods are implemented. Parameters ----------- reference : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Reference coordinate array with shape ``(3,)`` or ``(n, 3)``. Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. configuration : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Configuration coordinate array with shape ``(3,)`` or ``(m, 3)``. Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. max_cutoff : float Maximum cutoff distance between the reference and configuration. min_cutoff : float, optional Minimum cutoff distance between reference and configuration. box : array_like, optional The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. method : {'bruteforce', 'nsgrid', 'pkdtree'}, optional Keyword to override the automatic guessing of the employed search method. return_distances : bool, optional If set to ``True``, distances will also be returned. backend : {'serial', 'OpenMP', 'distopia'}, optional Keyword selecting the type of acceleration. Returns ------- pairs : numpy.ndarray (``dtype=numpy.int64``, ``shape=(n_pairs, 2)``) Pairs of indices, corresponding to coordinates in the `reference` and `configuration` arrays such that the distance between them lies within the interval (`min_cutoff`, `max_cutoff`]. Each row in `pairs` is an index pair ``[i, j]`` corresponding to the ``i``-th coordinate in `reference` and the ``j``-th coordinate in `configuration`. distances : numpy.ndarray (``dtype=numpy.float64``, ``shape=(n_pairs,)``), optional Distances corresponding to each pair of indices. Only returned if `return_distances` is ``True``. ``distances[k]`` corresponds to the ``k``-th pair returned in `pairs` and gives the distance between the coordinates ``reference[pairs[k, 0]]`` and ``configuration[pairs[k, 1]]``. .. code-block:: python pairs, distances = capped_distances(reference, configuration, max_cutoff, return_distances=True) for k, [i, j] in enumerate(pairs): coord1 = reference[i] coord2 = configuration[j] distance = distances[k] See Also -------- distance_array MDAnalysis.lib.pkdtree.PeriodicKDTree.search MDAnalysis.lib.nsgrid.FastNS.search .. versionchanged:: 1.0.1 nsgrid was temporarily removed and replaced with pkdtree due to issues relating to its reliability and accuracy (Issues #2919, #2229, #2345, #2670, #2930) .. versionchanged:: 1.0.2 nsgrid enabled again .. versionchanged:: 2.3.0 Can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` as an argument in any position and checks inputs using type hinting. .. versionchanged:: 2.10.0 Added the "backend" argument to select the type of acceleration of the distance calculations. Nr@ryBox Argument is of incompatible type. The dimension should be either None or of the form [lx, ly, lz, alpha, beta, gamma]rcrNrd_nsgrid_cappedrcrNrercrNrer)rBrXrWr>r$_determine_method__name__) rIrJrbrcrNrdrerreference_positionsconfiguration_positionsfunctions r'capped_distancerrsN jBJ/// 9Q<1  3 (1+8   H,,,x   !-     x   !-    rHctttd}|||St |dkst |dkr|dSt |t |zdkr|dS|t j|d|dg}t j|d|dg}|d|dz } ngt j |d dd kr |dd } n>q>))D>>q>))Dd{''))Gj!j.99G#cJ&66IbqbM IabbM"+.."2"2M4F4F4H4HiH sZ// /H j 00 0II9%J!''11GG MsCCCJ '' 22G!!##  > 62244I%*,#(:y~yi rHc |@tj|tj}|jddkrt d|}t |||||}|jdkr||||||S||||||| S) a Calculates pairs of indices corresponding to entries in the `reference` array which are separated by a distance lying within the specified cutoff(s). Optionally, these distances can be returned as well. If the optional argument `box` is supplied, the minimum image convention is applied when calculating distances. Either orthogonal or triclinic boxes are supported. An automatic guessing of the optimal method to calculate the distances is included in the function. An optional keyword for the method is also provided. Users can enforce a particular method with this functionality. Currently brute force, grid search, and periodic KDtree methods are implemented. Parameters ----------- reference : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Reference coordinate array with shape ``(3,)`` or ``(n, 3)``. Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. max_cutoff : float Maximum cutoff distance between `reference` coordinates. min_cutoff : float, optional Minimum cutoff distance between `reference` coordinates. box : array_like, optional The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. method : {'bruteforce', 'nsgrid', 'pkdtree'}, optional Keyword to override the automatic guessing of the employed search method. return_distances : bool, optional If set to ``True``, distances will also be returned. backend : {'serial', 'OpenMP', 'distopia'}, optional Keyword selecting the type of acceleration. Returns ------- pairs : numpy.ndarray (``dtype=numpy.int64``, ``shape=(n_pairs, 2)``) Pairs of indices, corresponding to coordinates in the `reference` array such that the distance between them lies within the interval (`min_cutoff`, `max_cutoff`]. Each row in `pairs` is an index pair ``[i, j]`` corresponding to the ``i``-th and the ``j``-th coordinate in `reference`. distances : numpy.ndarray (``dtype=numpy.float64``, ``shape=(n_pairs,)``) Distances corresponding to each pair of indices. Only returned if `return_distances` is ``True``. ``distances[k]`` corresponds to the ``k``-th pair returned in `pairs` and gives the distance between the coordinates ``reference[pairs[k, 0]]`` and ``reference[pairs[k, 1]]``. .. code-block:: python pairs, distances = self_capped_distances(reference, max_cutoff, return_distances=True) for k, [i, j] in enumerate(pairs): coord1 = reference[i] coord2 = reference[j] distance = distances[k] Note ----- Currently supports brute force, grid-based, and periodic KDtree search methods. See Also -------- self_distance_array MDAnalysis.lib.pkdtree.PeriodicKDTree.search MDAnalysis.lib.nsgrid.FastNS.self_search .. versionchanged:: 0.20.0 Added `return_distances` keyword. .. versionchanged:: 1.0.1 nsgrid was temporarily removed and replaced with pkdtree due to issues relating to its reliability and accuracy (Issues #2919, #2229, #2345, #2670, #2930) .. versionchanged:: 1.0.2 enabled nsgrid again .. versionchanged:: 2.3.0 Can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` as an argument in any position and checks inputs using type hinting. .. versionchanged:: 2.10.0 Added the "backend" argument to select the type of acceleration of the distance calculations. Nr@rrgrhri_nsgrid_capped_selfrkrl)rBrXrWr>r$_determine_method_selfrn) rIrbrcrNrdrerrorqs r'self_capped_distancer,sN jBJ/// 9Q<1  3 (1%  H111x  !-     x  !-     rHctttd}|||St |dkr|dS|t j|dg}t j|dg}|d|dz }ngt j |dddkr |dd}n9E i LrHc0tjdtj}tjdtj}t |dkr;|tjdtj}|d}|d} || z } | d |zkr d |z| z } nd } | | z|dd <d |d d<| } | | d| zz z} t|| |d} | }n&t|||} | }| }|s|,| }|||k}||||}}|r||fS|S)aR Capped distance evaluations using a grid-based search method. Computes and returns an array containing pairs of indices corresponding to entries in the `reference` array which are separated by a distance lying within the specified cutoff(s). Employs a grid-based search algorithm to find relevant distances. Optionally, these distances can be returned as well. If the optional argument `box` is supplied, the minimum image convention is applied when calculating distances. Either orthogonal or triclinic boxes are supported. Parameters ---------- reference : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Reference coordinate array with shape ``(3,)`` or ``(n, 3)`` (dtype will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. max_cutoff : float Maximum cutoff distance between `reference` coordinates. min_cutoff : float, optional Minimum cutoff distance between `reference` coordinates. box : numpy.ndarray, optional The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. Returns ------- pairs : numpy.ndarray (``dtype=numpy.int64``, ``shape=(n_pairs, 2)``) Pairs of indices, corresponding to coordinates in the `reference` array such that the distance between them lies within the interval (`min_cutoff`, `max_cutoff`]. Each row in `pairs` is an index pair ``[i, j]`` corresponding to the ``i``-th and the ``j``-th coordinate in `reference`. distances : numpy.ndarray, optional Distances corresponding to each pair of indices. Only returned if `return_distances` is ``True``. ``distances[k]`` corresponds to the ``k``-th pair returned in `pairs` and gives the distance between the coordinates ``reference[pairs[k, 0]]`` and ``configuration[pairs[k, 1]]``. .. versionchanged:: 0.20.0 Added `return_distances` keyword. .. versionchanged:: 2.3.0 Can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` as an argument in any position and checks inputs using type hinting. rr@rr Nrgrryrrg333333?r{r|rFrr)rBrrrDrUrCrWrrrr self_searchrr)rIrbrcrNrerr[rrrr sizefactorrrrrs r'rrs~ HV27 + + +ERZ000I 9~~ ; "*555I==a=((D==a=((Dd{''))GZ'' :-7  &0IbqbM IabbM ~~''H sW}, ,H H)OOOJ ,,..GG I3???J ,,..G!!##  > 62244I%*,#(:y~y i LrHcoordscTt|dkr|St|\}}|dkrtj|}|tj}tjtj|d}td||f||S)aTransform an array of coordinates from real space to S space (a.k.a. lambda space) S space represents fractional space within the unit cell for this system. Reciprocal operation to :meth:`transform_StoR`. Parameters ---------- coords : numpy.ndarray A ``(3,)`` or ``(n, 3)`` array of coordinates (dtype is arbitrary, will be converted to ``numpy.float32`` internally). box : numpy.ndarray The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. backend : {'serial', 'OpenMP'}, optional Keyword selecting the type of acceleration. Returns ------- newcoords : numpy.ndarray (``dtype=numpy.float32``, ``shape=coords.shape``) An array containing fractional coordiantes. .. versionchanged:: 0.13.0 Added *backend* keyword. .. versionchanged:: 0.19.0 Internal dtype conversion of input coordinates to ``numpy.float32``. Now also accepts (and, likewise, returns) a single coordinate. rrRC)orderr0rS) rUr rBdiagrVrDrlinalginvr()rrNrr\rs r'transform_RtoSr/sD 6{{a S>>LGS'gcll **RZ C (29==%%S 1 1 1C &#@@@@ MrHct|dkr|St|\}}|dkrtj|}|tj}t d||f||S)aTransform 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 :meth:`transform_RtoS` Parameters ---------- coords : numpy.ndarray A ``(3,)`` or ``(n, 3)`` array of coordinates (dtype is arbitrary, will be converted to ``numpy.float32`` internally). box : numpy.ndarray The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. backend : {'serial', 'OpenMP'}, optional Keyword selecting the type of acceleration. Returns ------- newcoords : numpy.ndarray (``dtype=numpy.float32``, ``shape=coords.shape``) An array containing real space coordiantes. .. versionchanged:: 0.13.0 Added *backend* keyword. .. versionchanged:: 0.19.0 Internal dtype conversion of input coordinates to ``numpy.float32``. Now also accepts (and, likewise, returns) a single coordinate. rrRr0rS)rUr rBrrVrDr()rrNrr\s r'transform_StoRrastB 6{{a S>>LGS'gcll **RZ C &#@@@@ MrHcoords1coords2)rMc|jd}t||f}|dkrT|tj}|1tj|tjnd}|dkr]|Ft |\}}|dkrtd||||f|n,td||||f|ntd|||f||dkr(|tj}|||dd<|S) a Calculates the bond lengths between pairs of atom positions from the two coordinate arrays `coords1` and `coords2`, which must contain the same number of coordinates. ``coords1[i]`` and ``coords2[i]`` represent the positions of atoms connected by the ``i``-th bond. If single coordinates are supplied, a single distance will be returned. In comparison to :meth:`distance_array` and :meth:`self_distance_array`, which calculate distances between all possible combinations of coordinates, :meth:`calc_bonds` only calculates distances between pairs of coordinates, similar to:: numpy.linalg.norm(a - b) for a, b in zip(coords1, coords2) If the optional argument `box` is supplied, the minimum image convention is applied when calculating distances. Either orthogonal or triclinic boxes are supported. If a numpy array of dtype ``numpy.float64`` with shape ``(n,)`` (for ``n`` coordinate pairs) is provided in `result`, then this preallocated array is filled. This can speed up calculations. Parameters ---------- coords1 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Coordinate array of shape ``(3,)`` or ``(n, 3)`` for one half of a single or ``n`` bonds, respectively (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. coords2 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Coordinate array of shape ``(3,)`` or ``(n, 3)`` for the other half of a single or ``n`` bonds, respectively (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. box : numpy.ndarray, optional The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. result : numpy.ndarray, optional Preallocated result array of dtype ``numpy.float64`` and shape ``(n,)`` (for ``n`` coordinate pairs). Avoids recreating the array in repeated function calls. backend : {'serial', 'OpenMP', 'distopia'}, optional Keyword selecting the type of acceleration. Defaults to 'serial'. Returns ------- bondlengths : numpy.ndarray (``dtype=numpy.float64``, ``shape=(n,)``) or numpy.float64 Array containing the bond lengths between each pair of coordinates. If two single coordinates were supplied, their distance is returned as a single number instead of an array. .. versionadded:: 0.8 .. versionchanged:: 0.13.0 Added *backend* keyword. .. versionchanged:: 0.19.0 Internal dtype conversion of input coordinates to ``numpy.float32``. Now also accepts single coordinates as input. .. versionchanged:: 2.3.0 Can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` as an argument in any position and checks inputs using type hinting. .. versionchanged:: 2.5.0 Can now optionally use the fast distance functions from distopia rrNrRr2rSr3r1 r>rGrVrBrWrXr r(rD)rrrNr=rnumatom bondlengthsr\s r'rrsVRmAG%fwj99K*"((44 47Objoo$$RZ000{{ ?$S>>LGS'!!.!7C=# 2!7C=# $w 4     *"((44  #F111I rHcoords3c|jd}t||f}|dkrT|tj}|1tj|tjnd}|dkr`|Ht |\}}|dkrtd|||||f|n.td|||||f|ntd||||f||dkr(|tj}|||dd<|S) a9Calculates the angles formed between triplets of atom positions from the three coordinate arrays `coords1`, `coords2`, and `coords3`. All coordinate arrays must contain the same number of coordinates. The coordinates in `coords2` represent the apices of the angles:: 2---3 / 1 Configurations where the angle is undefined (e.g., when coordinates 1 or 3 of a triplet coincide with coordinate 2) result in a value of **zero** for that angle. If the optional argument `box` is supplied, periodic boundaries are taken into account when constructing the connecting vectors between coordinates, i.e., the minimum image convention is applied for the vectors forming the angles. Either orthogonal or triclinic boxes are supported. If a numpy array of dtype ``numpy.float64`` with shape ``(n,)`` (for ``n`` coordinate triplets) is provided in `result`, then this preallocated array is filled. This can speed up calculations. Parameters ---------- coords1 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Array of shape ``(3,)`` or ``(n, 3)`` containing the coordinates of one side of a single or ``n`` angles, respectively (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. coords2 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Array of shape ``(3,)`` or ``(n, 3)`` containing the coordinates of the apices of a single or ``n`` angles, respectively (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. coords3 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Array of shape ``(3,)`` or ``(n, 3)`` containing the coordinates of the other side of a single or ``n`` angles, respectively (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. box : numpy.ndarray, optional The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. result : numpy.ndarray, optional Preallocated result array of dtype ``numpy.float64`` and shape ``(n,)`` (for ``n`` coordinate triplets). Avoids recreating the array in repeated function calls. backend : {'serial', 'OpenMP', 'distopia'}, optional Keyword selecting the type of acceleration. Returns ------- angles : numpy.ndarray (``dtype=numpy.float64``, ``shape=(n,)``) or numpy.float64 Array containing the angles between each triplet of coordinates. Values are returned in radians (rad). If three single coordinates were supplied, the angle is returned as a single number instead of an array. .. versionadded:: 0.8 .. versionchanged:: 0.9.0 Added optional box argument to account for periodic boundaries in calculation .. versionchanged:: 0.13.0 Added *backend* keyword. .. versionchanged:: 0.19.0 Internal dtype conversion of input coordinates to ``numpy.float32``. Now also accepts single coordinates as input. .. versionchanged:: 2.3.0 Can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` as an argument in any position and checks inputs using type hinting. rrNrRr5rSr6r4r) rrrrNr=rranglesr\s r' calc_anglesrsWdmAG ' 4 4F*rz**47Objoo$$RZ000{{ ?$S>>LGS'!!&!7GS&A# *!7GS&A# w8     *rz**  F111I MrHcoords4c $|jd}t||f}|dkrT|tj}|1tj|tjnd}|dkrc|Jt |\} }| dkrtd||||||f|n0td||||||f|ntd|||||f||dkr(|tj}|||dd<|S) adCalculates the dihedral angles formed between quadruplets of positions from the four coordinate arrays `coords1`, `coords2`, `coords3`, and `coords4`, which must contain the same number of coordinates. The dihedral angle formed by a quadruplet of positions (1,2,3,4) is calculated around the axis connecting positions 2 and 3 (i.e., the angle between the planes spanned by positions (1,2,3) and (2,3,4)):: 4 | 2-----3 / 1 If all coordinates lie in the same plane, the cis configuration corresponds to a dihedral angle of zero, and the trans configuration to :math:`\pi` radians (180 degrees). Configurations where the dihedral angle is undefined (e.g., when all coordinates lie on the same straight line) result in a value of ``nan`` (not a number) for that dihedral. If the optional argument `box` is supplied, periodic boundaries are taken into account when constructing the connecting vectors between coordinates, i.e., the minimum image convention is applied for the vectors forming the dihedral angles. Either orthogonal or triclinic boxes are supported. If a numpy array of dtype ``numpy.float64`` with shape ``(n,)`` (for ``n`` coordinate quadruplets) is provided in `result` then this preallocated array is filled. This can speed up calculations. Parameters ---------- coords1 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Coordinate array of shape ``(3,)`` or ``(n, 3)`` containing the 1st positions in dihedrals (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. coords2 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Coordinate array of shape ``(3,)`` or ``(n, 3)`` containing the 2nd positions in dihedrals (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. coords3 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Coordinate array of shape ``(3,)`` or ``(n, 3)`` containing the 3rd positions in dihedrals (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. coords4 : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Coordinate array of shape ``(3,)`` or ``(n, 3)`` containing the 4th positions in dihedrals (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. box : numpy.ndarray, optional The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. result : numpy.ndarray, optional Preallocated result array of dtype ``numpy.float64`` and shape ``(n,)`` (for ``n`` coordinate quadruplets). Avoids recreating the array in repeated function calls. backend : {'serial', 'OpenMP', 'distopia'}, optional Keyword selecting the type of acceleration. Returns ------- dihedrals : numpy.ndarray (``dtype=numpy.float64``, ``shape=(n,)``) or numpy.float64 Array containing the dihedral angles formed by each quadruplet of coordinates. Values are returned in radians (rad). If four single coordinates were supplied, the dihedral angle is returned as a single number instead of an array. The range of dihedral angle is :math:`(-\pi, \pi)`. .. versionadded:: 0.8 .. versionchanged:: 0.9.0 Added optional box argument to account for periodic boundaries in calculation .. versionchanged:: 0.11.0 Renamed from calc_torsions to calc_dihedrals .. versionchanged:: 0.13.0 Added *backend* keyword. .. versionchanged:: 0.19.0 Internal dtype conversion of input coordinates to ``numpy.float32``. Now also accepts single coordinates as input. .. versionchanged:: 2.3.0 Can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` as an argument in any position and checks inputs using type hinting. rrNrRr8rSr9r7r) rrrrrNr=rr dihedralsr\s r'calc_dihedralsrysbDmAG#FWJ77I*$$RZ00 47Objoo$$RZ000{{ ?$S>>LGS'!!)!7GWc9M# -!7GWc9M# w)D     *$$RZ00  !F111I rHc|}t|dkr|St|\}}|dkrtd||f|ntd||f||S)avMoves coordinates into the primary unit cell. Parameters ---------- coords : numpy.ndarray or :class:`~MDAnalysis.core.groups.AtomGroup` Coordinate array of shape ``(3,)`` or ``(n, 3)`` (dtype is arbitrary, will be converted to ``numpy.float32`` internally). Also accepts an :class:`~MDAnalysis.core.groups.AtomGroup`. box : numpy.ndarray The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. backend : {'serial', 'OpenMP'}, optional Keyword selecting the type of acceleration. Returns ------- newcoords : numpy.ndarray (``dtype=numpy.float32``, ``shape=coords.shape``) Array containing coordinates that all lie within the primary unit cell as defined by `box`. .. versionadded:: 0.8 .. versionchanged:: 0.13.0 Added *backend* keyword. .. versionchanged:: 0.19.0 Internal dtype conversion of input coordinates to ``numpy.float32``. Now also accepts (and, likewise, returns) single coordinates. .. versionchanged:: 2.3.0 Can now accept an :class:`~MDAnalysis.core.groups.AtomGroup` as an argument in any position and checks inputs using type hinting. rrRr:rSr;)rUr r()rrNr coords_arrayr\s r' apply_PBCrszR!'L <AS>>LGS' [ c2GDDDDD _L##6HHHH rHvectors)ra enforce_dtypect|\}}tj|}||j}|dkrt |||n#t ||||S)aApply minimum image convention to an array of vectors This function is required for calculating the correct vectors between two points. A naive approach of ``ag1.positions - ag2.positions`` will not provide the minimum vectors between particles, even if all particles are within the primary unit cell (box). Parameters ---------- vectors : numpy.ndarray Vector array of shape ``(n, 3)``, either float32 or float64. These represent many vectors (such as between two particles). box : numpy.ndarray The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. Returns ------- minimized_vectors : numpy.ndarray Same shape and dtype as input. The vectors from the input, but minimized according to the size of the box. .. versionadded:: 2.1.0 rR)r rB empty_likerVrArrravel)rrNr\outputs r'minimize_vectorsr9sv:S>>LGS ]7 # #F **W] # #C'f5555#GSYY[[&AAA MrH)NNr)NNNTr)NNN)NNTr)NNT)r)Nr)P__doc__numpyrB numpy.typingtypingnptrrrr core.groupsrutilr r mdamathr _augmentr rrwr c_distancesrr _distopiar importlibr! import_module ImportErrorstrrrr(r)r*r+r,r-r.r/r0r1r2r3r4r5r6r7r8r9r:r;c_distances_openmpr< USED_OPENMPNDArrayrGr]r`floatboolrrrmr}r~rjrrrrrrrrrrrrrHr'rs2ttj,,,,,,,,,, (''''''))))))))&&&&&&77777777MMMMMMMM######   .y., 8 292'7Jx   D 4Y4.Jz !! !!! 5/! TN! !  !!!!.,>=====, S[ !,*/,[,,,,^! "&$( ooS[+-.ok12o #+ o S[ ! o  o  [ oooodk5$OOO"&$( iiS[+-.i #+ i S[ !i i  [ iiiPOiX! #'!% '+%H H S[+-.H k12H H  H #+  H SM H tnH c]H H H H ^#'!% M%M%{M%;M%M% M% #+  M% SM M%M%M%M%M%`! #'!%'+%]]S[+-.]k12]] ] #+  ] tn ]c]]]]]@! #'!%'+%eeS[+-.ek12ee e #+  e tn ec]eeeeP! #'!%'+ llS[+-.lk12ll l #+  l tn llll^! #'!% '+%D D S[+-.D D D  #+  D SM D tn D c]D D D D T#'!% B!B!{B!B!B! #+  B! SM B!B!B!B!J! #'!%'+% VVS[+-.VVV #+  V tn V c] VVV  Vr! #'!%'+% [[S[+-.[[[ #+  [ tn [ c] [[[  [|! #'!%'+ ddS[+-.ddd #+  d tn ddd  dNh....bh((((ViD999"&$( mm 3; + ,m 3; + ,m #+ m S[ ! m  m  [ mmm:9m`iItDDD "&$( ww 3; + ,w 3; + ,w3; + ,w #+  w S[ ! w  w [wwwEDwtiIy$OOO "&$(FF 3; + ,F 3; + ,F3; + ,F3; + , F #+  F S[ ! FF [FFFPOFRh---"&22 #+{* +2 #+ 22 [ 222.-2jie5AAA'ck' ' '''BA'''s+BB B