imtdZddlZddlZddlmZddlmZmZdZ Gdd eZ Gd d eZ dS) aRadial Distribution Functions --- :mod:`MDAnalysis.analysis.rdf` ==================================================================== This module contains two classes to calculate radial `pair distribution functions`_ (`radial distribution functions`_ or "RDF"). The RDF :math:`g_{ab}(r)` between types of particles :math:`a` and :math:`b` is .. _equation-gab: .. math:: g_{ab}(r) = \frac{1}{N_{a}} \frac{1}{N_{b}/V} \sum_{i=1}^{N_a} \sum_{j=1}^{N_b} \langle \delta(|\mathbf{r}_i - \mathbf{r}_j| - r) \rangle which is normalized so that the RDF becomes 1 for large separations in a homogenous system. The RDF effectively counts the average number of :math:`b` neighbours in a shell at distance :math:`r` around a :math:`a` particle and represents it as a density. The radial cumulative distribution function is .. math:: G_{ab}(r) = \int_0^r \!\!dr' 4\pi r'^2 g_{ab}(r') and the average number of :math:`b` particles within radius :math:`r` .. _equation-countab: .. math:: N_{ab}(r) = \rho G_{ab}(r) (with the appropriate density :math:`\rho`). The latter function can be used to compute, for instance, coordination numbers such as the number of neighbors in the first solvation shell :math:`N(r_1)` where :math:`r_1` is the position of the first minimum in :math:`g(r)`. We provide options for calculating the density of particle :math:`b` in a shell at distance :math:`r` around a :math:`a` particle, which is .. _equation-nab: .. math:: n_{ab}(r) = \rho g_{ab}(r) .. _`pair distribution functions`: https://en.wikipedia.org/wiki/Pair_distribution_function .. _`radial distribution functions`: https://en.wikipedia.org/wiki/Radial_distribution_function .. Not Implemented yet: .. - Structure factor? .. - Coordination number N) distances) AnalysisBase ResultsGroupc>fd|}tj|dtj|dg}tt|dzD]7}|dxx|d|zz cc<|dxx|d|zdzz cc<8|S)aCustom aggregator for nested arrays This function takes a nested list or tuple of NumPy arrays, flattens it into a single list, and aggregates the elements at alternating indices into two separate arrays. The first array accumulates elements at even indices, while the second accumulates elements at odd indices. Parameters ---------- arrs : list List of arrays or nested lists of arrays Returns ------- list of ndarray A list containing two NumPy arrays: - The first array is the sum of all elements at even indices in the sum of flattened arrays. - The second array is the sum of all elements at odd indices in the sum of flattened arrays. c^t|ttfrfd|DS|gS)Nc0g|]}|D]}|Sr ).0sublistitemflattens a/srv/www/vhosts/g4struct/public_html/venv/lib/python3.11/site-packages/MDAnalysis/analysis/rdf.py z5nested_array_sum..flatten..os0IIIW8H8HIIDIIII) isinstancelisttuple)arrrs rrz!nested_array_sum..flattenms; cD%= ) ) JIIIIIII Iu rrrr)np zeros_likerangelen)arrsflataggregated_arrirs @rnested_array_sumrVs. 74==DmDG,,bmDG.D.DEN 3t99> " "--qT!a%[(qT!a%!)_, rceZdZdZedZdZ dfd Zd Zd Z d Z d Z e dZ e dZe dZe dZxZS)InterRDFaRadial distribution function :class:`InterRDF` is a tool to calculate average radial distribution functions between two groups of atoms. Suppose we have two AtomGroups ``A`` and ``B``. ``A`` contains atom ``A1``, ``A2``, and ``B`` contains ``B1``, ``B2``. Given ``A`` and ``B`` to :class:`InterRDF`, the output will be the average of RDFs between ``A1`` and ``B1``, ``A1`` and ``B2``, ``A2`` and ``B1``, ``A2`` and ``B2``. A typical application is to calculate the RDF of solvent with itself or with another solute. The :ref:`radial distribution function` is calculated by histogramming distances between all particles in `g1` and `g2` while taking periodic boundary conditions into account via the minimum image convention. The `exclusion_block` keyword may be used to exclude a set of distances from the calculations. Results are available in the attributes :attr:`results.rdf` and :attr:`results.count`. Parameters ---------- g1 : AtomGroup First AtomGroup g2 : AtomGroup Second AtomGroup nbins : int Number of bins in the histogram range : tuple or list The size of the RDF norm : str, {'rdf', 'density', 'none'} For 'rdf' calculate :math:`g_{ab}(r)`. For 'density' the :ref:`single particle density` :math:`n_{ab}(r)` is computed. 'none' computes the number of particles occurences in each spherical shell. .. versionadded:: 2.3.0 exclusion_block : tuple A tuple representing the tile to exclude from the distance array. exclude_same : str Will exclude pairs of atoms that share the same "residue", "segment", or "chain". Those are the only valid values. This is intended to remove atoms that are spatially correlated due to direct bonded connections. verbose : bool Show detailed progress of the calculation if set to `True` backend : {'serial', 'OpenMP', 'distopia'}, optional Keyword selecting the type of acceleration of the distance calculations. Default is 'serial'. .. versionadded:: 2.10.0 Attributes ---------- results.bins : numpy.ndarray :class:`numpy.ndarray` of the centers of the `nbins` histogram bins. .. versionadded:: 2.0.0 bins : numpy.ndarray Alias to the :attr:`results.bins` attribute. .. deprecated:: 2.0.0 This attribute will be removed in 3.0.0. Use :attr:`results.bins` instead. results.edges : numpy.ndarray :class:`numpy.ndarray` of the `nbins + 1` edges of the histogram bins. .. versionadded:: 2.0.0 edges : numpy.ndarray Alias to the :attr:`results.edges` attribute. .. deprecated:: 2.0.0 This attribute will be removed in 3.0.0. Use :attr:`results.edges` instead. results.rdf : numpy.ndarray :class:`numpy.ndarray` of the :ref:`radial distribution function` values for the :attr:`results.bins`. .. versionadded:: 2.0.0 rdf : numpy.ndarray Alias to the :attr:`results.rdf` attribute. .. deprecated:: 2.0.0 This attribute will be removed in 3.0.0. Use :attr:`results.rdf` instead. results.count : numpy.ndarray :class:`numpy.ndarray` representing the radial histogram, i.e., the raw counts, for all :attr:`results.bins`. .. versionadded:: 2.0.0 count : numpy.ndarray Alias to the :attr:`results.count` attribute. .. deprecated:: 2.0.0 This attribute will be removed in 3.0.0. Use :attr:`results.count` instead. Example ------- First create the :class:`InterRDF` object, by supplying two AtomGroups then use the :meth:`run` method :: rdf = InterRDF(ag1, ag2) rdf.run() Results are available through the :attr:`results.bins` and :attr:`results.rdf` attributes:: plt.plot(rdf.results.bins, rdf.results.rdf) The `exclusion_block` keyword allows the masking of pairs from within the same molecule. For example, if there are 7 of each atom in each molecule, the exclusion mask ``(7, 7)`` can be used. .. versionadded:: 0.13.0 .. versionchanged:: 1.0.0 Support for the `start`, `stop`, and `step` keywords has been removed. These should instead be passed to :meth:`InterRDF.run`. .. versionchanged:: 2.0.0 Store results as attributes `bins`, `edges`, `rdf` and `count` of the `results` attribute of :class:`~MDAnalysis.analysis.AnalysisBase`. .. versionchanged:: 2.10.0 Enabled **parallel execution** with the ``multiprocessing`` and ``dask`` backends; use the new method :meth:`get_supported_backends` to see all supported backends. cdSN)serialmultiprocessingdaskr clss rget_supported_backendszInterRDF.get_supported_backends    rTKg.@rdfNr$c  tt|j|jjfi| ||_||_t||_ ||d|_ ||_ ||dvrtd||tddddd} | ||_|j dvrtd |j d ||_dS) Nbinsr)residuesegmentchainzTThe exclude_same argument to InterRDF must be None, 'residue', 'segment' or 'chain'.zJThe exclude_same argument to InterRDF cannot be used with exclusion_block. resindices segindiceschainIDsr.densitynone'5' is an invalid norm. Use 'rdf', 'density' or 'none'.)superr!__init__universe trajectoryg1g2strlowernorm rdf_settings_exclusion_block ValueErrorget exclude_samebackend) selfrArBnbinsrrEexclusion_blockrJrKkwargs name_to_attr __class__s rr>zInterRDF.__init__s2 'h&r{'=HHHHHIIOO%% %*U;; /  # = ) )    #(C\ $#  ),,\:: 96 6 62DI222   rcVtjdgfi|j\}}|tj}|dz}||j_||j_d|dd|ddzz|j_|j dkr d|j_ |jdd|_ dS)Nr-?rr.rr) r histogramrFastypefloat64resultscountedgesr1rE volume_cum _maxrange)rLrYrZs r_preparezInterRDF._prepareDs|RD>>D,=>> u RZ((  " " 5":abb #9:  9  &'DL #*73A6rctj|jj|jj|j|jj|j\}}|j Z|dddf|j dz}|dddf|j dz}tj ||kd}||}|j zt|j|j |dddf}t|j|j |dddf}tj ||kd}||}tj|fi|j\}} |jxj|z c_|jdkr!|jxj|jjz c_dSdS)NboxrKrrr.)rcapped_distancerA positionsrBr\_ts dimensionsrKrGrwhererJgetattrrUrFrXrYrEr[volume) rLpairsdistidxAidxBmask attr_ix_a attr_ix_brY_s r _single_framezInterRDF._single_frameSs/ G  G  N#L    t  ,A;$"7"::DA;$"7"::D8DDL))!,D:D   ():;;E!!!Q$KHI):;;E!!!Q$KHI8I233A6D:D<::(9::q e# 9   L # #tx 6 # # # #  rc|ttjtjtjtjdSN)rYr[r1rZ)lookup)r ndarray_sum ndarray_meanrLs r_get_aggregatorzInterRDF._get_aggregatoros;%1*6$0%2     rc|j}|jdvrFtj|jjd}|dtjztj|zz}|jdkrvt|j }t|j }||z}|j r|j \}}||z }|||z|zz}|jj |_ |j |jz } ||| z z}|jj |z |j_dS)Nr.r9UUUUUU?r.)n_framesrErpowerrXrZpidiffrrArBrGr[rYr.) rLrEvolsnAnBNxAxBnblocksbox_vols r _concludezInterRDF._concludeys} 9* * *8DL.22D EBEMBGDMM1 1D 9  TWBTWBRA$ '.Br'R"Ww&&#l5DOo 5G AK D<-4 rcRd}tj|t|jjSNzThe `edges` attribute was deprecated in MDAnalysis 2.0.0 and will be removed in MDAnalysis 3.0.0. Please use `results.bins` insteadwarningswarnDeprecationWarningrXrZrLwmsgs rrZzInterRDF.edges, %  d.///|!!rcRd}tj|t|jjSNzThe `count` attribute was deprecated in MDAnalysis 2.0.0 and will be removed in MDAnalysis 3.0.0. Please use `results.bins` insteadrrrrXrYrs rrYzInterRDF.countrrcRd}tj|t|jjSNzThe `bins` attribute was deprecated in MDAnalysis 2.0.0 and will be removed in MDAnalysis 3.0.0. Please use `results.bins` insteadrrrrXr1rs rr1z InterRDF.bins, %  d.///|  rcRd}tj|t|jjSNzThe `rdf` attribute was deprecated in MDAnalysis 2.0.0 and will be removed in MDAnalysis 3.0.0. Please use `results.rdf` insteadrrrrXr.rs rr.z InterRDF.rdf, $  d.///|r)r+r,r.NNr$)__name__ __module__ __qualname____doc__ classmethodr)%_analysis_algorithm_is_parallelizabler>r]rprwrpropertyrZrYr1r. __classcell__rQs@rr!r!zs*NN`  [ -1)  ------^ 7 7 77778   5554""X"""X"!!X!  X     rr!ceZdZdZedZdZdZ dfd Zd Z d Z d Z dZ e dZe dZe dZe dZe dZxZS) InterRDF_saSite-specific radial distribution function Calculates site-specific radial distribution functions. Instead of two groups of atoms it takes as input a list of pairs of AtomGroup, ``[[A, B], [C, D], ...]``. Given the same ``A`` and ``B`` to :class:`InterRDF_s`, the output will be a list of individual RDFs between ``A1`` and ``B1``, ``A1`` and ``B2``, ``A2`` and ``B1``, ``A2`` and ``B2`` (and similarly for ``C`` and ``D``). These site-specific radial distribution functions are typically calculated if one is interested in the solvation shells of a ligand in a binding site or the solvation of specific residues in a protein. Parameters ---------- u : Universe a Universe that contains atoms in `ags` .. deprecated:: 2.3.0 This parameter is superflous and will be removed in MDAnalysis 3.0.0. ags : list a list of pairs of :class:`~MDAnalysis.core.groups.AtomGroup` instances nbins : int Number of bins in the histogram range : tuple or list The size of the RDF norm : str, {'rdf', 'density', 'none'} For 'rdf' calculate :math:`g_{ab}(r)`. For 'density' the :ref:`single particle density` :math:`n_{ab}(r)` is computed. 'none' computes the number of particles occurences in each spherical shell. .. versionadded:: 2.3.0 density : bool `False`: calculate :math:`g_{ab}(r)`; `True`: calculate the true :ref:`single particle density` :math:`n_{ab}(r)`. `density` overwrites the `norm` parameter. .. versionadded:: 1.0.1 This keyword was available since 0.19.0 but was not documented. Furthermore, it had the opposite meaning. Since 1.0.1 it is officially supported as documented. .. deprecated:: 2.3.0 Instead of `density=True` use `norm='density'` backend : {'serial', 'OpenMP', 'distopia'}, optional Keyword selecting the type of acceleration of the distance calculations. Default is 'serial'. .. versionadded:: 2.10.0 Attributes ---------- results.bins : numpy.ndarray :class:`numpy.ndarray` of the centers of the `nbins` histogram bins; all individual site-specific RDFs have the same bins. .. versionadded:: 2.0.0 bins : numpy.ndarray Alias to the :attr:`results.bins` attribute. .. deprecated:: 2.0.0 This attribute will be removed in 3.0.0. Use :attr:`results.bins` instead. results.edges : numpy.ndarray array of the ``nbins + 1`` edges of the histogram bins; all individual site-specific RDFs have the same bins. .. versionadded:: 2.0.0 edges : numpy.ndarray Alias to the :attr:`results.edges` attribute. .. deprecated:: 2.0.0 This attribute will be removed in 3.0.0. Use :attr:`results.edges` instead. results.rdf : list :class:`list` of the site-specific :ref:`radial distribution functions` if `norm='rdf'` or :ref:`density functions` for the :attr:`bins` if `norm='density'`. The list contains ``len(ags)`` entries. Each entry for the ``i``-th pair `[A, B] = ags[i]` in `ags` is a :class:`numpy.ndarray` with shape ``(len(A), len(B))``, i.e., a stack of RDFs. For example, ``results.rdf[i][0, 2]`` is the RDF between atoms ``A[0]`` and ``B[2]``. .. versionadded:: 2.0.0 rdf : list Alias to the :attr:`results.rdf` attribute. .. deprecated:: 2.0.0 This attribute will be removed in 3.0.0. Use :attr:`results.rdf` instead. results.count : list :class:`list` of the site-specific radial histograms, i.e., the raw counts, for all :attr:`results.bins`. The data have the same structure as :attr:`results.rdf` except that the arrays contain the raw counts. .. versionadded:: 2.0.0 count : list Alias to the :attr:`results.count` attribute. .. deprecated:: 2.0.0 This attribute will be removed in 3.0.0. Use :attr:`results.count` instead. results.cdf : list :class:`list` of the site-specific :ref:`cumulative counts`, for all :attr:`results.bins`. The data have the same structure as :attr:`results.rdf` except that the arrays contain the cumulative counts. This attribute only exists after :meth:`get_cdf` has been run. .. versionadded:: 2.0.0 cdf : list Alias to the :attr:`results.cdf` attribute. .. deprecated:: 2.0.0 This attribute will be removed in 3.0.0. Use :attr:`results.cdf` instead. Example ------- First create the :class:`InterRDF_s` object, by supplying one Universe and one list of pairs of AtomGroups, then use the :meth:`~InterRDF_s.run` method:: from MDAnalysisTests.datafiles import GRO_MEMPROT, XTC_MEMPROT u = mda.Universe(GRO_MEMPROT, XTC_MEMPROT) s1 = u.select_atoms('name ZND and resid 289') s2 = u.select_atoms('(name OD1 or name OD2) and resid 51 and sphzone 5.0 (resid 289)') s3 = u.select_atoms('name ZND and (resid 291 or resid 292)') s4 = u.select_atoms('(name OD1 or name OD2) and sphzone 5.0 (resid 291)') ags = [[s1, s2], [s3, s4]] rdf = InterRDF_s(u, ags) rdf.run() Results are available through the :attr:`results.bins` and :attr:`results.rdf` attributes:: plt.plot(rdf.results.bins, rdf.results.rdf[0][0, 0]) (Which plots the rdf between the first atom in ``s1`` and the first atom in ``s2``) To generate the *cumulative distribution function* (cdf) in the sense of "particles within radius :math:`r`", i.e., :math:`N_{ab}(r)`, use the :meth:`~InterRDF_s.get_cdf` method :: cdf = rdf.get_cdf() Results are available through the :attr:`results.cdf` attribute:: plt.plot(rdf.results.bins, rdf.results.cdf[0][0, 0]) (Which plots the cdf between the first atom in ``s1`` and the first atom in ``s2``) .. versionadded:: 0.19.0 .. versionchanged:: 1.0.0 Support for the `start`, `stop`, and `step` keywords has been removed. These should instead be passed to :meth:`InterRDF_s.run`. .. versionchanged:: 2.0.0 Store results as attributes `bins`, `edges`, `rdf`, `count` and `cdf` of the `results` attribute of :class:`~MDAnalysis.analysis.AnalysisBase`. .. versionchanged:: 2.3.0 Introduce `norm` and `exclusion_blocks` attributes. .. deprecated:: 2.3.0 Instead of `density=True` use `norm='density'` .. deprecated:: 2.3.0 The `universe` parameter is superflous. .. versionchanged:: 2.10.0 Enabled **parallel execution** with the ``multiprocessing`` and ``dask`` backends; use the new method :meth:`get_supported_backends` to see all supported backends. cdSr#r r's rr)z!InterRDF_s.get_supported_backendsr*rTcrtttjtjtjdSrr)rrrtrurvs rrwzInterRDF_s._get_aggregators8)*6$1%2     rr+r,r.Fr$c tt|j|ddjjfi|t jdt||_t| |_ ||d|_ |j dvrtd|j d|r!t jdtd|_ ||_dS) NrzHThe `u` attribute is superflous and will be removed in MDAnalysis 3.0.0.r0r8r;r<zThe `density` attribute was deprecated in MDAnalysis 2.3.0 and will be removed in MDAnalysis 3.0.0. Please use `norm=density` instead.r9)r=rr>r?r@rrragsrCrDrErFrHrK) rLurrMrrEr9rKrOrQs rr>zInterRDF_s.__init__s )j$( F1I  )  -3      #    IIOO%% %*U;; 96 6 62DI222   " M#    "DI rc2tjdgfi|j\}fd|jD|j_||j_d|dd|ddzz|j_|jdkr d|j_ |jdd|_ dS)NrSc g|]?\}}tj|j|jtftj@S))dtype)rzerosn_atomsrrW)r ag1ag2rYs rrz'InterRDF_s._prepare..sO   S Hck3;E ;2: N N N   rrTrr.rr) rrUrFrrXrYrZr1rEr[r\)rLrZrYs @rr]zInterRDF_s._prepares|RD>>D,=>> u     H    # 5":abb #9:  9  &'DL #*73A6rcnt|jD]\}\}}tj|j|j|j|jj|j\}}|j d}|j d\}}||z |z||z z } | tj } | dk| |kz} | tj } |dddf} |dddf} |j j|| | | fxx| z cc<|jdkr!|j xj|jjz c_dSdS)Nr_r1rrrr.) enumeraterrrarbr\rcrdrKrFrVrint64rXrYrEr[rg) rLrrrrhrirMrminrmax bin_indicescountsidx1sidx2ss rrpzInterRDF_s._single_framesV&tx00 G GMAzS#3  H' KE4%f-E*73JD$$;%/4$;?K%,,RX66K!Q&;+>?F]]28,,F!!!Q$KE!!!Q$KE L q !% "; < < < F < < < < 9   L # #tx 6 # # # #  rc8|j}|jdvrFtj|jjd}|dtjztj|zz}|jdkr&|jj|_|d|j|jz z z}g|j_ g|j_ t|j D]e\}\}}|jj |j |j g|jj |jj||z fdS)Nryrzr{r.r)r|rErr}rXrZr~rr[indicesr.rrappendrY)rLrErrrrs rrzInterRDF_s._concludes } 9* * *8DL.22D EBEMBGDMM1 1D 9  "l5DO A4=89 9D "  &tx00 B BMAzS L ' 'ck(B C C C L  # #DL$6q$9D$@ A A A A B Brcg|j_|jjD]=}|jjt j|d|jz >|jjS)aCalculate the cumulative counts for all sites. This is the :ref:`cumulative count` within a given radius, i.e., :math:`N_{ab}(r)`. The result is returned and also stored in the attribute :attr:`results.cdf`. Returns ------- cdf : list list of arrays with the same structure as :attr:`results.rdf` r)axis)rXcdfrYrrcumsumr|)rLrYs rget_cdfzInterRDF_s.get_cdfsa \' N NE L  # #BIe!$<$<$rr)r+r,r.Fr$)rrrrrr)rrwr>r]rprrrrZrYr1r.rrrs@rrrsTHHT  [ -1)    ))))))V 7 7 77770BBB*   *""X"""X"!!X!  X   X     rr) rrnumpyrlibrbaserrrr!rr rrrs066n,,,,,,,,!!!H     |   D J J J J J J J J J J r