diff --git a/Doc/index.rst b/Doc/index.rst index 3bf3e8fb0a..d6d2a2ae61 100644 --- a/Doc/index.rst +++ b/Doc/index.rst @@ -3,29 +3,28 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to MDANSE's documentation! -================================== - .. note:: This is the documentation of the MDANSE 2.0 release. The documentation, just like the code itself, is still under development. MDANSE 2 has currently (October 2024) just reached the first beta release. +Welcome to MDANSE's documentation! +================================== + **Useful links**: `MDANSE Project Website `_ | `MDANSE GitHub Page `_ -**MDANSE** (**Molecular Dynamics Analysis for Neutron Scattering Experiments**) +**MDANSE (Molecular Dynamics Analysis for Neutron Scattering Experiments)** is a Python application designed for computing neutron observables from molecular dynamics (MD) trajectories that can be directly compared with neutron scattering experiments, particularly inelastic and quasi-elastic -neutron scattering spectroscopies. - -MDANSE can analyse MD trajectories from a variety of MD simulation software such +neutron scattering spectroscopies. MDANSE can analyse MD trajectories from a +variety of MD simulation software such as CASTEP, VASP, DMOL, Gromacs, DL_POLY, CHARMM, LAMMPS, DFTB and etc., and provides both graphical user interface (GUI) and command line interfaces. -This project is built on the development published previously: \ -G. Goret, B. Aoun, E. Pellegrini, "MDANSE: An Interactive Analysis Environment for Molecular Dynamics Simulations", -J Chem Inf Model. 57(1):1-5 (2017). +The MDANSE project has been published previously in: \ +`G. Goret, B. Aoun, E. Pellegrini, "MDANSE: An Interactive Analysis Environment for Molecular Dynamics Simulations", +J. Chem. Inf. Model. 2017, 57, 1, 1–5 `_. .. raw:: html @@ -63,11 +62,11 @@ J Chem Inf Model. 57(1):1-5 (2017). pages/files pages/workflow pages/trajectory + pages/correlation pages/dynamics pages/scattering pages/structure pages/analysis - pages/correlation .. toctree:: :maxdepth: 5 @@ -75,6 +74,7 @@ J Chem Inf Model. 57(1):1-5 (2017). :caption: ⚛️ How-To Guides pages/H_start + pages/H_conv pages/H_cli pages/H_gui pages/gui diff --git a/Doc/pages/H_conv.rst b/Doc/pages/H_conv.rst new file mode 100644 index 0000000000..3c25492a02 --- /dev/null +++ b/Doc/pages/H_conv.rst @@ -0,0 +1,168 @@ +Converged Results +================= +In MD, a large number of settings must be chosen correctly to ensure that +high quality results are obtained. Some of these include the size of the MD +box, the time step and the simulation length. The choice of these settings +also depends on the type of intended analysis; for example, the dynamic +coherent structure factor is much more difficult to converge +when compared to the dynamics incoherent structure factor. In this section +we will show how the calculation results change with different MD settings +for a simple liquid argon system. + + +Simulation Box Size +~~~~~~~~~~~~~~~~~~~ + +Pair Distribution Function +-------------------------- +Here we run a liquid argon trajectory with four different simulation box +sizes: 1.146, 2.292, 4.584 and 9.168 nm. The same atom density, +temperature, time step and simulation length are used for all cases. We +calculate the pair distribution function for all trajectories. + +.. _figure-pdf: + +.. figure:: ./Pictures/argon_pdf.png + :align: center + :width: 11.748cm + :height: 9.393cm + + PDF calculated for a 120 ps MD simulation of liquid argon with a + number of different MD box sizes. Blue, orange, green and red plots + correspond to MD box sizes of 1.146, 2.292, 4.584 and 9.168 nm + respectively. + +In :numref:`figure-pdf` we show the results for the PDF plotted to half +the box size. Our smallest box size 1.146 nm (blue in :numref:`figure-pdf`) +is small enough for the periodic image of the argon atoms to have a +significant effect on itself. Compared to our largest system size, the +first peak is shifted to a slightly longer distance, is too high and too broad. + + +Simulation Length +~~~~~~~~~~~~~~~~~ + +Dynamic Coherent Structure Factor +--------------------------------- +For analysis types which calculate a correlation function, +a balance between the length of your correlation function and the number of +configurations that you average over for each time step must be reached. +Here we run dynamic coherent structure factor calculations using +the liquid argon trajectory with the 4.584 nm box size, ideal +instrument resolution and two different correlation frames settings. + +.. _figure-coh-fqt: + +.. figure:: ./Pictures/fqt_conv.png + :align: center + :width: 11.748cm + :height: 9.393cm + + The coherent intermediate scattering function calculated for 120 ps + from a 240 ps and 12 ns MD simulation of liquid argon plotted in blue + and orange respectively. + +.. _figure-coh-sqw: + +.. figure:: ./Pictures/sqw_conv.png + :align: center + :width: 11.748cm + :height: 9.393cm + + The dynamic coherent structure factor calculated from a Fourier + transform of the above coherent intermediate scattering functions + using a 240 ps and 12 ns MD simulation of liquid argon plotted in blue + and orange respectively. + +In the first calculation (blue in :numref:`figure-coh-fqt` and :numref:`figure-coh-sqw`), we +use a correlation frames setting of (0, 2000, 1, 1000). The first +and last frames will be 0 and 2000 and the number of time +steps of the correlation function will be 1000. This will mean that for +this calculation each time step of the correlation function will be +averaged over 1001 = 2000 -- 1000 + 1 configurations. For the blue plot in +:numref:`figure-coh-fqt` we can see :math:`F(q, t)` oscillate around zero; +after Fourier transforming we obtain a noisy :math:`S(q, f)` which is +especially poor around zero energy. + +In the second calculation (orange in :numref:`figure-coh-fqt` and :numref:`figure-coh-sqw`), +we use a correlation frames setting of (0, 100000, 1, 1000). It means that each time +step of the correlation function will be averaged over 99001 = 100000 -- 1000 + 1 +configurations, but will still be the same length as the first calculation. Visually, +we can see that :math:`F(q, t)` decay and stay closer to zero, and after Fourier +transforming we obtain a much smoother :math:`S(q, f)`. There is still +some noise; perhaps an even longer trajectory would be required. Clearly for dynamic +coherent structure factor calculations, to obtain high quality results longer +trajectories are needed so that a larger number of configurations are used per +time step of the correlation function. + +In both calculations the number of correlation function time steps was set to 1000, which +corresponds to a time of 120 ps. From the :math:`F(q, t)`, we can see that +this is sufficiently long to ensure that the correlation function decays +to zero. We can see that it does not change significantly beyond 30 ps or so. +For other calculations or systems this might not be the case and a +more careful choice for the correlation frames may be required. + +Dynamic Incoherent Structure Factor +----------------------------------- +Here we run the dynamic incoherent structure factor calculations using the same +liquid argon system and correlation frames settings as in the dynamic coherent +structure factor calculations above. + +.. _figure-inc-fqt: + +.. figure:: ./Pictures/disf_fqt.png + :align: center + :width: 11.748cm + :height: 9.393cm + + The incoherent intermediate scattering function calculated for 120 ps + from a 240 ps and 12 ns MD simulation of liquid argon plotted in blue + and orange respectively. + +.. _figure-inc-sqw: + +.. figure:: ./Pictures/disf_sqf.png + :align: center + :width: 11.748cm + :height: 9.393cm + + The dynamic incoherent structure factor calculated from a Fourier + transform of the above incoherent intermediate scattering functions + using a 240 ps and 12 ns MD simulation of liquid argon plotted in blue + and orange respectively. + +In contrast to the coherent calculations, there +are only minor differences between calculations with the (0, 2000, 1, 1000) and +(0, 100000, 1, 1000) correlation frames settings, results shown in blue +and orange in :numref:`figure-inc-fqt` and :numref:`figure-inc-sqw` respectively. +We can see that the incoherent calculation requires a much smaller number of +configurations per time step to approach convergence. + +Static Structure Factor +----------------------- +Unlike the previous two calculations, the static structure factor does +not require the calculations of a correlation function. The quality of +your results will depend on the length of your trajectory (among a number +of other things) but obviously there will not be a correlation frames +setting to specify. + +.. _figure-ssf-conv: + +.. figure:: ./Pictures/ssf_conv.png + :align: center + :width: 11.748cm + :height: 9.393cm + + The static structure factor using a single frame of an MD simulation + and a 12 ns MD simulation of liquid argon plotted in blue and orange + respectively. + +In :numref:`figure-ssf-conv` we plot the static structure factor +calculated from a single frame of an MD simulation and a 12 ns MD +simulation. We can see that even when we use a single frame, the SSF is +quite close to the results from the 12 ns MD simulation. This occurs +since converged results can be obtained for large system sizes or +long trajectories. The argon trajectory used contain a total of 2048 +atoms which appears to be sufficient to obtain enough statistics for +good static structure factor results, so that only a short MD +simulation would be required. diff --git a/Doc/pages/H_start.rst b/Doc/pages/H_start.rst index 594b9b524e..c803b36370 100644 --- a/Doc/pages/H_start.rst +++ b/Doc/pages/H_start.rst @@ -1,20 +1,16 @@ +.. _installation-tutorial: + Installing MDANSE ================= -.. _installation_tutorial: - -MDANSE Installation Steps --------------------------- - MDANSE can be easily installed by following these steps: Create Virtual Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To create your Python virtual environment for MDANSE use `venv` or `virtualenv`. +To create your Python virtual environment for MDANSE use ``venv`` or ``virtualenv``. +Open a terminal or command prompt. -Open a Terminal or Command Prompt. - -Navigate to Your Project Directory (Optional): If you have a specific +**Navigate to your project directory (optional)**: If you have a specific project directory where you want to work with MDANSE, navigate to that directory using the ``cd`` command. For example: @@ -22,7 +18,7 @@ directory using the ``cd`` command. For example: cd path/to/your/project/directory -Create a Virtual Environment: To create a virtual environment named +**Create a virtual environment**: To create a virtual environment named ``mdanse``, use the following command: .. code-block:: bash @@ -51,7 +47,7 @@ activation command varies by operating system: Install MDANSE Package ~~~~~~~~~~~~~~~~~~~~~~ -Use `pip` to install the MDANSE package from the specified GitHub repository: +Use ``pip`` to install the MDANSE package from the specified GitHub repository: .. code-block:: bash @@ -63,18 +59,18 @@ and analysis using MDANSE, but none of the visualisation tools. Install MDANSE_GUI Package ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Similarly, install the MDANSE_GUI package using `pip`: +Similarly, install the MDANSE_GUI package using ``pip``: .. code-block:: bash pip install MDANSE_GUI -From now on, the `mdanse_gui` command will be available to start +From now on, the ``mdanse_gui`` command will be available to start the graphical interface of MDANSE, which makes it easier to create valid inputs for different analysis types. -Run MDANSE -~~~~~~~~~~ +Run MDANSE_GUI +~~~~~~~~~~~~~~ You can now start using MDANSE by running the following command: @@ -82,7 +78,7 @@ You can now start using MDANSE by running the following command: mdanse_gui -This will launch the MDANSE Graphical User Interface (GUI), +This will launch the MDANSE graphical user interface (GUI), and you can start using MDANSE for your analysis. MDANSE Scripts diff --git a/Doc/pages/Pictures/argon_pdf.png b/Doc/pages/Pictures/argon_pdf.png new file mode 100644 index 0000000000..388132b0cc Binary files /dev/null and b/Doc/pages/Pictures/argon_pdf.png differ diff --git a/Doc/pages/Pictures/disf_fqt.png b/Doc/pages/Pictures/disf_fqt.png new file mode 100644 index 0000000000..03fade5c52 Binary files /dev/null and b/Doc/pages/Pictures/disf_fqt.png differ diff --git a/Doc/pages/Pictures/disf_sqf.png b/Doc/pages/Pictures/disf_sqf.png new file mode 100644 index 0000000000..5db69cbda1 Binary files /dev/null and b/Doc/pages/Pictures/disf_sqf.png differ diff --git a/Doc/pages/Pictures/fqt_conv.png b/Doc/pages/Pictures/fqt_conv.png new file mode 100644 index 0000000000..0ee376852f Binary files /dev/null and b/Doc/pages/Pictures/fqt_conv.png differ diff --git a/Doc/pages/Pictures/sqw_conv.png b/Doc/pages/Pictures/sqw_conv.png new file mode 100644 index 0000000000..6e704cbd96 Binary files /dev/null and b/Doc/pages/Pictures/sqw_conv.png differ diff --git a/Doc/pages/Pictures/ssf_conv.png b/Doc/pages/Pictures/ssf_conv.png new file mode 100644 index 0000000000..77948048a2 Binary files /dev/null and b/Doc/pages/Pictures/ssf_conv.png differ diff --git a/Doc/pages/analysis.rst b/Doc/pages/analysis.rst index e3e5bc5d5f..90505e6166 100644 --- a/Doc/pages/analysis.rst +++ b/Doc/pages/analysis.rst @@ -38,7 +38,7 @@ molecular dipole: .. math:: :label: pfx115 - I(\omega) \propto \frac{1}{2\pi} \int\limits_{-\infty}^{\infty} \mathrm{d}t \, e^{i\omega t}\frac{1}{3 N_{\alpha}}\sum_{\alpha} \langle \dot{\mu}_{\alpha}(t_0) \cdot \dot{\mu}_{\alpha}(t_0 + t) \rangle_{t_0} + I(\omega) \propto \frac{1}{2\pi} \int\limits_{-\infty}^{\infty} \mathrm{d}t \, e^{i\omega t}\frac{1}{3 N_{\alpha}}\sum_{\alpha} \langle \dot{\mu}_{\alpha}(0) \cdot \dot{\mu}_{\alpha}(t) \rangle where :math:`N_{\alpha}` is the number of molecules :math:`\alpha` and :math:`\dot{\mu}(t)` is the time-derivative of the molecular dipole moment. @@ -47,7 +47,7 @@ the time-derivative of the molecular dipole moment. Dipole AutoCorrelation Function ''''''''''''''''''''''''''''''' -Dipole AutoCorrelation Function is valuable for studying +Dipole autocorrelation function is valuable for studying molecular vibrations and infrared spectra using dipole auto-correlation. Researchers can gain insights into the vibrational modes and spectral characteristics of molecules, aiding in the identification and analysis @@ -102,7 +102,7 @@ Trajectory Box Translated Trajectory ''''''''''''''''''''''''' -A "Box Translated Trajectory" in molecular dynamics simulations refers to a +A box translated trajectory in molecular dynamics simulations refers to a technique where the entire simulation box, representing the space in which molecules interact, is shifted or translated during the simulation. This approach can be useful for correcting periodic boundary condition artifacts, @@ -115,19 +115,19 @@ properties within the computational environment. Center Of Masses Trajectory ''''''''''''''''''''''''''' -The Center Of Mass Trajectory (*COMT*) analysis consists in deriving the +The center of mass trajectory (COMT) analysis consists in deriving the trajectory of the respective centres of mass of a set of groups of -atoms. In order to produce a visualizable trajectory, *MDANSE* assigns +atoms. In order to produce a visualizable trajectory, MDANSE assigns the centres of mass to pseudo-hydrogen atoms whose mass is equal to the mass of their associated group. Thus, the produced trajectory can be -reused for other analysis. In that sense, *COMT* analysis is a practical +reused for other analysis. In that sense, COMT analysis is a practical way to reduce noticeably the dimensionality of a system. .. _cropped-trajectory: Cropped Trajectory '''''''''''''''''' -A "Cropped Trajectory" in molecular dynamics simulations refers to a +A cropped trajectory in molecular dynamics simulations refers to a shortened version of the trajectory data file, focusing on a specific time segment of a simulation. This cropping process is useful for reducing data size, isolating relevant events, improving computational efficiency, and @@ -143,20 +143,20 @@ It is often of interest to separate global motion from internal motion, both for quantitative analysis and for visualization by animated display. Obviously, this can be done under the hypothesis that global and internal motions are decoupled within the length and timescales of -the analysis. *MDANSE* can create Global Motion Filtered Trajectory -(*GMFT*) by filtering out global motions (made of the three +the analysis. MDANSE can create global motion filtered trajectory +(GMFT) by filtering out global motions (made of the three translational and rotational degrees of freedom), either on the whole system or on a user-defined subset, by fitting it to a reference -structure (usually the first frame of the *MD*). Global motion filtering +structure (usually the first frame of the MD). Global motion filtering uses a straightforward algorithm: - for the first frame, find the linear transformation such that the coordinate origin becomes the centre of mass of the system and its principal axes of inertia are parallel to the three coordinates axes (also called principal axes transformation), -- this provides a reference configuration C\ :sub:`ref`, -- for any other frames *f*, finds and applies the linear transformation - that minimizes the RMS distance between frame *f* and C\ :sub:`ref`. +- this provides a reference configuration :math:`C_{\mathrm{ref}}`, +- for any other frames :math:`f`, finds and applies the linear transformation + that minimizes the RMS distance between frame :math:`f` and :math:`C_{\mathrm{ref}}`. The result is stored in a new trajectory file that contains only internal motions. This analysis can be useful in case where diffusive @@ -175,28 +175,28 @@ which may be the centre-of-mass, and the dynamics of the angular coordinates describing the orientation of the rigid body. The angular coordinates are the appropriate variables to compute angular correlation functions of molecular systems in space and time. In most cases, -however, these variables are not directly available from *MD* -simulations since *MD* algorithms typically work in cartesian +however, these variables are not directly available from MD +simulations since MD algorithms typically work in cartesian coordinates. Molecules are either treated as flexible, or, if they are treated as rigid, constraints are taken into account in the framework of -cartesian coordinates [Ref23]_. In *MDANSE*, -Rigid-Body Trajectory (*RBT*) can be defined from a *MD* trajectory by +cartesian coordinates [Ref23]_. In MDANSE, +rigid-body trajectory (RBT) can be defined from a MD trajectory by fitting rigid reference structures, defining a (sub)molecule, to the corresponding structure in each time frame of the trajectory. Here 'fit' means the optimal superposition of the structures in a least-squares sense. We will describe now how rigid body motions, i.e. global translations and rotations of molecules or subunits of complex -molecules, can be extracted from a *MD* trajectory. A more detailed +molecules, can be extracted from a MD trajectory. A more detailed presentation is given in [Ref24]_. We define an optimal rigid-body trajectory in the following way: for each time frame of the trajectory the atomic positions of a rigid reference structure, defined by the three cartesian components of its centroid (e.g. the centre of mass) and three angles, are as close as possible to -the atomic positions of the corresponding structure in the *MD* -configuration. Here 'as close as possible' means as close as possible in +the atomic positions of the corresponding structure in the MD +configuration. Here "as close as possible" means as close as possible in a least-squares sense. -**Optimal superposition:** We consider a given time frame in which the +**Optimal superposition**: We consider a given time frame in which the atomic positions of a (sub)molecule are given by :math:`x_{\alpha}` where :math:`{\alpha = 1}, \ldots, N`. The corresponding positions in the reference structure are denoted as :math:`x_{\alpha}^{(0)}` where :math:`{\alpha = 1}, \ldots, N`. @@ -210,8 +210,8 @@ define the deviation {\Delta_{\alpha}\doteq D(q){\left\lbrack {x_{\alpha}^{(0)} - X^{(0)}} \right\rbrack - \left\lbrack {x_{\alpha} - X} \right\rbrack}.} Here :math:`D(q)` is a rotation matrix which depends on also yet -undetermined angular coordinates which we chose to be *quaternion -parameters*, abbreviated as vector :math:`q = (q_0, q_1, q_2, q_3)`. +undetermined angular coordinates which we chose to be quaternion +parameters, abbreviated as vector :math:`q = (q_0, q_1, q_2, q_3)`. The quaternion parameters fulfil the normalization condition :math:`q \cdot {q = 1}` [Ref25]_. The target function to be minimized is now defined as @@ -220,7 +220,7 @@ The target function to be minimized is now defined as {m{\left( {q;X,X^{(0)}} \right) = {\sum\limits_{\alpha}{\omega_{\alpha}|\Delta|_{\alpha}^{2}}}}.} -where :math:`\omega_{\alpha}` are atomic weights (see Section ??). The minimization +where :math:`\omega_{\alpha}` are atomic weights. The minimization with respect to the centroids is decoupled from the minimization with respect to the quaternion parameters and yields @@ -257,7 +257,7 @@ are fixed and the rotation matrix reads \end{pmatrix} -**Quaternions and rotations:** The rotational minimization problem can +**Quaternions and rotations**: The rotational minimization problem can be elegantly solved by using quaternion algebra. Quaternions are so-called hypercomplex numbers, having a real unit, 1, and three imaginary units, :math:`I`, :math:`J`, and :math:`K`. Since :math:`IJ = K` (cyclic), @@ -306,7 +306,7 @@ where :math:`Q` is a normalised quaternion {\text{|}Q\text{|}^{2}\doteq{{q_{0}^{2} + q_{1}^{2} + q_{2}^{2} + q_{3}^{2}} = \frac{1}{4}\mathrm{Tr}\, Q^{T}Q = 1}}. -We note that a normalized quaternion is represented by an *orthogonal* 4 x 4 matrix. :math:`R'` may then be +We note that a normalized quaternion is represented by an orthogonal 4 x 4 matrix. :math:`R'` may then be written as .. math:: @@ -316,7 +316,7 @@ written as where the components :math:`x'`, :math:`y'`, :math:`z'`, abbreviated as :math:`r'`, are given by :math:`r^{'} = D(q)r`. -**Solution of the minimization problem:** In quaternion algebra, the +**Solution of the minimization problem**: In quaternion algebra, the rotational minimization problem may now be phrased as follows: .. math:: @@ -371,14 +371,14 @@ Now any normalized eigenvector :math:`q` fulfils the relation Therefore, the eigenvector belonging to the smallest eigenvalue, :math:`\lambda_{\mathrm{min}}`, is the desired solution. At the same time :math:`\lambda_{\mathrm{min}}` -gives the average error per atom. The result of *RBT* analysis is stored -in a new trajectory file that contains only *RBT* motions. +gives the average error per atom. The result of RBT analysis is stored +in a new trajectory file that contains only RBT motions. .. _unfolded-trajectory: Unfolded Trajectory ''''''''''''''''''' -An "Unfolded Trajectory" in the context of molecular dynamics +An unfolded trajectory in the context of molecular dynamics simulations refers to a trajectory data file that has been processed or analyzed to reveal the unfolding or expansion of molecular structures over time. This term is particularly relevant in the study of biomolecules or diff --git a/Doc/pages/correlation.rst b/Doc/pages/correlation.rst index a467afd640..7b8f16e3d4 100644 --- a/Doc/pages/correlation.rst +++ b/Doc/pages/correlation.rst @@ -28,7 +28,7 @@ the length of our correlation function. The correlation function of c_{ab}(m) = \frac{1}{N_t - N_c + 1} \sum\limits_{k=0}^{N_t - N_c + 1} a^{*}(k)b(k + m) \qquad m = 0, \ldots, N_{c} - 1. -and :math:`c_{ab}(m) = c^{*}_{ab}(-m)`. In case that :math:`a(k)` and +In case that :math:`a(k)` and :math:`b(k)` are identical, the corresponding correlation function :math:`c_{aa}(m)` is called an *autocorrelation* function. Notice that the prefactor is the same for all time steps :math:`m`, in previous @@ -66,5 +66,5 @@ Its widths in the time and frequency domain are :math:`\sigma_t = \alpha/T` and :math:`\sigma_\nu = 1/(2\pi\sigma_t)`, respectively. :math:`\sigma_\nu` corresponds to the width of the resolution function of the Fourier spectrum and -:math:`T_{c} =(N_c-1)\cdot\Delta t` is the length of the correlation +:math:`T_{c} =(N_c-1)\Delta t` is the length of the correlation function. diff --git a/Doc/pages/dynamics.rst b/Doc/pages/dynamics.rst index b709c1dc4f..b63befc66f 100644 --- a/Doc/pages/dynamics.rst +++ b/Doc/pages/dynamics.rst @@ -61,37 +61,35 @@ Density Of States .. _theory-and-implementation-1: -*MDANSE* calculates the power spectrum of the *VACF*, which in case of -the mass-weighted *VACF* defines the phonon discrete *DOS*, (see the -section on :ref:`analysis-vacf`) defined as: +MDANSE calculates the power spectrum of the VACF, which in case of +the mass-weighted VACF defines the phonon discrete DOS (see the +section on :ref:`analysis-vacf`), defined as: .. math:: :label: pfx5 - {\mathrm{DOS}\left( {n\Delta\nu} \right)\doteq{\sum\limits_{\alpha}\omega_{\alpha}}{\overset{\sim}{C}}_{\mathit{vv};\mathit{\alpha\alpha}}\left( {n\Delta\nu} \right) \qquad {n = 0}, \ldots, {N_{t} - 1.}} + {\mathrm{DOS}\left( {\nu} \right)\doteq{\sum\limits_{\alpha}\omega_{\alpha}}{\overset{\sim}{C}}_{\mathit{vv};\mathit{\alpha\alpha}}\left(\nu \right)} -where :math:`N_{t}` is the total number of time steps of the correlation function, -:math:`{\Delta\nu = 1}\text{/}\left( {2N_{t}\Delta t} \right)` -is the frequency step, :math:`{\overset{\sim}{C}}_{\mathit{vv};\mathit{\alpha\alpha}}\left( {n\Delta\nu} \right)` +where :math:`{\overset{\sim}{C}}_{\mathit{vv};\mathit{\alpha\alpha}}\left( {\nu} \right)` is the Fourier transform of the velocity autocorrelation function and :math:`\omega_{\alpha}` is the weighting factor used for atom :math:`\alpha`. -:math:`{\mathrm{DOS}\left( {n\Delta\nu} \right)}` +The DOS can be computed either for the isotropic case or with respect to a -user-defined axis. The spectrum -:math:`{\mathrm{DOS}\left( {n\Delta\nu} \right)}` -is computed from the *unnormalized VACF*, such that :math:`\mathrm{DOS}(0)` gives an +user-defined axis. Since the DOS +is computed from the unnormalized VACF, such that :math:`\mathrm{DOS}(0)` gives an approximate value for the diffusion constant :math:`D = {\sum\limits_{\alpha}D_{\alpha}}` (see Eqs. :math:numref:`pfx20` and :math:numref:`pfx21`). -:math:`{\mathrm{DOS}\left( {n\Delta\nu} \right)}` +The DOS can be smoothed by, for example, a Gaussian window applied in the time domain [Ref10]_ (see the section :ref:`appendix-fca`). Its width in the time domain is :math:`{\sigma_{t} = \alpha}\text{/}T` , where :math:`T` is the length of the correlation function. We remark that the diffusion -constant obtained from *DOS* is biased due to the spectral smoothing -procedure since the *VACF* is weighted by this window Gaussian function. -*MDANSE* computes the density of states starting from atomic +constant obtained from this DOS is biased due to the spectral smoothing +procedure since the VACF is weighted by this window Gaussian function. + +MDANSE computes the density of states starting from atomic velocities. In the case that velocities are not available, the velocities will be computed by numerical differentiation of the coordinate trajectories correcting first for possible jumps due to periodic boundary conditions. @@ -110,7 +108,7 @@ Mean Square Displacement :width: 11.748cm :height: 9.393cm - *MSD* calculated for a 100 ps MD simulation of 256 water + MSD calculated for a 100 ps MD simulation of 256 water molecules using NPT condition at 1 bar and 300 K. Molecules in liquids and gases do not stay in the same place but move @@ -123,9 +121,9 @@ it will be seen to be a good approximation to a random walk. Mathematically, a random walk is a series of steps where each step is taken in a completely random direction from the one before. This kind of path was famously analysed by Albert Einstein in a study of Brownian -motion. He showed that the Mean-Square Displacement (*MSD*) of a +motion. He showed that the Mean-Square Displacement (MSD) of a particle following a random walk is proportional to the time elapsed. -The :numref:`figure-one` shows an example of an *MSD* analysis +The :numref:`figure-one` shows an example of an MSD analysis performed on a water box of 768 water molecules. To get the diffusion coefficient out of this plot, the slope of the linear part of the plot should be calculated. @@ -135,34 +133,34 @@ By defining .. math:: :label: pfx13 - {d_{\alpha}\left( {t,t_{0}} \right)\doteq R_{\alpha}{\left( {t_{0} + t} \right) - R_{\alpha}}\left( t_{0} \right),} + {d_{\alpha}\left( {t} \right)\doteq R_{\alpha}{\left( {t} \right) - R_{\alpha}}\left( 0 \right),} -the *MSD* of particle :math:`\alpha` can be written as: +the MSD of particle :math:`\alpha` can be written as: .. math:: :label: pfx14 - \mathrm{\Delta}_{\alpha}^{2}{(t) = \left\langle {d_{\alpha}^{2}\left( {t,t_{0}} \right)} \right\rangle_{t_{0}}} + \mathrm{\Delta}_{\alpha}^{2}{(t) = \left\langle {d_{\alpha}^{2}\left( {t} \right)} \right\rangle} -where :math:`R_{\alpha}(t_0)` and :math:`R_{\alpha}(t_0 + t)` are +where :math:`R_{\alpha}(0)` and :math:`R_{\alpha}(t)` are respectively the position of particle :math:`\alpha` -at times :math:`t_0` and :math:`t_0 + t`. One can introduce an *MSD* with respect to a given axis n: +at times :math:`0` and :math:`t`. One can introduce an MSD with respect to a given axis n: .. math:: :label: pfx15 - {\mathrm{\Delta}_{\alpha}^{2}\left( {t,t_{0};n} \right)\doteq\left\langle {d_{\alpha}^{2}\left( {t,t_{0};n} \right)} \right\rangle_{t_{0}}} + {\mathrm{\Delta}_{\alpha}^{2}\left( {t;n} \right)\doteq\left\langle {d_{\alpha}^{2}\left( {t;n} \right)} \right\rangle} with .. math:: :label: pfx16 - {d_{\alpha}^{}\left( {t,t_{0};n} \right)\doteq n\cdot d_{\alpha}^{}\left( {t,t_{0}} \right).} + {d_{\alpha}^{}\left( {t;n} \right)\doteq n\cdot d_{\alpha}^{}\left( {t} \right).} -The calculation of *MSD* is the standard way to obtain diffusion -coefficients from Molecular Dynamics (*MD*) simulations. Assuming +The calculation of MSD is the standard way to obtain diffusion +coefficients from Molecular Dynamics (MD) simulations. Assuming Einstein-diffusion in the long time limit one has for isotropic systems .. math:: @@ -170,7 +168,7 @@ Einstein-diffusion in the long time limit one has for isotropic systems {D_{\alpha} = {\lim\limits_{t\rightarrow\infty}{\frac{1}{6t}\mathrm{\Delta}_{\alpha}^{2}(t)}}}. -There exists also a well-known relation between the *MSD* and the +There exists also a well-known relation between the MSD and the velocity autocorrelation function. Writing .. math:: @@ -192,7 +190,7 @@ coefficient one obtains the relation .. math:: :label: pfx20 - {{D_{\alpha} = {\int\limits_{0}^{t}{\mathrm{d}\tau \, C_{\mathit{\upsilon\upsilon};\mathit{\alpha\alpha}}(t)}}}.} + {{D_{\alpha} = {\int\limits_{0}^{\infty}{\mathrm{d}\tau \, C_{\mathit{\upsilon\upsilon};\mathit{\alpha\alpha}}(t)}}}.} and can also be written as @@ -201,20 +199,20 @@ and can also be written as {{D_{\alpha} = \pi}{\overset{\sim}{C}}_{\mathit{\upsilon\upsilon};\mathit{\alpha\alpha}}(0).} -Computationally, the *MSD* is calculated by calculating the position autocorrelation since -from Eq. :math:numref:`pfx13` and :math:numref:`pfx14` +Computationally, the MSD is calculated by calculating the position autocorrelation since +from Eqs. :math:numref:`pfx13` and :math:numref:`pfx14` .. math:: :label: pfx22 - \mathrm{\Delta}_{\alpha}^{2}{(t) = \left\langle [R_{\alpha}{\left( {t_{0} + t} \right) - R_{\alpha}}\left( t_{0} \right)]^2 \right\rangle_{t_{0}}} + \mathrm{\Delta}_{\alpha}^{2}{(t) = \left\langle [R_{\alpha}{\left( t \right) - R_{\alpha}}\left( 0 \right)]^2 \right\rangle} and therefore .. math:: :label: pfx23 - \mathrm{\Delta}_{\alpha}^{2}(t) = \left\langle R_{\alpha}^{2}\left( {t_{0} + t} \right) \right\rangle_{t_{0}} + \left\langle R_{\alpha}^{2}\left( {t_{0}} \right) \right\rangle_{t_{0}} - 2\left\langle R_{\alpha}\left( {t_{0}} + t \right)R_{\alpha}\left( {t_{0}} \right) \right\rangle_{t_{0}} + \mathrm{\Delta}_{\alpha}^{2}(t) = \left\langle R_{\alpha}^{2}\left( t \right) \right\rangle + \left\langle R_{\alpha}^{2}\left( 0 \right) \right\rangle - 2\left\langle R_{\alpha}\left(t \right)R_{\alpha}\left( 0 \right) \right\rangle where the last part on the right side Eq. :math:numref:`pfx23` is the position autocorrelation of the atom :math:`\alpha`. @@ -226,7 +224,7 @@ Order Parameter .. _theory-and-implementation-3: -Adequate and accurate cross comparison of the NMR and *MD* simulation +Adequate and accurate cross comparison of the NMR and MD simulation data is of crucial importance in versatile studies conformational dynamics of proteins. NMR relaxation spectroscopy has proven to be a unique approach for a site-specific investigation of both global @@ -298,7 +296,7 @@ ranging from :math:`0` (completely disordered) to :math:`1` (fully ordered). So, computationally feasible timescales as it describes the spatial aspects of the reorientational motion of N-H peptidic bonds vector. -When performing Order Parameter analysis, *MDANSE* computes for each +When performing order parameter analysis, MDANSE computes for each residue :math:`i` both :math:`C_{\mathit{ii}}(t)` and :math:`S_{i}^{2}`. It also computes a correlation function averaged over all the selected bonds defined as: @@ -316,22 +314,22 @@ where :math:`N_{\mathrm{bonds}}` is the number of selected bonds for the analysi Position AutoCorrelation Function ''''''''''''''''''''''''''''''''' -The Position AutoCorrelation function (*PACF*) is similar to the -velocity autocorrelation function described below. In MDANSE the *PACF* +The position autocorrelation function (PACF) is similar to the +velocity autocorrelation function described below. In MDANSE the PACF is calculated relative to the atoms average position over the entire trajectory .. math:: :label: pfx44a - {\mathrm{PACF}_{\alpha}(t)\doteq\frac{1}{3}\left\langle {\Delta R_{\alpha}\left( t_{0} \right)\cdot \Delta R_{\alpha}\left( {t_{0} + t} \right)} \right\rangle_{t_{0}}} + {\mathrm{PACF}_{\alpha}(t)\doteq\frac{1}{3}\left\langle {\Delta R_{\alpha}\left( 0 \right)\cdot \Delta R_{\alpha}\left( t \right)} \right\rangle} where .. math:: :label: pfx44b - \Delta R_{\alpha}\left( t \right) = R_{\alpha}\left( t \right) - \langle R_{\alpha}\left( t \right) \rangle_{t} + \Delta R_{\alpha}\left( t \right) = R_{\alpha}\left( t \right) - \langle R_{\alpha} \rangle so that the origin dependence of the PACF function is removed. @@ -340,17 +338,17 @@ so that the origin dependence of the PACF function is removed. Van Hove Function ''''''''''''''''' The van Hove function describes the probability of finding a particle -:math:`j` at a distance :math:`R` at time :math:`t_0 + \Delta t` from a -particle :math:`i` at a time :math:`t_0` +:math:`j` at a distance :math:`R` at time :math:`t` from a +particle :math:`i` at a time :math:`0` .. math:: - G(R,\Delta t) = \frac{1}{N} \left\langle \sum_{i}^{N}\sum_{j}^{N} \delta [R - R_{j}(t_0 + \Delta t) + R_{i}(t_0)] \right\rangle + G(R, t) = \frac{1}{N} \sum_{i}^{N}\sum_{j}^{N} \left\langle \delta [R - R_{j}(t) + R_{i}(0)] \right\rangle and can be rewritten so that .. math:: - G(R,\Delta t) &= \frac{1}{N} \left\langle \int \sum_{i}^{N}\sum_{j}^{N} \delta [R' + R - R_{j}(t_0 + \Delta t)]\delta [R' - R_{i}(t_0)] \, \mathrm{d} R' \right\rangle \\ - &= \frac{1}{\rho} \left\langle \rho (R, t_0 + \Delta t) \rho (0, t_0) \right\rangle + G(R, t) &= \frac{1}{N} \int \sum_{i}^{N}\sum_{j}^{N} \left\langle \delta [R' + R - R_{j}(t)]\delta [R' - R_{i}(0)] \right\rangle \, \mathrm{d} R' \\ + &= \frac{1}{\rho} \left\langle \rho (R, t) \rho (0, 0) \right\rangle so that the van Hove function is a density-density time-correlation function. The van Hove function is related to the intermediate scattering @@ -358,26 +356,26 @@ function via a Fourier transform and the dynamic structure factor via a double Fourier transform .. math:: - F(q,\Delta t) &= \int G(R,t) \exp(i q \cdot R) \, \mathrm{d}R \\ + F(q, t) &= \int G(R,t) \exp(i q \cdot R) \, \mathrm{d}R \\ S(q,\omega) &= \int\int G(R,t) \exp(i q \cdot R - i \omega t) \, \mathrm{d}R\mathrm{d}t and can be split into distinct and self parts where .. math:: - G_{\mathrm{d}}(R,\Delta t) &= \left\langle \frac{1}{N} \sum_{i}^{N}\sum_{j \neq i}^{N} \delta [R - R_{j}(t_0 + \Delta t) + R_{i}(t_0)] \right\rangle \\ - G_{\mathrm{s}}(R,\Delta t) &= \left\langle \frac{1}{N} \sum_{i} \delta [R - R_{i}(t_0 + \Delta t) + R_{i}(t_0)] \right\rangle + G_{\mathrm{d}}(R, t) &= \frac{1}{N} \sum_{i}^{N}\sum_{j \neq i}^{N} \left\langle \delta [R - R_{j}(t) + R_{i}(0)] \right\rangle \\ + G_{\mathrm{s}}(R, t) &= \frac{1}{N} \sum_{i} \left\langle \delta [R - R_{i}(t) + R_{i}(0)] \right\rangle -In *MDANSE* the distinct part of the van Hove function is spherically +In MDANSE the distinct part of the van Hove function is spherically averaged and normalised so that for liquid or gaseous systems .. math:: - \lim_{r \rightarrow \infty } G_{\mathrm{d}}(r,\Delta t) = \lim_{\Delta t \rightarrow \infty } G_{\mathrm{d}}(r,\Delta t) = 1 + \lim_{r \rightarrow \infty } G_{\mathrm{d}}(r, t) = \lim_{t \rightarrow \infty } G_{\mathrm{d}}(r, t) = 1 -and the self part of the van Hove function in *MDANSE* is summed so +and the self part of the van Hove function in MDANSE is summed so that it only depends on the distance :math:`r` .. math:: - G_{\mathrm{s}}(r,\Delta t) = \left\langle \frac{1}{N} \sum_{i} \delta \left[r - \vert R_{i}(t_0 + \Delta t) + R_{i}(t_0) \vert \right] \right\rangle + G_{\mathrm{s}}(r, t) = \frac{1}{N} \sum_{i} \left\langle \delta \left[r - \vert R_{i}(t) + R_{i}(0) \vert \right] \right\rangle .. _analysis-vacf: @@ -386,17 +384,13 @@ Velocity AutoCorrelation Function .. _theory-and-implementation-4: -The Velocity AutoCorrelation Function (*VACF*) is another interesting -property describing the dynamics of a molecular system. Indeed, it -reveals the underlying nature of the forces acting on the system. - In a molecular system that would be made of non-interacting particles, -the velocities would be constant at any time triggering the *VACF* to be +the velocities would be constant and the VACF would have a constant value. Now, if we think about a system with small interactions such as in a gas-phase, the magnitude and direction of the velocity of a particle will change gradually over time due to its collision with the other particles of the molecular system. In such a -system, the *VACF* will be represented by a decaying exponential. +system, the VACF will be represented by a decaying exponential. In the case of solid phase, the interactions are much stronger and, as a results, the atoms are bound to a given position from which they will @@ -404,32 +398,32 @@ move backwards and forwards oscillating between positive and negative values of their velocity. The oscillations will not be of equal magnitude however, but will decay in time, because there are still perturbative forces acting on the atoms to disrupt the perfection of -their oscillatory motion. So, in that case the *VACF* will look like a +their oscillatory motion. So, in that case the VACF will look like a damped harmonic motion. Finally, in the case of liquid phase, the atoms have more freedom than in solid phase and because of the diffusion process, the oscillatory motion seen in solid phase will be cancelled quite rapidly depending on -the density of the system. So, the *VACF* will just have one very damped +the density of the system. So, the VACF will just have one very damped oscillation before decaying to zero. This decaying time can be considered as the average time for a collision between two atoms to occur before they diffuse away. -Mathematically, the *VACF* of atom :math:`\alpha` in an atomic or molecular system is +Mathematically, the VACF of atom :math:`\alpha` in an atomic or molecular system is usually defined as .. math:: :label: pfx45 - {C_{\mathit{vv};\mathit{\alpha\alpha}}(t)\doteq\frac{1}{3}\left\langle {v_{\alpha}\left( t_{0} \right)\cdot v_{\alpha}\left( {t_{0} + t} \right)} \right\rangle_{t_{0}}.} + {C_{\mathit{vv};\mathit{\alpha\alpha}}(t)\doteq\frac{1}{3}\left\langle {v_{\alpha}\left( 0 \right)\cdot v_{\alpha}\left( t \right)} \right\rangle.} In some cases, e.g. for non-isotropic systems, it is useful to define -*VACF* along a given axis, +VACF along a given axis, .. math:: :label: pfx46 - {C_{\mathit{vv};\mathit{\alpha\alpha}}\left( {t;n} \right)\doteq\left\langle {v_{\alpha}\left( {t_{0};n} \right)v_{\alpha}\left( {{t_{0} + t};n} \right)} \right\rangle_{t_{0}},} + {C_{\mathit{vv};\mathit{\alpha\alpha}}\left( {t;n} \right)\doteq\left\langle {v_{\alpha}\left( {0;n} \right)v_{\alpha}\left( {t;n} \right)} \right\rangle,} where :math:`v_{\alpha}(t; n)` is given by @@ -440,7 +434,7 @@ where :math:`v_{\alpha}(t; n)` is given by The vector :math:`n` is a unit vector defining a space-fixed axis. -The *VACF* of the particles in a many body system can be related to the +The VACF of the particles in a many body system can be related to the incoherent dynamic structure factor by the relation: .. math:: @@ -448,7 +442,7 @@ incoherent dynamic structure factor by the relation: {\lim\limits_{q\rightarrow 0}\frac{\omega^{2}}{q^{2}}S{\left( {q,\omega} \right) = G}(\omega),} -where :math:`G(\omega)` is the Density Of States (*DOS*). For an isotropic system it +where :math:`G(\omega)` is the density of states. For an isotropic system it reads .. math:: @@ -461,7 +455,7 @@ reads {{\overset{\sim}{C}}_{\mathit{vv};\mathit{\alpha\alpha}}{(\omega) = \frac{1}{2\pi}}{\int\limits_{- \infty}^{+ \infty}\mathrm{d} t \,}\exp\left\lbrack {{- i}\omega t} \right\rbrack C_{\mathit{vv};\mathit{\alpha\alpha}}(t).} -For non-isotropic systems, relation :math:numref:`pfx48` holds if the *DOS* +For non-isotropic systems, relation :math:numref:`pfx48` holds if the DOS is computed from the atomic velocity autocorrelation functions :math:`C_{\mathit{vv};\mathit{\alpha\alpha}}\left( {t;n_{q}} \right)` where :math:`n_q` is the unit vector in the direction of :math:`q`. diff --git a/Doc/pages/files.rst b/Doc/pages/files.rst index 6c01ead882..a74171fe56 100644 --- a/Doc/pages/files.rst +++ b/Doc/pages/files.rst @@ -3,66 +3,54 @@ Supported File Formats ====================== -In the updated MDANSE version, there have been significant changes to the +In MDANSE 2, there have been significant changes to the supported file formats for input and output. This section provides an overview of these changes and the file formats used by MDANSE. .. _hdf5: -HDF5 File Format and GUI Integration -------------------------------------- +HDF5 Based File Formats +------------------------ -In the new version of MDANSE, the primary file format for both trajectory -storage and analysis results is `Hierarchical Data Format (HDF5) `_ +In the MDANSE 2, the primary file format for both trajectory (MDT) +storage and analysis (MDA) results are based on the `Hierarchical Data Format (HDF5) `_ . HDF5 is a versatile file format designed for efficiently organizing and managing large data sets. It employs a hierarchical structure, akin to a file system, -and supports n-dimensional arrays with associated metadata attributes. HDF5 +and supports *n*-dimensional arrays with associated metadata attributes. HDF5 is widely adopted, and even `NetCDF version 4 `_ is built on top of HDF5. Using HDF5 ensures platform independence, efficient data storage, and self-contained information within trajectory files. -Furthermore, users can interact with MDANSE through -the GUI to convert trajectories from different formats to the required -HDF5 format, perform analysis and plot results. +Trajectories have to be converted to the MDT format before +MDANSE can perform analysis calculations. Multiple converters +are available in MDANSE to convert outputs of different MD engines +to the MDT format. + +The results of MDANSE analysis runs are saved in MDA files. +Contents of the MDA files can be viewed and plotted in the MDANSE GUI. .. _text_output: DAT File Format ----------------- -An alternative output format of Analysis results is in the form of -`DAT files `_, which +An alternative output format of analysis results is in the form of DAT files, which are text-based and easily readable. Each DAT file corresponds to a specific -variable generated during the analysis. If the Text option is selected, a +variable generated during the analysis. If the TextFormat option is selected, a tarball is generated, which contains multiple files, including: -- ``jobinfo.txt``: A text file documenting the analysis options selected during +- **jobinfo.txt**: A text file documenting the analysis options selected during the analysis. -- Variable DAT files: Each file is named after the variable it contains and +- **DAT files**: Each file is named after the variable it contains and includes the following information: - Variable name - Type of plot (representing plot dimensions) - - Variable's placement on the x-axis (if plotted on the y-axis in the + - Variable's placement on the *x*-axis (if plotted on the *y*-axis in the 2D/3D Plotter) - Units of data - - Length of the trajectory (indicated as slice:[length]) + - Length of the trajectory (indicated as ``slice:[length]``) - A list of numbers representing the variable data The DAT format simplifies data sharing and analysis, providing a clear and human-readable representation of analysis results. - -.. _mdanse-scripts: - -MDANSE Scripts --------------------- - -MDANSE now includes Python scripts that capture the complete analysis setup, -including all selected options. These scripts are designed to be run using -the Python interpreter bundled with MDANSE. Running these scripts automates -the execution of a specific analysis with predefined settings, simplifying -repetitive tasks and ensuring consistency in analysis procedures. - -This update streamlines the analysis process and facilitates the reproducibility -of results within MDANSE. - diff --git a/Doc/pages/installation.rst b/Doc/pages/installation.rst index 517d3c9227..dec5f5e4d9 100644 --- a/Doc/pages/installation.rst +++ b/Doc/pages/installation.rst @@ -8,23 +8,23 @@ simulations in the context of neutron scattering experiments. MDANSE Installation -------------------- -To get started with MDANSE, you can follow the MDANSE Installation Tutorial -at :ref:`installation_tutorial`. +To get started with MDANSE, you can follow the MDANSE installation guide +at :ref:`installation-tutorial`. Explore the Documentation -------------------------- -MDANSE comes with extensive documentation, providing: +MDANSE comes with extensive documentation and is split into four sections: -- **Explanations:** Clear understanding of MDANSE's capabilities and background knowledge. -- **Tutorials:** Step-by-step instructions to help you get started and become proficient. -- **How-To Guides:** Practical solutions for common tasks. -- **Technical References:** Detailed information about MDANSE's features and functionalities. +- **Explanations**: Clear understanding of MDANSE's capabilities and background knowledge. +- **Tutorials**: Step-by-step instructions to help you get started and become proficient. +- **How-to guides**: Practical solutions for common tasks. +- **Technical references**: Detailed information about MDANSE's features and functionalities. Sample Data ----------- -MDANSE often provides sample datasets that you can use for -testing and learning. You can typically find sample +MDANSE provides sample datasets that you can use for +testing and learning. You can find sample data within the `MDANSE-Examples GitHub repository `_. diff --git a/Doc/pages/introduction.rst b/Doc/pages/introduction.rst index 9c774aa15f..93142a6e70 100644 --- a/Doc/pages/introduction.rst +++ b/Doc/pages/introduction.rst @@ -26,13 +26,11 @@ molecular dynamics simulations. Its primary objectives are to: Flexibility and Compatibility ----------------------------- -MDANSE offers: - - A Python-based graphical user interface (GUI) via the MDANSE_GUI package, including a trajectory viewer and a data plotter. - Command-line utilities for creating and running MDANSE jobs as Python scripts. - Specialised trajectory converters for specific MD engines. -- A general trajectory converter based on ASE. +- General trajectory converters based on ASE, MDAnalysis and MDTraj. Your Guide to MDANSE --------------------- @@ -47,9 +45,5 @@ Collaboration and Feedback The authors welcome suggestions, feedback, and bug reports regarding the MDANSE software and this user's guide, we encourage you to report them. Your feedback is essential in helping us enhance the software and improve the user experience. - -GitHub Repository ------------------ - -You can report issues and make suggestions on our GitHub repository. Please visit -the following link to access the `MDANSE GitHub repository `_ +You can report issues and make suggestions on our `GitHub repository `_. +Alternatively, you can contact the developers directly by emailing us at MDANSE-help@stfc.ac.uk. diff --git a/Doc/pages/parameters.rst b/Doc/pages/parameters.rst index 2c802215c9..4bed54c267 100644 --- a/Doc/pages/parameters.rst +++ b/Doc/pages/parameters.rst @@ -4,6 +4,8 @@ Glossary of Parameters ======================= +.. _param-frames: + Frames ~~~~~~ @@ -148,6 +150,7 @@ Axis selection is available for :ref:`analysis-angular-correlation` and :ref:`analysis-op` analyses. +.. _param-atom-selection: Atom Selection ^^^^^^^^^^^^^^ diff --git a/Doc/pages/scattering.rst b/Doc/pages/scattering.rst index 6b20298816..df1d4765df 100644 --- a/Doc/pages/scattering.rst +++ b/Doc/pages/scattering.rst @@ -20,22 +20,21 @@ This section discusses plugins used to calculate neutron spectroscopy observables from the trajectory. These plugins will be explored in depth in further sections, however, before that, it is important to understand how MDANSE performs these -analyses. A part of that are :ref:`param-q-vectors`, which -are used to perform these analyses. An in-depth discussion of this -aspect is present in `Appendix 2 <#_Appendix_2>`__. +analyses. A part of that are the :ref:`param-q-vectors`, which +are used to perform these analyses. .. _scattering_theory: Background '''''''''' -**Dynamic Structure Factor S(q, ω):** This is a central +**Dynamic structure factor S(q, ω)**: This is a central concept in neutron scattering experiments. This factor characterizes how scattering intensity changes with alterations in momentum (:math:`q`) and energy (:math:`\omega`) during scattering events. It is instrumental in unraveling the atomic and molecular structures of materials. -**Double Differential Cross-Section:** :math:`S(q, \omega)` is closely related to the -double differential cross-section [7], which is a vital measurement in neutron +**Double differential cross-section**: The dynamic structure factor is closely related to the +double differential cross-section, which is a vital measurement in neutron scattering. The double differential cross-section, :math:`{\mathrm{d}^{2}{\sigma/\mathit{\mathrm{d}\Omega \mathrm{d}E}}}`, is defined as the number of neutrons scattered per unit time into the solid angle interval @@ -75,8 +74,8 @@ These equations relate the neutron energies (:math:`E` and :math:`E_0`) to their numbers (:math:`k` and :math:`k_0`) using the mass of the neutron (:math:`m`). They are fundamental for connecting energy and momentum in neutron scattering. -**Dimensionless Momentum and Energy Transfer:** These equations below define the -dimensionless momentum (:math:`q`, dynamic structure factor) and energy (:math:`\omega`) transfer in +**Momentum and energy transfer**: These equations below define the +momentum (:math:`q`) and energy (:math:`\omega`) transfer in units of the reduced Planck constant (:math:`\hbar`) based on the incident and scattered wave numbers and energies: @@ -91,7 +90,7 @@ wave numbers and energies: {{\omega = \frac{E_{0} - E}{\hbar}}.} The modulus of the momentum transfer can be expressed in terms of a scattering -angle, energy transfer, and incident neutron energy. See equation below: +angle, energy transfer, and incident neutron energy. .. math:: :label: pfx60 @@ -99,10 +98,10 @@ angle, energy transfer, and incident neutron energy. See equation below: {{\vert q \vert = \vert k_{0} \vert \sqrt{{2 - \frac{\mathit{\hbar\omega}}{E_{0}} - 2}\cos{\theta\sqrt{1 - \frac{\mathit{\hbar\omega}}{E_{0}}}}}}.} -**Intermediate Scattering Function F(q, t):** -This equation defines the dynamic structure factor, :math:`S(q, \omega)`, as a Fourier -transform of the intermediate scattering function, :math:`F(q, t)`, with respect to -time, :math:`t`. It captures information about the structure and dynamics of the +**Intermediate scattering function F(q, t)**: +This equation defines the dynamic structure factor :math:`S(q, \omega)` as a Fourier +transform of the intermediate scattering function :math:`F(q, t)` with respect to +time :math:`t`. It captures information about the structure and dynamics of the scattering system [Ref16]_. It can be written as: .. math:: @@ -110,7 +109,7 @@ scattering system [Ref16]_. It can be written as: {S{\left( {q,\omega} \right) = \frac{1}{2\pi}}{\int\limits_{- \infty}^{+ \infty}\mathrm{d}t \, }\exp\left\lbrack {{- i}\omega t} \right\rbrack F\left( {q,t} \right).} -:math:`F(q, t)` is called the *intermediate scattering function* and is defined as +and .. math:: :label: pfx62 @@ -138,10 +137,10 @@ The overline :math:`\overline{...}` appearing in :math:`{\Gamma_{\mathit{\alpha\ denotes an average over isotopes and relative spin orientations of neutron and nucleus. -**Coherent and Incoherent Scattering:** +**Coherent and incoherent scattering**: Usually, one splits the intermediate scattering function and the dynamic structure factor into their *coherent* and *incoherent* parts which -describe collective and single particle motions, respectively. Defining +describe collective and single particle motions, respectively. By defining .. math:: :label: pfx65 @@ -167,7 +166,7 @@ treatments for coherent and incoherent scattering lengths. {\text{F}_{\text{inc}}{\left( {q,t} \right) = \frac{1}{N}}{\sum\limits_{\alpha}{b_{\alpha,\mathrm{inc}}^{2}\left\langle {\exp\left\lbrack {{- i}q\cdot\hat{R}_{\alpha}(0)} \right\rbrack\exp\left\lbrack {iq\cdot\hat{R}_{\alpha}(t)} \right\rbrack} \right\rangle}}.} -*MDANSE* introduces the partial terms, this considers the contributions from different species :math:`(I, J)` to the scattering process. +MDANSE introduces the partial terms, this considers the contributions from different species :math:`(I, J)` to the scattering process. .. math:: :label: pfx69 @@ -184,19 +183,19 @@ where: .. math:: :label: pfx71 - {\text{F}_{\mathit{IJ},\text{coh}}{\left( {q,t} \right) = \frac{1}{\sqrt{n_{I}n_{J}}}}{\sum\limits_{\alpha}^{n_{I}}{\sum\limits_{\beta}^{n_{J}}\left\langle {\exp\left\lbrack {{- i}q\cdot\hat{R}_{\alpha}\left( t_{0} \right)} \right\rbrack\exp\left\lbrack {iq\cdot\hat{R}_{\beta}\left( {t_{0} + t} \right)} \right\rbrack} \right\rangle_{t_{0}}}},} + {\text{F}_{\mathit{IJ},\text{coh}}{\left( {q,t} \right) = \frac{1}{\sqrt{n_{I}n_{J}}}}{\sum\limits_{\alpha}^{n_{I}}{\sum\limits_{\beta}^{n_{J}}\left\langle {\exp\left\lbrack {{- i}q\cdot\hat{R}_{\alpha}\left( 0 \right)} \right\rbrack\exp\left\lbrack {iq\cdot\hat{R}_{\beta}\left( t \right)} \right\rbrack} \right\rangle}},} .. math:: :label: pfx72 - {\text{F}_{I,\text{inc}}{\left( {q,t} \right) = \frac{1}{n_{I}}}{\sum\limits_{\alpha = 1}^{n_{I}}\left\langle {\exp\left\lbrack {{- i}q\cdot\hat{R}_{\alpha}\left( t_{0} \right)} \right\rbrack\exp\left\lbrack {iq\cdot\hat{R}_{\alpha}\left( {t_{0} + t} \right)} \right\rbrack} \right\rangle_{t_{0}}}.} + {\text{F}_{I,\text{inc}}{\left( {q,t} \right) = \frac{1}{n_{I}}}{\sum\limits_{\alpha = 1}^{n_{I}}\left\langle {\exp\left\lbrack {{- i}q\cdot\hat{R}_{\alpha}\left( 0 \right)} \right\rbrack\exp\left\lbrack {iq\cdot\hat{R}_{\alpha}\left( t \right)} \right\rbrack} \right\rangle}.} where :math:`n_I`, :math:`n_J`, :math:`n_{\mathrm{species}}`, :math:`\omega_{I,(\mathrm{coh}/\mathrm{inc})}` and :math:`\omega_{J,(\mathrm{coh}/\mathrm{inc})}` are defined in Section :ref:`target_CN`. The corresponding dynamic structure factors are obtained by performing the Fourier transformation defined in Eq. :math:numref:`pfx61`. -**Classical Framework and Corrections:** +**Classical framework and corrections**: In the classical framework the intermediate scattering functions are interpreted as classical time correlation functions. The position operators are replaced by time-dependent vector functions and quantum @@ -228,7 +227,7 @@ liquid, containing only one sort of atoms, it reads where :math:`M` is the mass of the atoms. -**Recoil Moment:** Formula :math:numref:`pfx76` shows that the +**Recoil moment**: Formula :math:numref:`pfx76` shows that the first moment is given by the average kinetic energy (in units of :math:`\hbar`) of a particle which receives a momentum transfer :math:`\hbar q`. Therefore, :math:`\langle\omega\rangle` @@ -248,13 +247,12 @@ is correct to first order in :math:`\hbar`. Therefore, it cannot be used for large :math:`q`-values which correspond to large momentum transfers :math:`\hbar q`. This is actually true for all correction methods which have suggested -so far. For more details we refer to Ref. -[Ref18]_. +so far. For more details we refer to [Ref18]_. -**Static Structure Factor S(q):** An important quantity describing structural properties of liquids is the -static structure factor. :math:`S(q)` as an integral involving the -dynamic structure factor which is also the coherent intermediate scattering function +**Static structure factor S(q)**: An important quantity describing structural properties of liquids is the +static structure factor. :math:`S(q)` is an integral involving the +dynamic structure factor or the coherent intermediate scattering function at zero time delay :math:`t = 0`. .. math:: @@ -262,7 +260,7 @@ at zero time delay :math:`t = 0`. {\text{S}(q)\doteq{\int\limits_{- \infty}^{+ \infty}{\mathrm{d}\omega}}\,\text{S}_{\mathrm{coh}}\left( {q,\omega} \right) = \text{F}_{\mathrm{coh}}\left( {q,0} \right).} -**Total Structure Factors:** MDANSE computes the partial :math:`S(Q)` as the Fourier transform of the +**Total structure factors**: MDANSE computes the partial :math:`S(Q)` as the Fourier transform of the partial pair distribution function :math:`g(r)`, corresponding to the Faber-Ziman definition: .. math:: @@ -275,7 +273,7 @@ the total :math:`g(r)`. In the case of the analysis 'X-ray Static structure factor', the :math:`Q`-dependence of the atomic form factors is taken into account in this weighted sum. -**X-ray Observable Normalization:** Again, Soper has provided experimental data (table 4 in *ISRN Physical +**X-ray observable normalization**: Soper has provided experimental data (table 4 in *ISRN Physical Chemistry*, 279463 (2013), given in file soper13_fx.dat). Here a source of confusion is that the data can be normalized in different ways (see Soper's paper). Using the normalization II in that reference we have @@ -295,39 +293,57 @@ recalculate the x-ray observable using the atomic factors. Current Correlation Function '''''''''''''''''''''''''''' -The correlation function is a fundamental concept in the study of dynamical -processes in various physical systems, including disordered materials. It -provides insights into how fluctuations or excitations propagate through a -system over time. In the context of disordered systems, understanding the -correlation function can help reveal the behavior of particles or components -in a disordered environment, such as a disordered solid or a supercooled -liquid. +The current correlation functions :math:`C_{\alpha\beta}(q, t)` and :math:`C_{\alpha\beta}(q, \omega)` +are closely related to the intermediate scattering function :math:`F(q, t)` +and the dynamics structure factor :math:`S(q, \omega)`. The intermediate +scattering function :math:`F(q, t)` is a correlation function of the Fourier components of +particle density whereas the current correlation function :math:`C_{\alpha\beta}(q, t)` +are a correlation function of the Fourier components of the particle current: -In the context of MDANSE, researchers calculate two essential components -of the correlation function: +.. math:: + + C_{\alpha\beta}(q, t) = \frac{1}{N} \langle j_{\alpha}(q, t) j_{\beta}(-q, 0) \rangle \qquad\qquad j_{\alpha}(q, t) = \sum_{l} v_{l\alpha}(t) \exp(iq\cdot r_l(t)) + +where :math:`\alpha, \beta = x, y` or :math:`z`. The particle currents +can be projected onto longitudinal and transverse components of the +:math:`q`-vector. The longitudinal and transverse particle current are: + +.. math:: + + j_{\mathrm{L}}(q, t) &= \sum_{l} (v_{l\alpha}(t) \cdot \hat{q})\hat{q} \, \exp(iq\cdot r_l(t)) \\ + j_{\mathrm{T}}(q, t) &= \sum_{l} [v_{l\alpha}(t) - (v_{l\alpha}(t) \cdot \hat{q})\hat{q}] \, \exp(iq\cdot r_l(t)) + +where :math:`\hat{q}` are unit vectors of :math:`q`. For isotropic systems, +the longitudinal and transverse particle current are uncorrelated and the +current correlation function tensor :math:`C_{\alpha\beta}(q, t)` +will depend only on two independent components so that we can write: + +.. math:: + + C_{\alpha\beta}(q, t) = \hat{q}_{\alpha}\hat{q}_{\beta} C_{\mathrm{L}}(q, t) + (\delta_{\alpha\beta} - \hat{q}_{\alpha}\hat{q}_{\beta}) C_{\mathrm{T}}(q, t) + +where the longitudinal and transverse current correlation functions are. + +.. math:: + + C_{\mathrm{L}}(q, t) = \frac{1}{N} \langle j_{\mathrm{L}}(q, t) \cdot j_{\mathrm{L}}(-q, 0) \rangle + +.. math:: + + C_{\mathrm{T}}(q, t) = \frac{1}{N} \langle j_{\mathrm{T}}(q, t) \cdot j_{\mathrm{T}}(-q, 0) \rangle + + +From the continuity equation we can obtain a relation between the +longitudinal current correlation and the dynamic structure factor. -- **Longitudinal Component:** This component is associated with density - fluctuations, offering insights into how particle or atom densities change - at specific locations within the disordered system over time. +.. math:: -- **Transverse Component:** The transverse component is linked to propagating - shear modes, helping researchers comprehend the relative displacements of - neighboring particles or atoms and the propagation of these shear modes - throughout the disordered material. + C_{\mathrm{L}}(q, \omega) = \frac{\omega^2}{Q^2} S(q, \omega) .. _dynamic-coherent-structure-factor: Dynamic Coherent Structure Factor ''''''''''''''''''''''''''''''''' -In materials science and condensed matter physics, dynamic coherent structure -factors are crucial. They enable a understanding of complex -particle or atom movements and interactions over time. These factors provide -invaluable insights into the dynamic behavior of materials, aiding researchers in -deciphering particle evolution and characterizing properties such as diffusion -rates, elasticity, and phase transitions. They play a pivotal role in enhancing -our understanding of system dynamics and significantly benefit research in these -fields. - In this analysis, MDANSE proceeds in two steps. First, it computes the partial and total intermediate coherent scattering function using equation :math:numref:`pfx69`. Then, the partial and total dynamic coherent structure @@ -335,51 +351,36 @@ factors are obtained by performing the Fourier Transformation, defined in Eq. :math:numref:`pfx61`, respectively on the total and partial intermediate coherent scattering functions. -**Coherent Intermediate Scattering Function Calculation:** -*MDANSE* computes the coherent intermediate scattering function on a -rectangular grid of equidistantly spaced points along the time-and the -:math:`q`-axis, respectively: +**Coherent intermediate scattering function**: .. math:: :label: pfx80 - {{F}_{\text{coh}}\left( {q_{m},k\Delta t} \right)\doteq{\sum\limits_{{I = 1},J\geq I}^{N_{\mathrm{species}}}\sqrt{n_{I}n_{J}\omega_{I,\text{com}}\omega_{I,\text{com}}}}{\overline{\left\langle {\rho_{I}\left( {{-q},0} \right)\rho_{J}\left( {q,k\Delta t} \right)} \right\rangle}}^{q},} - -where :math:`{k = 0}, \ldots, {N_{t} - 1}` and :math:`{m = 0}, \ldots, {N_{q} - 1}`. -:math:`N_t` is the number of time steps in the coordinate time series, -:math:`N_q` is a user-defined number of :math:`q`-shells, -:math:`N_{\mathrm{species}}` is the number of selected species, :math:`n_{I}` -is the number of atoms of species :math:`I`, :math:`\omega_{I}` the weight -for species :math:`I` (see Section :ref:`target_CN` for more details) -and :math:`{\rho_{I}( {q,k\Delta t})}`. The overline -:math:`{\overline{...}}^{q}` in Eq. :math:numref:`pfx80` denotes an average -over :math:`q`-vectors having *approximately* the same modulus + {{F}_{\text{coh}}\left( {q, t} \right)\doteq{\sum\limits_{{I = 1},J\geq I}^{N_{\mathrm{species}}}\sqrt{n_{I}n_{J}\omega_{I,\text{com}}\omega_{I,\text{com}}}}{\left\langle {\rho_{I}\left( {{-q},0} \right)\rho_{J}\left( {q, t} \right)} \right\rangle},} -**Fourier-Transformed Particle Density:** Below defines -the Fourier-transformed particle density for species :math:`I`: +where :math:`N_{\mathrm{species}}` is the number of selected species, :math:`n_{I}` +is the number of atoms , :math:`\omega_{I}` is the weight and +:math:`{\rho_{I}( {q, t})}` is the Fourier components of the particle density of species +:math:`I` .. math:: :label: pfx83 - {\rho_{I}{\left( {q,k\cdot\Delta t} \right) = \sum\limits_{\alpha}^{n_{I}}}\exp\left\lbrack {\mathit{iq}\cdot R_{\alpha}\left( {k\Delta t} \right)} \right\rbrack.} + {\rho_{I}{\left( {q, t} \right) = \sum\limits_{\alpha}^{n_{I}}}\exp\left\lbrack {\mathit{iq}\cdot R_{\alpha}\left( t \right)} \right\rbrack.} - -**q-Vectors on a Reciprocal Lattice:** Below describes the selection of :math:`q`-vectors on a lattice reciprocal to the MD box lattice. +In MDANSE, the DCSF is averaged over :math:`q`-vectors having *approximately* the same +modulus so that .. math:: - :label: pfx85 - - {{q_{m} = {q_{\mathit{\min}} + m}}\Delta q} + :label: pfx80 + F_{\text{coh}}\left( {Q_{m}, t} \right) = \overline{F_{\text{coh}}\left( {q_m, t} \right)}^{q_m} -The particle density must not change if jumps in the particle -trajectories due to periodic boundary conditions occur. In addition, the -*average* particle density (:math:`N/V`) must not change. +where :math:`Q_{m} \approx \vert q_{m} \vert`. -**Position Vector in the MD Cell** This can be achieved by choosing :math:`q`-vectors on a -lattice which is reciprocal to the lattice defined by the *MD* box. Let +**Reciprocal lattice q-vectors**: Let :math:`b_1`, :math:`b_2`, :math:`b_3` be the basis vectors -which span the *MD* cell. Any position vector in the *MD* cell can be +which span the MD cell. Any position vector in the MD cell can be written as .. math:: @@ -387,11 +388,10 @@ written as {{R = x^{'}}{b_{1} + y^{'}}{b_{2} + z^{'}}b_{3},} -Eq. :math:numref:`pfx86` defines the position vector in the MD cell. - -**Dual Basis Vectors:** with :math:`x'`, :math:`y'`, :math:`z'` having +so that it defines the position vector in the MD cell. +With :math:`x'`, :math:`y'`, :math:`z'` having values between :math:`0` and :math:`1` if :math:`R` is in the unit cell. -The primes indicate that the coordinates are box coordinates. A jump due +The primes indicate that the coordinates are fractional coordinates. A jump due to periodic boundary conditions can cause :math:`x'`, :math:`y'`, :math:`z'` to jump by :math:`\pm1`. The set of dual basis vectors :math:`b^1`, :math:`b^2`, :math:`b^3` is defined by @@ -402,30 +402,29 @@ the relation {b_{i}{b^{j} = \delta_{i}^{j}}.} -Eq. :math:numref:`pfx87` defines the dual basis vectors and -their relation to the basis vectors. - -**Selection of q-Vectors with Phase Changes:** If the q-vectors are now chosen as +and defines the dual basis vectors and their relation to the basis +vectors. If the :math:`q`-vectors are now chosen as .. math:: :label: pfx88 {{q = 2}\pi\left( {k{b^{1} + l}{b^{2} + m}b^{3}} \right),} -Describes the selection of :math:`q`-vectors with phase changes for -handling jumps in particle trajectories - -where :math:`k`, :math:`l`, :math:`m` are integer numbers, jumps in the particle trajectories +so that this selection of :math:`q`-vectors produces phase changes for +handling jumps in particle trajectories. Here :math:`k`, :math:`l`, :math:`m` +are integer numbers, jumps in the particle trajectories produce phase changes of multiples of :math:`2\pi` in the Fourier transformed -particle density, i.e. leave it unchanged. One can define a grid of +particle density, i.e. leave it unchanged. + +In MDANSE, One can define a grid of :math:`q`-shells or a grid of :math:`q`-vectors along a given direction or on a -given plane, giving in addition a *tolerance* for :math:`q`. *MDANSE* looks +given plane, giving in addition a *tolerance* for :math:`q`. MDANSE looks then for :math:`q`-vectors of the form given in Eq. :math:numref:`pfx88` whose moduli deviate within the prescribed tolerance from the equidistant :math:`q`-grid. From these :math:`q`-vectors only a maximum number per grid-point (called generically :math:`q`-shell also in the anisotropic case) is kept. -**Negative Coherent Scattering Lengths:** The :math:`q`-vectors can be generated isotropically, anisotropically or along +**Negative coherent scattering lengths**: The :math:`q`-vectors can be generated isotropically, anisotropically or along user-defined directions. The :math:`\sqrt{\omega_{I}}` may be negative if they represent normalized coherent scattering lengths, i.e. @@ -437,18 +436,17 @@ lengths, i.e. Defines the use of negative coherent scattering lengths for hydrogenous materials. Negative coherent scattering lengths occur in hydrogenous materials -since :math:`b_{\mathrm{H},\mathrm{coh}}` is negative [Ref20]_. - -When the default value of weights (:math:`b_{\mathrm{coherent}}`) is chosen for this +since :math:`b_{\mathrm{H},\mathrm{coh}}` is negative [Ref20]_. When the +default value of weights (``b_coherent``) is chosen for this analysis, the result will correspond to that of the equation :math:numref:`ntdsf-eq6` -from the :ref:`analysis-ndtsf`. +from the :ref:`neutron-dynamic-total-structure-factor`. .. _dynamic-incoherent-structure-factor: Dynamic Incoherent Structure Factor ''''''''''''''''''''''''''''''''''' -In this analysis, *MDANSE* proceeds in two steps. First, it computes +In this analysis, MDANSE proceeds in two steps. First, it computes the partial and total intermediate incoherent scattering function :math:`F_{\mathrm{inc}}(q, t)` using equation :math:numref:`pfx70`. Then, the partial and total dynamic incoherent structure factors are obtained by @@ -456,108 +454,58 @@ performing the Fourier Transformation, defined in Eq. :math:numref:`pfx61`, respectively on the total and partial intermediate incoherent scattering function. -**Computation of Incoherent Intermediate Scattering Function:** *MDANSE* computes the incoherent intermediate scattering function on a -rectangular grid of equidistantly spaced points along the time-and the -:math:`q`-axis, respectively: +**Incoherent intermediate scattering function**: .. math:: :label: pfx90 - {\text{F}_{\text{inc}}\left( {q_{m},k\Delta t} \right)\doteq{\sum\limits_{I = 1}^{N_{\mathrm{species}}}{n_{I}\omega_{I,\text{inc}}}}\text{F}_{I,\text{inc}}\left( {q_{m},k\Delta t} \right)} - + {\text{F}_{\text{inc}}\left( {q, t} \right)\doteq{\sum\limits_{I = 1}^{N_{\mathrm{species}}}{n_{I}\omega_{I,\text{inc}}}}\text{F}_{I,\text{inc}}\left( {q, t} \right)} -where :math:`{k = 0}, \ldots, {N_t - 1}` and :math:`{m = 0}, \ldots, {N_q - 1}`. :math:`N_t` -is the number of time steps in the coordinate time series, :math:`N_q` -is a user-defined number of :math:`q`-shells, :math:`N_{\mathrm{species}}` +where :math:`N_{\mathrm{species}}` is the number of selected species, :math:`n_I` the number of atoms of species :math:`n_I`, :math:`\omega_{I}` the weight for species :math:`I` -(see Section :ref:`target_CN` for more details) and :math:`{F_{I,\text{inc}}\left( {q_{m},k\Delta t} \right)}` +(see Section :ref:`target_CN` for more details) and :math:`{F_{I,\text{inc}}\left( {q, t} \right)}` is defined as: .. math:: :label: pfx92 - {\text{F}_{I,\mathrm{inc}}{\left( {q_{m},k\Delta t} \right) = \sum\limits_{\alpha = 1}^{n_{I}}}{\overline{\left\langle {\exp\left\lbrack {{-i}q\cdot R_{\alpha}(0)} \right\rbrack\exp\left\lbrack {iq\cdot R_{\alpha}(t)} \right\rbrack} \right\rangle}}^{q}.} - -The overline :math:`{\overline{...}}^{q}` in Eq. :math:numref:`pfx92` -denotes an average -over :math:`q`-vectors having *approximately* the same modulus -:math:`{{q_{m} = {q_{\mathit{\min}} + m}}\Delta q}`. The -particle density must not change if jumps in the particle -trajectories due to periodic boundary conditions occur. + {\text{F}_{I,\mathrm{inc}}{\left( {q_{m}, t} \right) = \sum\limits_{\alpha = 1}^{n_{I}}}{\left\langle {\exp\left\lbrack {{-i}q\cdot R_{\alpha}(0)} \right\rbrack\exp\left\lbrack {iq\cdot R_{\alpha}(t)} \right\rbrack} \right\rangle}.} - -**Selection of q-Vectors on a Reciprocal Lattice:** In addition, the -*average* particle density (:math:`N/V`) must not change. This can be achieved -by choosing :math:`q`-vectors on a lattice which is reciprocal to the lattice -defined by the *MD* box. Let :math:`b_1`, :math:`b_2`, -:math:`b_3` be the basis vectors which span the *MD* cell. Any -position vector in the *MD* cell can be written as +In MDANSE, the DISF is averaged over :math:`q`-vectors having *approximately* the same +modulus so that .. math:: - :label: pfx94 - - {{R = x^{'}}{b_{1} + y^{'}}{b_{2} + z^{'}}b_{3},} - -with :math:`x'`, :math:`y'`, :math:`z'` having values between :math:`0` and :math:`1` -if :math:`R` is in the unit cell. The primes indicate that -the coordinates are box coordinates. A jump due to periodic boundary -conditions causes :math:`x'`, :math:`y'`, :math:`z'` to jump by :math:`\pm 1`. -The set of dual basis vectors :math:`b^1`, :math:`b^2`, :math:`b^3` is defined by -the relation - -.. math:: - :label: pfx95 - - {b_{i}{b^{j} = \delta_{i}^{j}}.} - -If the :math:`q`-vectors are now chosen as + :label: pfx80 -.. math:: - :label: pfx96 + F_{\text{inc}}\left( {Q_{m}, t} \right) = \overline{F_{\text{inc}}\left( {q_m, t} \right)}^{q_m} - {{q = 2}\pi\left( {k{b^{1} + l}{b^{2} + m}b^{3}} \right),} - -where :math:`k`, :math:`l`, :math:`m`, are integer numbers, jumps in the particle trajectories -produce phase changes of multiples of :math:`2\pi` in the Fourier transformed -particle density, i.e. leave it unchanged. One can define a grid of -:math:`q`-shells or a grid of :math:`q`-vectors along a given direction or on a -given plane, giving in addition a *tolerance* for :math:`q`. *MDANSE* looks -then for :math:`q`-vectors of the form given in Eq. :math:numref:`pfx96` whose moduli -deviate within the prescribed tolerance from the equidistant :math:`q`-grid. -From these :math:`q`-vectors only a maximum number per grid-point (called -generically :math:`q`-shell also in the anisotropic case) is kept. -The :math:`q`-vectors can be generated isotropically, anisotropically or along -user-defined directions. - -When the default value of weights (:math:`{b^{2}}_{\mathrm{incoherent}}`) is chosen for this -analysis, the result will correspond to that of the equation :math:numref:`ntdsf-eq7` -from the :ref:`analysis-ndtsf`. +where :math:`Q_{m} \approx \vert q_{m} \vert`. .. _elastic-incoherent-structure-factor: Elastic Incoherent Structure Factor ''''''''''''''''''''''''''''''''''' -The *EISF* appears as the amplitude of the *elastic* line in the neutron +The elastic incoherent structure +factor (EISF) appears as the amplitude of the *elastic* line in the neutron scattering spectrum. Elastic scattering is only present for systems in which the atomic motion is confined in space, as for solids. To understand which information -is contained in the *EISF* we consider for simplicity a system where only one +is contained in the EISF we consider for simplicity a system where only one sort of atoms is visible to the neutrons. To a very good approximation this is the case for all systems containing a large amount of hydrogen atoms, as biological systems. Incoherent scattering from hydrogen dominates by far all other contributions. -**Van Hove Self-correlation Function:** The Elastic Incoherent Structure -Factor (*EISF*) is defined as the limit of the incoherent intermediate -scattering function for infinite time, +**The van Hove self-correlation function**: The EISF is defined as the +limit of the incoherent intermediate scattering function for infinite time .. math:: :label: pfx97 {\mathrm{EISF}(q)\doteq\lim\limits_{t\rightarrow\infty}\text{F}_{\mathrm{inc}}\left( {q,t} \right).} -Using the above definition of the *EISF* one can decompose the incoherent +Using the above definition of the EISF one can decompose the incoherent intermediate scattering function as follows: .. math:: @@ -573,10 +521,10 @@ now the Fourier transform it follows immediately that {\text{S}_{\text{inc}}{\left( {q,\omega} \right) = \mathrm{EISF}}(q)\delta{(\omega) + \text{S}_{\text{inc}}^{'}}\left( {q,\omega} \right).} -The *EISF* appears as the amplitude of the *elastic* line in the neutron +The EISF appears as the amplitude of the *elastic* line in the neutron scattering spectrum. Elastic scattering is only present for systems in which the atomic motion is confined in space, as for solids. To -understand which information is contained in the *EISF* we consider for +understand which information is contained in the EISF we consider for simplicity a system where only one sort of atoms is visible to the neutrons. To a very good approximation this is the case for all systems containing a large amount of hydrogen atoms, as biological systems. @@ -598,15 +546,15 @@ one can write: {\mathrm{EISF}(q) = b_{\text{inc}}^{2}{\int \mathrm{d}^{3}}r \, \exp\left\lbrack {\mathit{iq}\cdot r} \right\rbrack G_{\mathrm{s}}\left( {r,{t = \infty}} \right).} -The *EISF* gives the sampling distribution of the points in space in the +The EISF gives the sampling distribution of the points in space in the limit of infinite time. In a real experiment this means times longer -than the time which is observable with a given instrument. The *EISF* +than the time which is observable with a given instrument. The EISF vanishes for all systems in which the particles can access an infinite volume since :math:`G_{\mathrm{s}}(r, t)` approaches :math:`1/V` for large times. This is the case for molecules in liquids and gases. -**EISF Computation:** For computational purposes it is convenient to use the following -representation of the *EISF* [Ref21]_: +**EISF computation**: For computational purposes it is convenient to use the following +representation of the EISF [Ref21]_: .. math:: :label: pfx102 @@ -624,83 +572,57 @@ following expression for the elastic incoherent scattering function is {\mathrm{EISF}_{I}{(q) = \frac{1}{n_{I}}}{\sum\limits_{\alpha}^{n_{I}}\left\langle {|{\exp\left\lbrack {\mathit{iq}\cdot R_{\alpha}} \right\rbrack\left. {} \right|^{2}}} \right\rangle}.} This expression is derived from definition :math:numref:`pfx97` -of the *EISF* and expression :math:numref:`pfx70` for the +of the EISF and expression :math:numref:`pfx70` for the intermediate scattering function, using that for infinite time the relation .. math:: :label: pfx104 - {\left\langle {\exp\left\lbrack {{- \mathit{iq}}\cdot R_{\alpha}(0)} \right\rbrack\exp\left\lbrack {\mathit{iq}\cdot R_{\alpha}(t)} \right\rbrack} \right\rangle = \left\langle {|{\exp\left\lbrack {\mathit{iq}\cdot R_{\alpha}} \right\rbrack\left. {} \right|^{2}}} \right\rangle} + \lim\limits_{t\rightarrow\infty}{\left\langle {\exp\left\lbrack {{- \mathit{iq}}\cdot R_{\alpha}(0)} \right\rbrack\exp\left\lbrack {\mathit{iq}\cdot R_{\alpha}(t)} \right\rbrack} \right\rangle = \left\langle {|{\exp\left\lbrack {\mathit{iq}\cdot R_{\alpha}} \right\rbrack\left. {} \right|^{2}}} \right\rangle} -holds. In this way the computation of the *EISF* is reduced to the +holds. In this way the computation of the EISF is reduced to the computation of a static thermal average. We remark at this point that -the length of the *MD* trajectory from which the *EISF* is computed +the length of the MD trajectory from which the EISF is computed should be long enough to allow for a representative sampling of the conformational space. -**Grid Computation:** *MDANSE* allows one to compute the elastic incoherent structure factor -on a grid of equidistantly spaced points along the *q*-axis: +In MDANSE, the EISF is averaged over :math:`q`-vectors having *approximately* the same +modulus so that .. math:: - :label: pfx105 - - {\mathrm{EISF}\left( q_{m} \right)\doteq{\sum\limits_{I = 1}^{N_{\mathit{species}}}{n_{I}\omega_{I}\mathrm{EISF}_{I}\left( q_{m} \right)}} \qquad {m = 0}, \ldots, {N_{q} - 1.}} - -where :math:`N_q` is a user-defined number of :math:`q`-shells, the values for -:math:`q_m` are defined as - -.. math:: - :label: pfx106 - - {{q_{m} = {q_{\mathit{\min}} + m}}\Delta q} - -and for each species the following expression for the elastic -incoherent scattering function is: - -.. math:: - :label: pfx107 + :label: pfx80 - {\mathrm{EISF}_{I}{\left( q_{m} \right) = \frac{1}{n_{I}}}{\sum\limits_{\alpha}^{n_{I}}{\overline{\left\langle {|{\exp\left\lbrack {\mathit{iq}\cdot R_{\alpha}} \right\rbrack\left. {} \right|^{2}}} \right\rangle}}^{q}}.} + \mathrm{EISF}\left( {Q_{m}, t} \right) = \overline{\mathrm{EISF}\left( {q_m, t} \right)}^{q_m} -Here the symbol :math:`{\overline{...}}^{q}` -denotes an average over the *q*-vectors having the same modulus -:math:`q_m`. The program corrects the atomic input trajectories for -jumps due to periodic boundary conditions. +where :math:`Q_{m} \approx \vert q_{m} \vert`. .. _gaussian-dynamic-incoherent-structure-factor: Gaussian Dynamic Incoherent Structure Factor '''''''''''''''''''''''''''''''''''''''''''' - -The Gaussian Dynamic Incoherent Structure Factor is a concept used to study how -particles or atoms move independently within materials over time, with a focus -on their distribution. It's valuable in materials science and condensed matter -physics for understanding dynamic behavior at the atomic level. -**MSD Calculation:** The *MSD* can be related to the incoherent intermediate scattering +**Cumulant expansion**: The MSD can be related to the incoherent intermediate scattering function via the cumulant expansion [Ref11]_, [Ref22]_ .. math:: :label: pfx108 - {\text{F}_{\text{inc}}^{\mathrm{g}}{\left( {q,t} \right) = {\sum\limits_{I = 1}^{N_{\mathrm{species}}}{n_{I}\omega_{I,\text{inc}}}}}\text{F}_{I,\text{inc}}^{\mathrm{g}}\left( {q,t} \right)} - -where :math:`N_{\mathrm{species}}` is the number of selected species, :math:`n_I` -the number of atoms of species :math:`I`, :math:`\omega_{I,\mathrm{inc}}` the weight for -species \mathrm{I} (see Section :ref:`target_CN` for more details) and + {\text{F}_{\text{inc}}{\left( {q,t} \right) = {\sum\limits_{I = 1}^{N_{\mathrm{species}}}{n_{I}\omega_{I,\text{inc}}}}}\text{F}_{I,\text{inc}}\left( {q,t} \right)} .. math:: :label: pfx109 - {\text{F}_{I,\text{inc}}^{\mathrm{g}}{\left( {q,t} \right) = \frac{1}{n_{I}}}\sum\limits_{\alpha}^{n_{I}}\exp\left\lbrack {{- q^{2}}\rho_{\alpha,1}{(t) + q^{4}}\rho_{\alpha,2}(t)\mp\ldots} \right\rbrack.} - + {\text{F}_{I,\text{inc}}{\left( {q,t} \right) = \frac{1}{n_{I}}}\sum\limits_{\alpha}^{n_{I}}\exp\left\lbrack {{- q^{2}}\rho_{\alpha,1}{(t) + q^{4}}\rho_{\alpha,2}(t) + \ldots} \right\rbrack} -The cumulants :math:`\rho_{\alpha,k}(t)` are identified as +where :math:`N_{\mathrm{species}}` is the number of selected species, :math:`n_I` +the number of atoms of species :math:`I`, :math:`\omega_{I,\mathrm{inc}}` the weight for +species :math:`I` (see Section :ref:`target_CN` for more details). The cumulants +:math:`\rho_{\alpha,k}(t)` are identified as .. math:: - {\rho_{\alpha,1}{(t) = \left\langle {d_{\alpha}^{2}\left( {t;n_{q}} \right)} \right\rangle}} + {\rho_{\alpha,1}{(t) = \frac{1}{2!}\left\langle {d_{\alpha}^{2}\left( {t;n_{q}} \right)} \right\rangle}} .. math:: @@ -710,74 +632,56 @@ The cumulants :math:`\rho_{\alpha,k}(t)` are identified as :label: pfx112 {\vdots} -**Gaussian Approximation:** The vector :math:`n_q` is the unit vector +**Gaussian approximation**: The vector :math:`n_q` is the unit vector in the direction of :math:`q`. In the Gaussian approximation the above expansion is truncated after the -:math:`q^2`-term. For certain model systems like the ideal gas, the -harmonic oscillator, and a particle undergoing Einstein diffusion, this -is exact. For these systems the incoherent intermediate scattering -function is completely determined by the *MSD*. *MDANSE* allows one to -compute the total and partial incoherent intermediate scattering -function in the *Gaussian approximation* by discretizing equation -:math:numref:`pfx108`: +:math:`q^2`-term. .. math:: - :label: pfx113 - {\text{F}_{\text{inc}}^{\mathrm{g}}\left( {q_{m},k\Delta t} \right)\doteq{\sum\limits_{I = 1}^{N_{\mathit{species}}}{n_{I}\omega_{I,\text{inc}}\text{F}_{I,\text{inc}}^{\mathrm{g}}\left( {q_{m},k\Delta t} \right)}}} + {\text{F}_{I,\text{inc}}\left( {q,t} \right) \approx \text{F}_{I,\text{inc}}^{\mathrm{g}}{\left( {q,t} \right) = \frac{1}{n_{I}}}\sum\limits_{\alpha}^{n_{I}}\exp\left\lbrack {{- q^{2}}\rho_{\alpha,1}(t)} \right\rbrack} -where :math:`{k = 0}, \ldots, {N_t - 1}` and :math:`{m = 0}, \ldots ,{N_q - 1}`. +For certain model systems like the ideal gas, the +harmonic oscillator, and a particle undergoing Einstein diffusion, this +is exact. For these systems the incoherent intermediate scattering +function is completely determined by the MSD. -**Intermediate Scattering Function:** for each species the -following expression for the intermediate scattering function +**Intermediate scattering function**: For an isotropic system, the +following expression for the intermediate scattering function is obtained .. math:: :label: pfx114 - {\text{F}_{I,\alpha,\text{inc}}^{\mathrm{g}}{\left( {q_{m},k\Delta t} \right) = \frac{1}{n_{I}}}\sum\limits_{\alpha}^{n_{I}}\exp\left\lbrack {\frac{- \left( q_{m} \right)^{2}}{6}\Delta_{\alpha}^{2}\left( {k\Delta t} \right)} \right\rbrack \quad \mathrm{isotropic\ system}} + {\text{F}_{I,\alpha,\text{inc}}^{\mathrm{g}}{\left( {Q, t} \right) = \frac{1}{n_{I}}}\sum\limits_{\alpha}^{n_{I}}\exp\left\lbrack {\frac{- Q^{2}}{6}\Delta_{\alpha}^{2}\left( { t} \right)} \right\rbrack} .. math:: :label: pfx115 - {\text{F}_{I,\alpha,\text{inc}}^{\mathrm{g}}{\left( {q_{m},k\Delta t} \right) = \frac{1}{n_{I}}}\sum\limits_{\alpha}^{n_{I}}\exp\left\lbrack {\frac{- \left( q_{m} \right)^{2}}{2}\Delta_{\alpha}^{2}\left( {k\Delta t;n} \right)} \right\rbrack \quad \mathrm{isotropic\ system}} + {\text{F}_{I,\alpha,\text{inc}}^{\mathrm{g}}{\left( {Q, t} \right) = \frac{1}{n_{I}}}\sum\limits_{\alpha}^{n_{I}}\exp\left\lbrack {\frac{- Q^{2}}{2}\Delta_{\alpha}^{2}\left( { t;n} \right)} \right\rbrack} -:math:`N_t` is the total number of time steps in the coordinate time -series and :math:`N_q` is a user-defined number of :math:`q`-shells. The (:math:`q`, -:math:`t`)-grid is the same as for the calculation of the intermediate -incoherent scattering function (see `Dynamic Incoherent Structure -Factor <#_Dynamic_Incoherent_Structure>`__). The quantities :math:`\Delta_{\alpha}^{2}(t)` +where the quantities :math:`\Delta_{\alpha}^{2}(t)` and :math:`\Delta_{\alpha}^{2}\left( {t;n} \right)` are the mean-square displacements, defined in Equations :math:numref:`pfx14` and :math:numref:`pfx15`, respectively. -They are computed by using the algorithm described in the `Mean Square -Displacement <#_Theory_and_implementation_2>`__ section. *MDANSE* -corrects the atomic input trajectories for jumps due to periodic -boundary conditions. It should be noted that the computation of the +They are computed by using the algorithm described in the :ref:`analysis-msd` section. +It should be noted that the computation of the intermediate scattering function in the Gaussian approximation is much 'cheaper' than the computation of the full intermediate scattering function, :math:`F_{\mathrm{inc}}(q, t)`, since no averaging over different -:math:`q`-vectors needs to be performed. It is sufficient to compute a single -mean-square displacement per atom. +:math:`q`-vectors needs to be performed. .. _neutron-dynamic-total-structure-factor: Neutron Dynamic Total Structure Factor '''''''''''''''''''''''''''''''''''''' -The Neutron Dynamic Total Structure Factor is a term used in scientific -research, especially in neutron scattering experiments, to investigate how -particles or atoms within a material contribute to its overall structure and -dynamics. This factor provides valuable insights into how these components move -and interact over time. - -**Calculation of Partial Coherent Intermediate Scattering Functions and Dynamic Structure Factors:** -this is a combination of the dynamic coherent and the dynamic incoherent +**Partial coherent intermediate scattering functions and dynamic structure factors**: +This is a combination of the dynamic coherent and the dynamic incoherent structure factors. It is a fully neutron-specific analysis, where the coherent part of the intermediate scattering function is calculated -using the atomic coherent neutron scattering lengths -:math:`b_{\mathrm{coherent}}` and +using the atomic coherent neutron scattering lengths ``b_coherent`` and the incoherent one is calculated using the square of the atomic -incoherent neutron scattering lengths :math:`{b^{2}}_{\mathrm{incoherent}}`. Therefore, in +incoherent neutron scattering lengths ``b_incoherent2``. Therefore, in this analysis the weights option is not available. The partial coherent intermediate scattering functions @@ -789,21 +693,15 @@ same way as in the DCSF analysis, i.e.: .. math:: :label: ntdsf-eq1 - I_{\alpha\beta}^{\mathrm{coh}}(q,t) = \left| \frac{1}{\sqrt{N_{\alpha}N_{\beta}}}\sum_{i \in \alpha,j \in \beta}^{N_{\alpha},N_{\beta}}\left\langle \exp\left[- iq \cdot r_{i}(t_{0})\right] \exp \left[iq \cdot r_{j}(t_{0} + t)\right] \right\rangle_{t_0} \right|_{q} + I_{\alpha\beta}^{\mathrm{coh}}(q,t) = \frac{1}{\sqrt{N_{\alpha}N_{\beta}}}\sum_{i \in \alpha,j \in \beta}^{N_{\alpha},N_{\beta}}\left\langle \exp\left[- iq \cdot r_{i}(0)\right] \exp \left[iq \cdot r_{j}(t)\right] \right\rangle where :math:`\alpha` and :math:`\beta` refer to the chemical elements, :math:`N_{\alpha}` and :math:`N_{\beta}` are the respective number of atoms of each type, :math:`i` and :math:`j` are two specific atoms of type :math:`\alpha` and :math:`\beta`, respectively, and :math:`\mathbf{r}_{i}(0)` and :math:`\mathbf{r}_{j}(t)` are their -positions at the time origin and at the time :math:`t`, respectively. -The notation :math:`\left\langle \ldots \right\rangle_{t_0}` indicates an -average over all possible time origins :math:`t_{0}` and -:math:`|\ldots|_{q}` represents an average over all the -:math:`q`-vectors contributing to the corresponding -:math:`q`-bin. - -Similarly, the partial incoherent intermediate scattering functions +positions at the times :math:`0` and :math:`t`, respectively. Similarly, +the partial incoherent intermediate scattering functions :math:`I_{\alpha}^{\mathrm{inc}}(q,t)` and the partial incoherent dynamic structure factors :math:`S_{\alpha}^{\mathrm{inc}}(q,\omega)` are obtained as in the DISF analysis: @@ -811,10 +709,9 @@ the DISF analysis: .. math:: :label: ntdsf-eq2 - I_{\alpha}^{\mathrm{inc}}(q,t) = \left| \frac{1}{N_{\alpha}}\sum_{i \in \alpha}^{N_{\alpha}}\left\langle \exp\left[- iq \cdot r_{i}(t_{0})\right] \exp \left[iq \cdot r_{i}(t_{0} + t)\right] \right\rangle_{t_0} \right|_{q} + I_{\alpha}^{\mathrm{inc}}(q,t) = \frac{1}{N_{\alpha}}\sum_{i \in \alpha}^{N_{\alpha}}\left\langle \exp\left[- iq \cdot r_{i}(0)\right] \exp \left[iq \cdot r_{i}(t)\right] \right\rangle - -**Combination of Partial Contributions:** The main difference between +**Combination of partial contributions**: The main difference between this analysis and the DCSF and DISF analyses, apart from the fact that the coherent and incoherent contributions are calculated simultaneously, is the way the different @@ -839,12 +736,11 @@ calculated as: where :math:`c_{\alpha} = N_{\alpha} / N` and :math:`c_{\beta} = N_{\beta} / N` are the concentration numbers -for elements :math:`\alpha` and :math:`\beta`, respectively. - -These expressions correspond to the formalism and equations given in -[Ref47]_, chapter 1: “An introduction to neutron scattering” . +for elements :math:`\alpha` and :math:`\beta`, respectively. These +expressions correspond to the formalism and equations given in +[Ref47]_ - Chapter 1: “An introduction to neutron scattering” . -**Units Conversion:** +**Units conversion**: As in the MDANSE database the coherent and incoherent neutron scattering lengths are given in Å, the total intermediate scattering functions above will be given in Å\ :sup:`2`/sterad/atom. Therefore, multiplying @@ -857,7 +753,7 @@ On the other hand, the DISF and DCSF analyses use the standard weight normalization procedure implemented in MDANSE (see :ref:`param-normalize`). Therefore the total coherent intermediate scattering function returned by the DCSF analysis is (assuming that the chosen weights are -b_coherent): +``b_coherent``): .. math:: :label: ntdsf-eq6 @@ -865,7 +761,7 @@ b_coherent): I^{\mathrm{coh}}(q,t) = \frac{\sum_{\alpha\beta}^{n}{c_{\alpha}c_{\beta}b_{\alpha,\mathrm{coh}}b_{\beta,\mathrm{coh}}I_{\alpha\beta}^{\mathrm{coh}}(q,t)}}{\sum_{\alpha\beta}^{n}{c_{\alpha}c_{\beta}b_{\alpha,\mathrm{coh}}b_{\beta,\mathrm{coh}}}} and the incoherent intermedicate scattering function given by the DISF -analysis is (assuming that the chosen weights are b_incoherent2): +analysis is (assuming that the chosen weights are ``b_incoherent2``): .. math:: :label: ntdsf-eq7 @@ -880,7 +776,7 @@ Naturally, similar expressions apply to the dynamic structure factors, Structure Factor From Scattering Function ''''''''''''''''''''''''''''''''''''''''' -The "Structure Factor From Scattering Function" is a concept used in +The structure factor from scattering function is a concept used in scientific research, particularly in the field of neutron scattering experiments. It relates to how particles or atoms within a material contribute to its overall structural properties based on their scattering diff --git a/Doc/pages/structure.rst b/Doc/pages/structure.rst index 964f15e49e..40758cce90 100644 --- a/Doc/pages/structure.rst +++ b/Doc/pages/structure.rst @@ -27,7 +27,7 @@ This section contains the following plugins: Area Per Molecule ''''''''''''''''' -The Area Per Molecule (APM) analysis in Molecular Dynamics (MD) assesses the surface +The area per molecule (APM) analysis in molecular dynamics (MD) assesses the surface area occupied by each molecule within a given system. This tool plays a crucial role in comprehending molecular arrangement and interactions. Users can specify the molecule they wish to analyze. The APM analysis provides valuable insights into how molecules are @@ -43,7 +43,7 @@ to advancements in fields like biophysics and structural biology. Coordination Number ''''''''''''''''''' -In chemistry, the Coordination Number (CN) is the total number of neighbors +In chemistry, the coordination number (CN) is the total number of neighbors of a central atom in a molecule or ion. CN plays a vital role in the analysis of complex molecular systems in simulations, serving several key purposes: @@ -80,7 +80,7 @@ defined for species :math:`I` defined as the number of atoms of species :math:`I found in a shell of width :math:`\mathrm{d}r` at a distance :math:`r` of the center of gravity of the group of atom :math:`g`. -*MDANSE* allows one to compute the *CN* on a set of equidistantly spaced +MDANSE allows one to compute the CN on a set of equidistantly spaced distances at different times .. math:: @@ -105,7 +105,7 @@ to intramolecular and intermolecular distances only. Secondly, these equations can be averaged over the selected frames providing a time averaged intra and intermolecular *CN*. Finally, the same equations (time-dependent and time-averaged) can be integrated over r to provide a -cumulative *CN*. *MDANSE* computes all these variations. +cumulative CN, MDANSE computes all these variations. .. _density-profile: @@ -113,12 +113,12 @@ cumulative *CN*. *MDANSE* computes all these variations. Density Profile ''''''''''''''' -The Density Profile analysis in MDANSE calculates the spatial +The density profile analysis in MDANSE calculates the spatial distribution of particles or molecules along a specified axis within a simulation box. This analysis provides valuable insights into how the density of particles or molecules varies across the system along the chosen axis. By dividing the axis into segments or bins and specifying the size of each bin -using the parameter :math:`dr`, the Density Profile reveals how particles are +using the parameter :math:`dr`, the density profile reveals how particles are distributed within the system. It is a useful tool for understanding the spatial arrangement and concentration of particles, making it valuable for identifying regions of interest and tracking changes over time in molecular simulations. @@ -128,7 +128,7 @@ regions of interest and tracking changes over time in molecular simulations. Eccentricity '''''''''''' -Eccentricity analysis in *MDANSE* quantifies how spherical a system is and +Eccentricity analysis in MDANSE quantifies how spherical a system is and can be used to observe how the geometry of the system changes over time. The eccentricity of a selection of atom is calculated using the equation @@ -145,7 +145,7 @@ aspherical selection of atoms will have a eccentricity approaching 1. Molecular Trace ''''''''''''''' -Molecular Trace in MDANSE pertains to a calculation or property +Molecular trace in MDANSE pertains to a calculation or property related to the analysis of molecular structures within the context of neutron scattering experiments or molecular dynamics simulations. The "resolution" parameter in this context determines the level of detail with which molecular @@ -157,7 +157,7 @@ overview of molecular behavior. The Molecular Trace calculation is a valuable tool for investigating the movement and behavior of molecular components in complex systems. -In the context of Molecular Trace analysis, molecular structures are often +In the context of molecular trace analysis, molecular structures are often represented and analyzed in terms of grid points, where each point corresponds to a specific location within the molecular system. The resolution parameter controls the spacing and granularity of these grid points, influencing the @@ -169,7 +169,7 @@ detail of the analysis. Pair Distribution Function '''''''''''''''''''''''''' -The Pair Distribution Function (*PDF*) is an example of a pair +The pair distribution function (PDF) is an example of a pair correlation function, which describes how, on average, the atoms in a system are radially packed around each other. This proves to be a particularly effective way of describing the average structure of @@ -178,14 +178,14 @@ liquids, where there is continual movement of the atoms and a single snapshot of the system shows only the instantaneous disorder, it is extremely useful to be able to deal with the average structure. -The *PDF* is useful in other ways. For example, it is something that can +The PDF is useful in other ways. For example, it is something that can be deduced experimentally from x-ray or neutron diffraction studies, thus providing a direct comparison between experiment and simulation. It can also be used in conjunction with the interatomic pair potential function to calculate the internal energy of the system, usually quite accurately. -Mathematically, the *PDF* can be computed using the following formula: +Mathematically, the PDF can be computed using the following formula: .. math:: :label: pfx121 @@ -196,7 +196,7 @@ where :math:`N_{\mathrm{species}}` is the number of selected species, :math:`n_I and :math:`n_J` are respectively the numbers of atoms of species :math:`I` and :math:`J`, :math:`\omega_I` and :math:`\omega_J` respectively the weights for species :math:`I` and :math:`J` (see Section `Coordination Number`_ for more details) and -:math:`\mathrm{PDF}_{\mathit{\alpha\beta}}(r)` is the partial *PDF* for :math:`I` and :math:`J` species that can be defined as: +:math:`\mathrm{PDF}_{\mathit{\alpha\beta}}(r)` is the partial PDF for :math:`I` and :math:`J` species that can be defined as: .. math:: :label: pfx123 @@ -208,15 +208,15 @@ where :math:`\rho_J` is the density of atom of species :math:`J` and a shell of width :math:`\mathrm{d}r` at distance :math:`r` of the atom :math:`\alpha` of species :math:`I`. -From the computation of *PDF*, two related quantities are also calculated; -the Radial Distribution Function (*RDF*), defined as +From the computation of PDF, two related quantities are also calculated; +the radial distribution function (RDF), defined as .. math:: :label: pfx125 {\mathrm{RDF}{(r) = 4}\pi r^{2}\rho_{0}\mathrm{PDF}(r),} -and the Total Correlation Function (*TCF*), defined as +and the total correlation function (TCF), defined as .. math:: :label: pfx126 @@ -229,10 +229,10 @@ system and :math:`V` the volume of the simulation. All these quantities are initially calculated as intramolecular and intermolecular parts for each pair of atoms, which are then added to -create the total *PDF*/*RDF*/*TCF* for each pair of atoms, as well as the +create the total PDF/RDF/TCF for each pair of atoms, as well as the total intramolecular and total intermolecular values. Lastly, the total -functions are computed. Please note, however, that in the case of *TCF*, -the below set of equations has been chosen, which will return results +functions are computed. Please note, however, that in the case of TCF, +the below set of equations have been chosen, which will return results that differ from those of nMOLDYN. .. math:: @@ -256,7 +256,7 @@ that differ from those of nMOLDYN. Root Mean Square Deviation '''''''''''''''''''''''''' -The Root Mean-Square Deviation (*RMSD*) is perhaps the most popular estimator +The Root mean-square deviation (RMSD) is perhaps the most popular estimator of structural similarity. It quantifies differences between two structures by measuring the root mean-square of atomic position differences, revealing insights into their structural dissimilarities. It is a numerical measure of @@ -266,20 +266,19 @@ the difference between two structures. It can be defined as: .. math:: :label: pfx131 - {\mathrm{RMSD}{\left( {n\Delta t} \right) = \sqrt{\frac{\sum\limits_{\alpha}^{N_{\alpha}}\vert {\mathbf{r}_{\alpha}{(n\Delta t) - \mathbf{r}_{\alpha}}(n_{\mathrm{ref}}\Delta t)} \vert^{2}}{N_{\alpha}}}} \qquad {n = 0}, \ldots, {N_{t} - 1}} + {\mathrm{RMSD}{\left( {t} \right) = \sqrt{\frac{\sum\limits_{\alpha}^{N_{\alpha}}\vert {\mathbf{r}_{\alpha}{(t) - \mathbf{r}_{\alpha}}(t_{\mathrm{ref}})} \vert^{2}}{N_{\alpha}}}}} -where :math:`N_{t}` is the number of frames, :math:`\mathrm{\Delta}t` -is the time step, :math:`N_{\alpha}` is the number of selected atoms of -the system and :math:`\mathbf{r}_{\alpha}(n\Delta t)` and -:math:`\mathbf{r}_{\alpha}(n_{\mathrm{ref}}\Delta t)` -are respectively the position of atom :math:`\alpha` at time :math:`n\Delta t` and :math:`n_{\mathrm{ref}}\Delta t` where :math:`n_{\mathrm{ref}}` is -a reference frame usually chosen as the zeroth frame of the simulation. +where :math:`N_{\alpha}` is the number of selected atoms of +the system and :math:`\mathbf{r}_{\alpha}(t)` and +:math:`\mathbf{r}_{\alpha}(t_{\mathrm{ref}})` +are respectively the position of atom :math:`\alpha` at time :math:`t` and :math:`t_{\mathrm{ref}}` where :math:`t_{\mathrm{ref}}` is +a reference time usually chosen as the zeroth time of the simulation. -Typically, *RMSD* is used to quantify the structural evolution of the +Typically, RMSD is used to quantify the structural evolution of the system during the simulation. It can provide precious information about the system especially if it reached equilibrium or conversely if major structural changes occurred during the simulation. MDANSE calculates the -*RMSD* of individual atoms types, for example, the *RMSD* of the oxygen +RMSD of individual atoms types, for example, the RMSD of the oxygen atoms in addition to the RMSD of all atoms of the system. .. _root-mean-square-fluctuation: @@ -287,12 +286,12 @@ atoms in addition to the RMSD of all atoms of the system. Root Mean Square Fluctuation '''''''''''''''''''''''''''' -Root Mean Square Fluctuation (*RMSF*) assesses how the positions of atoms or -molecules within a system fluctuate over time. Specifically, *RMSF* measures the +Root mean square fluctuation (RMSF) assesses how the positions of atoms or +molecules within a system fluctuate over time. Specifically, RMSF measures the average magnitude of deviations or fluctuations in atomic positions from their mean positions during a simulation. -*RMSF* analysis is valuable for understanding the flexibility and stability of +RMSF analysis is valuable for understanding the flexibility and stability of molecules within a simulation, providing insights into regions where atoms or groups of atoms exhibit significant fluctuations. This information can be crucial for studying the dynamic behavior of biomolecules, protein-ligand interactions, @@ -304,27 +303,26 @@ or any molecular system subject to temporal variations. Radius Of Gyration '''''''''''''''''' -Radius Of Gyration (*ROG*) is calculated as a root (atomic mass weighted) mean +Radius of gyration (ROG) is calculated as a root (atomic mass weighted) mean square distance of the components of a system relative to either its centre of -mass or a given axis of rotation. The *ROG* serves as a quantitative +mass or a given axis of rotation. The ROG serves as a quantitative measure which can be used to characterize the spatial distribution of a system such as a molecule or a cluster of atoms. -In MDANSE *ROG* is calculated relative to the systems centre of mass. +In MDANSE, ROG is calculated relative to the systems centre of mass. It can be defined as: .. math:: :label: pfx134 - {\mathrm{ROG}{({n\Delta t}) = \sqrt{\frac{\sum\limits_{i}^{N}m_{i}\vert {\mathbf{r}_{i}{(n\Delta t) - \mathbf{r}_{\mathrm{CM}}}(n\Delta t)} \vert^{2}}{\sum\limits_{i}^{N}m_{i}}}} \qquad {n = 0}, \ldots, {N_{t} - 1}} + {\mathrm{ROG}{({n\Delta t}) = \sqrt{\frac{\sum\limits_{i}^{N}m_{i}\vert {\mathbf{r}_{i}{(t) - \mathbf{r}_{\mathrm{CM}}}(t)} \vert^{2}}{\sum\limits_{i}^{N}m_{i}}}}} -where :math:`N_{t}` is the number of frames, :math:`\mathrm{\Delta}t` -is the time step, :math:`N` is the number of atoms of the system, -:math:`\mathbf{r}_{i}(n\Delta t)` are the positions of the -atoms :math:`i`, :math:`\mathbf{r}_{\mathrm{CM}}(n\Delta t)` is the centre of mass of -the system and :math:`n\Delta t` is the time of the simulation. +where :math:`N` is the number of atoms of the system, +:math:`\mathbf{r}_{i}(t)` are the positions of the +atoms :math:`i`, :math:`\mathbf{r}_{\mathrm{CM}}(t)` is the centre of mass of +the system and :math:`t` is the time of the simulation. -*ROG* can be used to describe the overall spread of the molecule and +ROG can be used to describe the overall spread of the molecule and as such is a good measure for the molecule compactness. For example, it can be useful when monitoring folding process of a protein. @@ -334,14 +332,14 @@ it can be useful when monitoring folding process of a protein. Solvent Accessible Surface '''''''''''''''''''''''''' -The Solvent Accessible Surface calculation involves defining the surface +The solvent accessible surface calculation involves defining the surface accessibility of molecules or atoms by creating a mesh of points. The number of points is determined by the field discussed, influencing the level of detail in the surface representation. Essentially, a higher density of points leads to a finer-grained representation, capturing smaller surface features and intricacies. -**Probe Radius**: Measured in nanometers, the probe radius is a crucial +**Probe radius**: Measured in nanometers, the probe radius is a crucial parameter influencing the precision of the calculation. Smaller probe radii provide a more detailed and assessment of the molecular surface area, often resulting in a larger reported surface @@ -353,7 +351,7 @@ area due to increased sensitivity to surface features. Static Structure Factor ''''''''''''''''''''''' -The **Static Structure Factor** analysis offers a convenient method to +The static structure factor analysis offers a convenient method to calculate the static coherent structure factor, represented as :math:`S(q)`, where :math:`S(q) = F_{\mathrm{coh}}(q, t = 0)`. This factor is fundamental for gaining insights into the ordered arrangements of particles within a material. @@ -387,12 +385,12 @@ molecular structures and dynamics. Xray Static Structure Factor '''''''''''''''''''''''''''' -MDANSE's Xray Static Structure Factor analysis is tailored for neutron +MDANSE's xray static structure factor analysis is tailored for neutron and X-ray scattering experiments in material science. It systematically investigates material structural properties by analyzing particle distribution and ordering. Researchers gain precise insights into fundamental aspects like atomic spacing and ordered patterns. MDANSE -provides fine-grained control over ":math:`r` values" and ":math:`q` values," enabling +provides fine-grained control over ":math:`r`-values" and ":math:`q`-values," enabling customization for probing specific material structural characteristics. This tool is invaluable for advancing scientific and industrial research, especially in neutron scattering experiments. diff --git a/Doc/pages/trajectory.rst b/Doc/pages/trajectory.rst index 761e5e583e..3b2213fd9b 100644 --- a/Doc/pages/trajectory.rst +++ b/Doc/pages/trajectory.rst @@ -1,9 +1,12 @@ + +.. _trajectory-converters: + Trajectory Converters ===================== Below is the list of converters present in MDANSE. These converters allow for the -outputs of a variety of MD simulation software to be able to be used in -MDANSE by converting the various file formats to the HDF format. These trajectory +outputs of a variety of MD simulation packages to be used in +MDANSE by converting the various file formats to the MDT format. These trajectory converters convert positions and other vital information such as the unit cell parameters. @@ -18,7 +21,18 @@ information such as the unit cell parameters. - DL_POLY - Gromacs - LAMMPS +- MDAnalysis +- MDTraj - VASP - CHARMM - NAMD -- XPLOR \ No newline at end of file +- XPLOR + +The MDANSE MD engine specific converters were developed to convert +specific trajectory formats outputted by those MD engines. If you are +unable to find the MD package you used or if you had dumped the +trajectory to a format not support by that particular +converter, we recommend trying the ASE, MDAnalysis or MDTraj converters +which may support the file format you need to convert. These general +trajectory converters utilise their respective libraries to read MD +trajectory files and convert them to MDT. diff --git a/Doc/pages/workflow.rst b/Doc/pages/workflow.rst index f9a4bfdb49..0713a53b11 100644 --- a/Doc/pages/workflow.rst +++ b/Doc/pages/workflow.rst @@ -11,11 +11,11 @@ analysis calculation and (3) results plotting. 1. Trajectory conversion ------------------------ To load a trajectory into MDANSE and run an analysis calculation -the trajectory must be in the MDANSE trajectory format, saved as a HDF file. +the trajectory must be in the MDANSE trajectory format (MDT). Most likely your trajectory is in whatever format was output by your preferred Molecular Dynamics simulation software, and you need to convert it first. Once you have converted your -trajectory to the MDANSE HDF format, you can use it as input for all kinds of +trajectory to the MDANSE MDT format, you can use it as input for all kinds of analysis. See also :ref:`trajectory-converters`. 2a. Analysis parameters @@ -57,25 +57,23 @@ type of analysis performed. Output files ^^^^^^^^^^^^ All the output arrays created in the analysis are written to the filesystem in the -format chosen by the user. (If you intend to continue visualising the results within -the MDANSE_GUI, you will need to use the HDF5 format. If, however, you were planning +format chosen by the user. If you intend to continue visualising the results within +the MDANSE_GUI, you will need to use the MDAFormat. If, however, you were planning to process the results further using other software, then you will need to pick -the ASCII output. See also :ref:`param-output-files`) +the TextFormat output. See also :ref:`param-output-files`. 2b. Analysis results --------------------- The analysis jobs are run in steps, iterating over each part of the trajectory. - The iterations over steps will produce partial results. This is where the specific equations described in the documentation of an analysis type are applied. -The partial results will be combined into the final result. - -The partial properties are calculated, typically per atom type, -or per pair of atom types and are combined into the total result. +The partial results will be combined into the final result. The partial +properties are calculated, typically per atom type, or per pair of atom +types and are combined into the total result. 3. Plotting ----------- -If the HDF5 format was chosen for the analysis job output file, the +If the MDAFormat was chosen for the analysis job output file, the file can then be opened in the MDANSE_GUI and plotted. As the MDANSE_GUI plotting is built on the matplotlib library many options found in the matplotlib are available in MDANSE_GUI. Additionally as the analysis diff --git a/MDANSE/Src/MDANSE/Framework/Jobs/CurrentCorrelationFunction.py b/MDANSE/Src/MDANSE/Framework/Jobs/CurrentCorrelationFunction.py index b946722e74..c1760674e7 100644 --- a/MDANSE/Src/MDANSE/Framework/Jobs/CurrentCorrelationFunction.py +++ b/MDANSE/Src/MDANSE/Framework/Jobs/CurrentCorrelationFunction.py @@ -52,7 +52,7 @@ class CurrentCorrelationFunction(IJob): category = ( "Analysis", - "Dynamics", + "Scattering", ) ancestor = ["hdf_trajectory", "molecular_viewer"] diff --git a/README.md b/README.md index 6c15c5995c..4ce685a51d 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,13 @@ To do this, MDANSE reads trajectories created with MD simulation software such as CASTEP, VASP, DMOL, Gromacs, DL_POLY, CHARMM, LAMMPS, PBD, DFTB etc., and provides both a graphical user interface (GUI) and a command line interface. -This project is built on the development published previously: \ -G. Goret, B. Aoun, E. Pellegrini, "MDANSE: An Interactive Analysis Environment for Molecular Dynamics Simulations", -J Chem Inf Model. 57(1):1-5 (2017). +This MDANSE project has been published previously in: \ +[G. Goret, B. Aoun, E. Pellegrini, "MDANSE: An Interactive Analysis Environment for Molecular Dynamics Simulations", +J. Chem. Inf. Model. 2017, 57, 1, 1–5](https://doi.org/10.1021/acs.jcim.6b00571). ## Version information -This is the 2.x branch of MDANSE, which consists of two Python packages, MDANSE (the analysis code) and MDANSE_GUI (the user interface). The final version in the 1.5.x series can still be found in the **legacy** branch, but is not being actively developed. +This is the 2.x branch of MDANSE, which consists of two Python packages, MDANSE (the analysis code) and MDANSE_GUI (the graphical user interface). The final version in the 1.5.x series can still be found in the **legacy** branch, but is not being actively developed. The current version of MDANSE is currently still at the _beta_ stage. You can help it advance to the official release stage by reporting problems you experience while using MDANSE. @@ -60,7 +60,7 @@ python3 -m pip install "git+https://github.com/ISISNeutronMuon/MDANSE@protos#egg The typical workflow of MDANSE: -1. Convert a trajectory from the file format generated by an MD simulation software into the MDANSE trajectory format, +1. Convert a trajectory from the file format generated by an MD simulation software into the MDANSE trajectory format (MDT), 2. Load the converted trajectory into MDANSE, 3. Perform an analysis, 4. Check the results with the plotter. @@ -70,12 +70,12 @@ The most complete user documentation of MDANSE can be found on [our Read the Doc At the same time, it is still possible to access the original **[MDANSE User Guide](https://epubs.stfc.ac.uk/work/51935555)**. Other information including example scripts can be found on the [MDANSE website](https://www.isis.stfc.ac.uk/Pages/MDANSEproject.aspx) -while the most recent tutorials are stored in the [MDANSE examples repository](https://github.com/ISISNeutronMuon/MDANSE-Examples). +while the most recent tutorials are stored in the [MDANSE-Examples repository](https://github.com/ISISNeutronMuon/MDANSE-Examples). ## What can MDANSE do? Firstly, MDANSE can read the output of MD simulation software. It does this by providing converters for different file formats -into an .MDT file (HDF format), which is then used for all calculations. The following MD packages are supported: +into an MDT file (HDF format), which is then used for all calculations. The following MD packages are supported: - CASTEP - CHARMM @@ -91,6 +91,8 @@ into an .MDT file (HDF format), which is then used for all calculations. The fol - VASP - XPLOR - ASE +- MDAnalysis +- MDTraj The converted trajectory can then be loaded into MDANSE, where it can be visualised and animated. Then, various properties can be calculated from the positions and velocities of atoms. @@ -159,8 +161,8 @@ be found on [our Read the Docs page](https://mdanse.readthedocs.io/en/protos). If you used MDANSE in your research, please cite the following paper: ->MDANSE: An Interactive Analysis Environment for Molecular Dynamics Simulations. -G. Goret, B. Aoun, E. Pellegrini. J Chem Inf Model. (2017) 57(1):1-5. +>[G. Goret, B. Aoun, E. Pellegrini, "MDANSE: An Interactive Analysis Environment for Molecular Dynamics Simulations", +J. Chem. Inf. Model. 2017, 57, 1, 1–5](https://doi.org/10.1021/acs.jcim.6b00571) ## License @@ -172,14 +174,13 @@ information. MDANSE started as a fork of [version 3 of the nMOLDYN program](https://github.com/khinsen/nMOLDYN3). nMOLDYN was originally developed by Gerald Kneller in 1995 and subsequently also by Konrad Hinsen, Tomasz Rog, -Krzysztof Murzyn, Slawomir Stachura, and Eric Pellegrini. MDANSE includes most of the code of nMOLDYN3, and also code -from the libraries [MMTK](https://github.com/khinsen/MMTK), [ScientificPython](https://github.com/khinsen/ScientificPython) -and [MDTraj](https://github.com/mdtraj/mdtraj). +Krzysztof Murzyn, Sławomir Stachura, and Eric Pellegrini. MDANSE includes most of the code of nMOLDYN3, and also code +from the libraries [MMTK](https://github.com/khinsen/MMTK) and [ScientificPython](https://github.com/khinsen/ScientificPython). For more information see: ->nMoldyn 3: Using task farming for a parallel spectroscopy-oriented analysis of molecular dynamics simulations. -K. Hinsen, E. Pellegrini, S. Stachura, G.R. Kneller J. Comput. Chem. (2012) 33:2043-2048 [https://doi.org/10.1002/jcc.23035][https://doi.org/10.1002/jcc.23035]. +>[K. Hinsen, E. Pellegrini, S. Stachura, G. R. Kneller, "nMoldyn 3: Using task farming for a parallel spectroscopy-oriented analysis of molecular dynamics simulations", +J. Comput. Chem. 2012, 33, 2043–2048](https://doi.org/10.1002/jcc.23035) We are grateful to all the people who have helped in some way or another to improve nMOLDYN and/or MDANSE along those years. Apart from the main developers mentioned above, we would like to acknowledge explicitly the contributions done in the past