iFdZddlZddlZddlmZmZddlmZddlm Z ddl m Z ddl Z ej d Z ejed d d d ejeddd d [GddeZdS)a Mean Squared Displacement --- :mod:`MDAnalysis.analysis.msd` ============================================================== :Authors: Hugo MacDermott-Opeskin :Year: 2020 :Copyright: Lesser GNU Public License v2.1+ This module implements the calculation of Mean Squared Displacements (MSDs) by the Einstein relation. MSDs can be used to characterize the speed at which particles move and has its roots in the study of Brownian motion. For a full explanation of the theory behind MSDs and the subsequent calculation of self-diffusivities the reader is directed to :footcite:p:`Maginn2019`. MSDs can be computed from the following expression, known as the **Einstein formula**: .. math:: MSD(r_{d}) = \bigg{\langle} \frac{1}{N} \sum_{i=1}^{N} |r_{d} - r_{d}(t_0)|^2 \bigg{\rangle}_{t_{0}} where :math:`N` is the number of equivalent particles the MSD is calculated over, :math:`r` are their coordinates and :math:`d` the desired dimensionality of the MSD. Note that while the definition of the MSD is universal, there are many practical considerations to computing the MSD that vary between implementations. In this module, we compute a "windowed" MSD, where the MSD is averaged over all possible lag-times :math:`\tau \le \tau_{max}`, where :math:`\tau_{max}` is the length of the trajectory, thereby maximizing the number of samples. The computation of the MSD in this way can be computationally intensive due to its :math:`N^2` scaling with respect to :math:`\tau_{max}`. An algorithm to compute the MSD with :math:`N log(N)` scaling based on a Fast Fourier Transform is known and can be accessed by setting ``fft=True`` [Calandri2011]_ [Buyl2018]_. The FFT-based approach requires that the `tidynamics `_ package is installed; otherwise the code will raise an :exc:`ImportError`. Please cite [Calandri2011]_ [Buyl2018]_ if you use this module in addition to the normal MDAnalysis citations. .. warning:: To correctly compute the MSD using this analysis module, you must supply coordinates in the **unwrapped** convention, also known as **no-jump**. That is, when atoms pass the periodic boundary, they must not be wrapped back into the primary simulation cell. In MDAnalysis you can use the :class:`~MDAnalysis.transformations.nojump.NoJump` transformation. In GROMACS, for example, this can be done using `gmx trjconv`_ with the ``-pbc nojump`` flag. .. _`gmx trjconv`: https://manual.gromacs.org/current/onlinehelp/gmx-trjconv.html .. SeeAlso:: :mod:`MDAnalysis.transformations.nojump` Computing an MSD ---------------- This example computes a 3D MSD for the movement of 100 particles undergoing a random walk. Files provided as part of the MDAnalysis test suite are used (in the variables :data:`~MDAnalysis.tests.datafiles.RANDOM_WALK` and :data:`~MDAnalysis.tests.datafiles.RANDOM_WALK_TOPO`) First load all modules and test data .. code-block:: python import MDAnalysis as mda import MDAnalysis.analysis.msd as msd from MDAnalysis.tests.datafiles import RANDOM_WALK_TOPO, RANDOM_WALK Given a universe containing trajectory data we can extract the MSD analysis by using the class :class:`EinsteinMSD` .. code-block:: python u = mda.Universe(RANDOM_WALK_TOPO, RANDOM_WALK) MSD = msd.EinsteinMSD(u, select='all', msd_type='xyz', fft=True) MSD.run() The MSD can then be accessed as .. code-block:: python msd = MSD.results.timeseries lagtimes = MSD.results.delta_t_values Visual inspection of the MSD is important, so let's take a look at it with a simple plot. .. code-block:: python import matplotlib.pyplot as plt nframes = MSD.n_frames fig = plt.figure() ax = plt.axes() # plot the actual MSD ax.plot(lagtimes, msd, lc="black", ls="-", label=r'3D random walk') exact = lagtimes*6 # plot the exact result ax.plot(lagtimes, exact, lc="black", ls="--", label=r'$y=2 D\tau$') plt.show() This gives us the plot of the MSD with respect to lag-time (:math:`\tau`). We can see that the MSD is approximately linear with respect to :math:`\tau`. This is a numerical example of a known theoretical result that the MSD of a random walk is linear with respect to lag-time, with a slope of :math:`2d`. In this expression :math:`d` is the dimensionality of the MSD. For our 3D MSD, this is 3. For comparison we have plotted the line :math:`y=6\tau` to which an ensemble of 3D random walks should converge. .. _figure-msd: .. figure:: /images/msd_demo_plot.png :scale: 100 % :alt: MSD plot Note that a segment of the MSD is required to be linear to accurately determine self-diffusivity. This linear segment represents the so called "middle" of the MSD plot, where ballistic trajectories at short time-lags are excluded along with poorly averaged data at long time-lags. We can select the "middle" of the MSD by indexing the MSD and the time-lags. Appropriately linear segments of the MSD can be confirmed with a log-log plot as is often reccomended :footcite:p:`Maginn2019` where the "middle" segment can be identified as having a slope of 1. .. code-block:: python plt.loglog(lagtimes, msd) plt.show() Now that we have identified what segment of our MSD to analyse, let's compute a self-diffusivity. Computing Self-Diffusivity -------------------------------- Self-diffusivity is closely related to the MSD. .. math:: D_d = \frac{1}{2d} \lim_{t \to \infty} \frac{d}{dt} MSD(r_{d}) From the MSD, self-diffusivities :math:`D` with the desired dimensionality :math:`d` can be computed by fitting the MSD with respect to the lag-time to a linear model. An example of this is shown below, using the MSD computed in the example above. The segment between :math:`\tau = 20` and :math:`\tau = 60` is used to demonstrate selection of a MSD segment. .. code-block:: python from scipy.stats import linregress start_time = 20 start_index = int(start_time/timestep) end_time = 60 linear_model = linregress(lagtimes[start_index:end_index], msd[start_index:end_index]) slope = linear_model.slope error = linear_model.stderr # dim_fac is 3 as we computed a 3D msd with 'xyz' D = slope * 1/(2*MSD.dim_fac) We have now computed a self-diffusivity! Combining Multiple Replicates -------------------------------- It is common practice to combine replicates when calculating MSDs. An example of this is shown below using MSD1 and MSD2. .. code-block:: python u1 = mda.Universe(RANDOM_WALK_TOPO, RANDOM_WALK) MSD1 = msd.EinsteinMSD(u1, select='all', msd_type='xyz', fft=True) MSD1.run() u2 = mda.Universe(RANDOM_WALK_TOPO, RANDOM_WALK) MSD2 = msd.EinsteinMSD(u2, select='all', msd_type='xyz', fft=True) MSD2.run() combined_msds = np.concatenate((MSD1.results.msds_by_particle, MSD2.results.msds_by_particle), axis=1) average_msd = np.mean(combined_msds, axis=1) The same cannot be achieved by concatenating the replicas in a single run as the jump between the last frame of the first trajectory and frame 0 of the next trajectory will lead to an artificial inflation of the MSD and hence any subsequent diffusion coefficient calculated. Notes _____ There are several factors that must be taken into account when setting up and processing trajectories for computation of self-diffusivities. These include specific instructions around simulation settings, using unwrapped trajectories and maintaining a relatively small elapsed time between saved frames. Additionally, corrections for finite size effects are sometimes employed along with various means of estimating errors :footcite:p:`Yeh2004,Bulow2020` The reader is directed to the following review, which describes many of the common pitfalls :footcite:p:`Maginn2019`. There are other ways to compute self-diffusivity, such as from a Green-Kubo integral. At this point in time, these methods are beyond the scope of this module. Note also that computation of MSDs is highly memory intensive. If this is proving a problem, judicious use of the ``start``, ``stop``, ``step`` keywords to control which frames are incorporated may be required. References ---------- .. footbibliography:: Classes ------- .. autoclass:: EinsteinMSD :members: :inherited-members: N)dueDoi) AnalysisBase)groups)tqdmzMDAnalysis.analysis.msdz10.21105/joss.00877z*Mean Squared Displacements with tidynamicsT) descriptionpath cite_modulez10.1051/sfn/201112010zFCA fast correlation algorithmcVeZdZdZ dfd ZdZdZd Zd Zd Z d Z d Z xZ S) EinsteinMSDuxClass to calculate Mean Squared Displacement by the Einstein relation. Parameters ---------- u : Universe or AtomGroup An MDAnalysis :class:`Universe` or :class:`AtomGroup`. Note that :class:`UpdatingAtomGroup` instances are not accepted. select : str A selection string. Defaults to "all" in which case all atoms are selected. msd_type : {'xyz', 'xy', 'yz', 'xz', 'x', 'y', 'z'} Desired dimensions to be included in the MSD. Defaults to 'xyz'. fft : bool If ``True``, uses a fast FFT based algorithm for computation of the MSD. Otherwise, use the simple "windowed" algorithm. The tidynamics package is required for `fft=True`. Defaults to ``True``. non_linear : bool If ``True``, calculates MSD for trajectory where frames are non-linearly dumped. To use this set `fft=False`. Defaults to ``False``. .. versionadded:: 2.10.0 Attributes ---------- dim_fac : int Dimensionality :math:`d` of the MSD. results.timeseries : :class:`numpy.ndarray` The averaged MSD over all the particles with respect to constant lag-time or unique Δt intervals. results.msds_by_particle : :class:`numpy.ndarray` The MSD of each individual particle with respect to constant lag-time or unique Δt intervals. - for `non_linear=False`: a 2D array of shape (n_lagtimes, n_atoms) - for `non_linear=True`: a 2D array of shape (n_delta_t_values, n_atoms) results.delta_t_values : :class:`numpy.ndarray` Array of unique Δt (time differences) at which time-averaged MSD values are computed. .. versionadded:: 2.10.0 ag : :class:`AtomGroup` The :class:`AtomGroup` resulting from your selection n_frames : int Number of frames included in the analysis. n_particles : int Number of particles MSD was calculated over. .. versionadded:: 2.0.0 .. versionchanged:: 2.10.0 Added ability to calculate MSD from samples that are not linearly spaced with the new `non_linear` keyword argument. allxyzTFc t|tjrtdt t |j|jjfi|||_ ||_ | ||_ ||_ ||j |_t!|j|_d|_d|j_d|j_d|j_dS)Nz4UpdatingAtomGroups are not valid for MSD computation) isinstancerUpdatingAtomGroup TypeErrorsuperr__init__universe trajectoryselectmsd_type_parse_msd_typefft non_linear select_atomsaglen n_particles_position_arrayresultsmsds_by_particle timeseriesdelta_t_values)selfurrrrkwargs __class__s a/srv/www/vhosts/g4struct/public_html/venv/lib/python3.11/site-packages/MDAnalysis/analysis/msd.pyrzEinsteinMSD.__init__Js a1 2 2 F  *k4  )!**?JJ6JJJ    $..--tw<<#)- %"& &* ###ctj|j|jf|j_tj|j|j|jf|_dSN)npzerosn_framesr!r#r$dim_facr"r's r+_preparezEinsteinMSD._prepareksT)+ ]D, -) )  % "x ]D,dl ;  r,c0dgdgdgddgddgddggdd}|j|_ ||j|_n5#t$r(t d|jwxYwt |j|_dS)z.Sets up the desired dimensionality of the MSD.rrr)rrr)xyzxyxzyzrzNinvalid msd_type: {} specified, please specify one of xyz, xy, xz, yz, x, y, zN)rlower_dimKeyError ValueErrorformatr r2)r'keyss r+rzEinsteinMSD._parse_msd_typevsa&a&a&99   ++--  T]+DII   &&,fT]&;&;   49~~ s A2A:cV|jjdd|jf|j|j<dS)z2Constructs array of positions for MSD calculation.N)r positionsr=r" _frame_indexr3s r+ _single_framezEinsteinMSD._single_frames137'2C AAtyL3 T.///r,c|jr|dS|jr|dS|dSr.)r_conclude_non_linearr _conclude_fft_conclude_simpler3s r+ _concludezEinsteinMSD._concludes^ ? (  % % ' ' ' ' 'x (""$$$$$%%'''''r,c^tjd|j}|jtj}t |D]u}|d| ddddf||dddddfz }tj|d}tj |d|j j |ddf<v|j j d|j _ tj|j|j d|j dz z|j _dS)z7Calculates the MSD via the simple "windowed" algorithm.rNaxisr)r/aranger1r"astypefloat64r squaresummeanr#r$r%timesr&)r'lagtimesrClagdispsqdists r+rIzEinsteinMSD._conclude_simples9Q ..(// ;; >> L LCUsdUAAAqqq[)IcddAAAqqqj,AADYt__((b(11F46GF4K4K4KDL )#qqq& 1 1"&,"?"D"D!"D"L"L &(i &>&> JqMDJqM )'  ###r,c ddl}n#t$rtdwxYw|jtj}t t|jD]5}| |dd|ddf|j j dd|f<6|j j d|j _ t j|j|jd|jdz z|j _dS)z:Calculates the MSD via the FCA fast correlation algorithm.rNzERROR --- tidynamics was not found! tidynamics is required to compute an FFT based MSD (default) try installing it using pip eg: pip install tidynamics or set fft=FalserrM) tidynamics ImportErrorr"rPr/rQr ranger!msdr#r$rTr%rOr1rUr&)r'r[rCns r+rHzEinsteinMSD._conclude_ffts         $    (// ;; eD,--..  A2<..!!!Q'"33DL )!!!Q$ / /#',"?"D"D!"D"L"L &(i &>&> JqMDJqM )'  ###s!cF|j}|j}|jtj}t jtt jt}t|D]}t|dz|D]}|j ||j |z }||||z }t j |dzd} t j | } | | || | dgd<t j|g|d<t} fd| D} t jt#| |f} t%| D]<\}}t j||}t j |d| |ddf<=t j| |j_t j| |j_| |j_dS)NrrrMrgcDg|]}tj|S)r/rT).0dtmsd_dicts r+ z4EinsteinMSD._conclude_non_linear..s'CCCbBGHRL))CCCr,)r1r!r"rPr/rQ collections defaultdictlistr]rUrSrTappendr0sortedrAr enumeratevstackarrayr#r%r&r$)r'r1n_atomsrCmsds_by_particle_dictijdelta_trX squared_dispr^r&avg_msdsmsds_by_particle_arrayidxrdarrres @r+rGz EinsteinMSD._conclude_non_linears="(// ;; *400 + 7 = =x D DA1q5(++ D D*Q-$*Q-7 |il2!vdAgA666 gl++!((---%g.55lCCCC Dc &(hw&7&7%8c"  00CCCCNCCC!#3~+>+>*H!I!I 00 B BGC)1"566C-/WSq-A-A-A "36 * *"$(8"4"4 &(h~&>&> #(> %%%r,)rrTF) __name__ __module__ __qualname____doc__rr4rrErJrIrHrG __classcell__)r*s@r+rrs77x  ++++++B   &&&0   (((       6$?$?$?$?$?$?$?r,r)r|numpyr/loggingrrbasercorerr rg getLoggerloggerciterrbr,r+rs?0]]~  4 5 5C< "   C  0 "  [?[?[?[?[?,[?[?[?[?[?r,