i9^dZddlZddlmZddlmZddlmZm Z m Z m Z ddl m Zddl mZd ejd efd Zd ejd ejd ejfdZdejdejd ejfdZdejd ejfdZdejdejd efdZd ejd ejdejd efdZdejdejdejd efdZdejd eeejffdZdejdejdejd ejfdZejfd ejd!ejd ejfd"Zd ejd efd#ZdS)$a Mathematical helper functions --- :mod:`MDAnalysis.lib.mdamath` =============================================================== Helper functions for common mathematical operations. Some of these functions are written in C/cython for higher performance. Linear algebra -------------- .. autofunction:: normal .. autofunction:: norm .. autofunction:: pdot .. autofunction:: pnorm .. autofunction:: angle .. autofunction:: dihedral .. autofunction:: stp .. autofunction:: sarrus_det .. autofunction:: triclinic_box .. autofunction:: triclinic_vectors .. autofunction:: box_volume Connectivity ------------ .. autofunction:: make_whole .. autofunction:: find_fragments .. versionadded:: 0.11.0 .. versionchanged: 1.0.0 Unused function :func:`_angle()` has now been removed. N) NoDataError)util) make_wholefind_fragments_sarrus_det_single_sarrus_det_multiple)UnionvreturncPtjtj||S)aCalculate the norm of a vector v. .. math:: v = \sqrt{\mathbf{v}\cdot\mathbf{v}} This version is faster then numpy.linalg.norm because it only works for a single vector and therefore can skip a lot of the additional fuss linalg.norm does. Parameters ---------- v : array_like 1D array of shape (N) for a vector of length N Returns ------- float norm of the vector )npsqrtdot)r s `/srv/www/vhosts/g4struct/public_html/venv/lib/python3.11/site-packages/MDAnalysis/lib/mdamath.pynormrLs( 726!Q<<  vec1vec2cdtj||}t|}|dkr|S||z S)a9Returns the unit vector normal to two vectors. .. math:: \hat{\mathbf{n}} = \frac{\mathbf{v}_1 \times \mathbf{v}_2}{|\mathbf{v}_1 \times \mathbf{v}_2|} If the two vectors are collinear, the vector :math:`\mathbf{0}` is returned. .. versionchanged:: 0.11.0 Moved into lib.mdamath )rcrossr)rrnormalns rrrcs8(4..F V ACxx A:rabc.tjd||S)aPairwise dot product. ``a`` must be the same shape as ``b``. Parameters ---------- a: :class:`numpy.ndarray` of shape (N, M) b: :class:`numpy.ndarray` of shape (N, M) Returns ------- :class:`numpy.ndarray` of shape (N,) zij,ij->i)reinsum)rrs rpdotr xs 9ZA & &&rc(t||dzS)zEuclidean norm of each vector in a matrix Parameters ---------- a: :class:`numpy.ndarray` of shape (N, M) Returns ------- :class:`numpy.ndarray` of shape (N,) g?)r )rs rpnormr"s 1:: rctj||t|t|zz }tj|dd}tj|S)a Returns the angle between two vectors in radians .. versionchanged:: 0.11.0 Moved into lib.mdamath .. versionchanged:: 1.0.0 Changed rounding-off code to use `np.clip()`. Values lower than -1.0 now return `np.pi` instead of `-np.pi` g?)rrrcliparccos)rrxs rangler(sJ q! Q$q'')*A 4A 9Q<<rvec3cRtj|tj||S)aTakes the scalar triple product of three vectors. Returns the volume *V* of the parallel epiped spanned by the three vectors .. math:: V = \mathbf{v}_3 \cdot (\mathbf{v}_1 \times \mathbf{v}_2) .. versionchanged:: 0.11.0 Moved into lib.mdamath )rrr)rrr)s rstpr+s" 6$t,, - --rabbccdctt||t||}t|||dkr|n| S)uReturns the dihedral angle in radians between vectors connecting A,B,C,D. The dihedral measures the rotation around bc:: ab A---->B \ bc _\' C---->D cd The dihedral angle is restricted to the range -π <= x <= π. .. versionadded:: 0.8 .. versionchanged:: 0.11.0 Moved into lib.mdamath r)r(rr+)r,r-r.r's rdihedralr0sC$ fRnnfRnn--ABB3&&11QB.rmatrixcl|tj}|j}|j}|dks|dddkr"t d||dkrt|St| d |ddS)aComputes the determinant of a 3x3 matrix according to the `rule of Sarrus`_. If an array of 3x3 matrices is supplied, determinants are computed per matrix and returned as an appropriately shaped numpy array. .. _rule of Sarrus: https://en.wikipedia.org/wiki/Rule_of_Sarrus Parameters ---------- matrix : numpy.ndarray An array of shape ``(..., 3, 3)`` with the 3x3 matrices residing in the last two dimensions. Returns ------- det : float or numpy.ndarray The determinant(s) of `matrix`. If ``matrix.shape == (3, 3)``, the determinant will be returned as a scalar. If ``matrix.shape == (..., 3, 3)``, the determinants will be returned as a :class:`numpy.ndarray` of shape ``(...,)`` and dtype ``numpy.float64``. Raises ------ ValueError: If `matrix` has less than two dimensions or its last two dimensions are not of shape ``(3, 3)``. .. versionadded:: 0.20.0 rNr5z >uSbSz J JJrr'yzc tj|tj}tj|tj}tj|tj}t|}t|}t|}tjd5tjtjtj||||zz }tjtjtj||||zz }tjtjtj||||zz }dddn #1swxYwYtj||||||gtj } tj | dkr|dkr|dkr|dkr| Stj dtj S)aVConvert the three triclinic box vectors to ``[lx, ly, lz, alpha, beta, gamma]``. If the resulting box is invalid, i.e., any box length is zero or negative, or any angle is outside the open interval ``(0, 180)``, a zero vector will be returned. All angles are in degrees and defined as follows: * ``alpha = angle(y,z)`` * ``beta = angle(x,z)`` * ``gamma = angle(x,y)`` Parameters ---------- x : array_like Array of shape ``(3,)`` representing the first box vector y : array_like Array of shape ``(3,)`` representing the second box vector z : array_like Array of shape ``(3,)`` representing the third box vector Returns ------- numpy.ndarray A numpy array of shape ``(6,)`` and dtype ``np.float32`` providing the unitcell dimensions in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. Invalid boxes are returned as a zero vector. Note ---- Definition of angles: http://en.wikipedia.org/wiki/Lattice_constant See Also -------- :func:`~MDAnalysis.lib.mdamath.triclinic_vectors` .. versionchanged:: 0.20.0 Calculations are performed in double precision and invalid box vectors result in an all-zero box. dtypeignore)invalidNrf@) rasarrayr8rerrstaterad2degr&rarrayfloat32allzeros) r'r@rAlxlylzalphabetagammaboxs r triclinic_boxrWs^ 1BJ'''A 1BJ'''A 1BJ'''A aB aB aB X & & &@@ 29RVAq\\R"W%=>>??z")BF1aLLBG$<==>> 29RVAq\\R"W%=>>??@@@@@@@@@@@@@@@ (BBtU32: F F FC vcCiUU]]te||  8ARZ ( ( ((s#B>E--E14E1 dimensionsrDc.tj|tj}|\}}}}}}tj|dkr|dkr |dkr|dkstjd|} n||cxkr |cxkrdkr6nn3tj|dd|d } n_tjdtj} || d <|dkrd} n&tjtj|} |dkrd} n&tjtj|} |dkrd} d } n>?? XfBJ777  4 D==IIrz%0011I 4<<HHvbj..//H D==IIIJu%%Eu Iu I > 4 > 4= 4X -A!ABYN 47 Gj&!+ +j.>!.C C  4 d c ! !#**5u*==JJ&666J rc&tj|tj}|\}}}}}}||cxkr |cxkrdkrnn|dkr|dkr|dkr ||z|z}n5t|tj} | d| dz| dz}|S)a]Return the volume of the unitcell described by `dimensions`. The volume is computed as the product of the box matrix trace, with the matrix obtained from :func:`triclinic_vectors`. If the box is invalid, i.e., any box length is zero or negative, or any angle is outside the open interval ``(0, 180)``, the resulting volume will be zero. Parameters ---------- dimensions : array_like Unitcell dimensions provided in the same format as returned by :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`: ``[lx, ly, lz, alpha, beta, gamma]``. Returns ------- volume : float The volume of the unitcell. Will be zero for invalid boxes. .. versionchanged:: 0.20.0 Calculations are performed in double precision and zero is returned for invalid dimensions. rCrZrr\r]r^)rrIr8ri) rXrcrPrQrRrSrTrUvolumetri_vecss r box_volumerms4 *Zrz 2 2 2C%("BBtU %%%%%%%%%%%%%"q&&R!VVQb2%S ;;;$(4.08D>A Mr) __doc__numpyr exceptionsrr_cutilrrr r numpy.typingtypingnptr ArrayLikefloatrNDArrayrr r"r(r+r0r?rWrM DTypeLikerirmrrr{s0##H$$$$$$  !CM!e!!!!.cm *'CK'CK'CK''''" S[ S[     S] s}     . -."}.47M. ....&//CM/s}/////,,Ks{,KuUCK-?'@,K,K,K,K^>) }>)>)+.=>)[>)>)>)>)D79jcc c&)mc[ccccL$3=$U$$$$$$r