Merge pull request #636 from ISISNeutronMuon/chi/docs-update-3

Documentation update: new converged results section

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 <https://www.isis.stfc.ac.uk/Pages/MDANSEproject.aspx>`_ | `MDANSE GitHub Page <https://github.com/ISISNeutronMuon/MDANSE>`_
 
-**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 <https://doi.org/10.1021/acs.jcim.6b00571>`_.
 
 
 .. raw:: html
@@ -63,18 +62,19 @@ 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
    :hidden:
    :caption: ⚛️ How-To Guides
 
    pages/H_start
+   pages/H_conv
    pages/H_cli
    pages/H_gui
    pages/gui

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.

Doc/pages/H_start.rst

@@ -1,28 +1,24 @@
+.. _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:
 
 .. code-block:: bash
 
    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,26 +59,26 @@ 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:
 
 .. code-block:: bash
 
    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