Documentation Review and Suggestions

AUTHORS

@@ -4,13 +4,15 @@ MDANSE project has been created by:
 
 MDANSE source code is currently developed by
 
-* Eric Pellegrini
+* Maciej Bartkowiak
+* Chi Cheng
 * Sanghamitra Mukhopadhyay
-* Rastislav Turanyi
 
 MDANSE former contributors:
 
+* Eric Pellegrini
 * Bachir Aoun
 * Gael Goret
 * Remi Perenon
+* Rastislav Turanyi
 

CHANGELOG

@@ -1,3 +1,10 @@
+version 2.0.0 - 2024-02-15
+--------------------------
+* CHANGED programming language to Python 3
+* CHANGED GUI library to Qt
+* REMOVED NetCDF4 support
+* ADDED ASE trajectory converter for native ASE trajectories and other formats
+* CHANGED the formula for the Position Autocorrelation Function
 
 version 1.5.2
 --------------

README.md → Doc/README.md

@@ -2,7 +2,7 @@
 
 ## Molecular Dynamics Analysis for Neutron Scattering Experiments
 
-MDANSE is a python application designed for computing neutron observables from molecular dynamics (MD) trajectories that can 
+MDANSE is a Python application designed for computing neutron observables from molecular dynamics (MD) trajectories. The results can 
 be directly compared with neutron scattering experiments, particularly inelastic and quasi-elastic neutron scattering 
 spectroscopies.
 
@@ -22,12 +22,22 @@ The current version of MDANSE is currently still at the _alpha_ stage. Once the
 
 The untested version of MDANSE can be downloaded from GitHub Actions as a Python wheel. There is one wheel for the main code ('MDANSE'), platform depenedent, and another for the GUI ('MDANSE_GUI'). Once downloaded, they can be installed by typing `pip install MDANSE-*.whl`. The GUI script can be run using the `mdanse_gui` command (`mdanse_gui.exe` on windows).
 
-The typical workflow will look as follows:
+As an alternative, it is possible to install MDANSE directly from the GitHub repository by typing
 
-1. Convert a trajectory from the file format generated by an MD simulation software into a NetCDF format (File>Trajectory conveters)
-2. Load the converted trajectory into MDANSE (File>Load data)
-3. Perform an analysis of choice (through the Plugins panel)
-4. Check the results with the plotter
+python3 -m pip install  "git+https://github.com/ISISNeutronMuon/MDANSE@protos#egg=MDANSE&subdirectory=MDANSE"
+
+for the main part of the code, and
+
+python3 -m pip install  "git+https://github.com/ISISNeutronMuon/MDANSE@protos#egg=MDANSE_GUI&subdirectory=MDANSE_GUI"
+
+for the GUI.
+
+The typical workflow of MDANSE:
+
+1. Convert a trajectory from the file format generated by an MD simulation software into the MDANSE trajectory format,
+2. Load the converted trajectory into MDANSE,
+3. Perform an analysis,
+4. Check the results with the plotter.
 
 
 The most complete user documentation of MDANSE can be found on [our Read the Docs page](https://mdanse.readthedocs.io/en/protos). At the same time, it is still possible to access the original **[MDANSE User Guide](https://epubs.stfc.ac.uk/work/51935555)**.
@@ -36,8 +46,8 @@ Other information including example scripts can be found on the [MDANSE website]
 
 ## What can MDANSE do?
 
-Firstly, MDANSE can interface with MD simulation software. It does this by providing converters for proprietary file formats
-into MMTK-style NetCDF format, which is then used for all calculations. The following MD packages are supported:
+Firstly, MDANSE can interface with 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:
 
 - CASTEP
 - CHARMM
@@ -52,11 +62,11 @@ into MMTK-style NetCDF format, which is then used for all calculations. The foll
 - PDB
 - VASP
 - XPLOR
+- ASE
 
 The converted trajectory can then be loaded into MDANSE, where it can be visualised via the Molecular Viewer and animated.
-Various trajectory variables (positions, velocities, and forces) can also be plotted for each particle. Then, if the 
-trajectory is as expected, various properties can be calculated, which can be compared with neutron (or, some, with X-ray)
-experimental data, or used as new data to draw conclusions from. The following properties can be computed:
+Various trajectory variables (positions, velocities, and forces) can also be plotted for each particle. Then, various properties can be calculated, which can be compared with neutron (or, for some analysis types, with X-ray)
+experimental data, or used as a prediction of results of a potential experiment. The following properties can be computed:
 
 <details><summary>Dynamics</summary><ul>
 <li>Angular correlation</li>
@@ -93,7 +103,7 @@ experimental data, or used as new data to draw conclusions from. The following p
 <li>Solvent Accessible Surface</li>
 <li>Spatial Density</li>
 <li>Static Structure Factor</li>
-<li>Voronoi</li>
+<li>Voronoi (volume per atom)</li>
 <li>X-Ray Static Structure Factor</li>
 </ul></details>
 
@@ -102,13 +112,17 @@ experimental data, or used as new data to draw conclusions from. The following p
 <li>Temperature</li>
 </ul></details>
 
-Each of these analyses can be configured in various ways. For example, the frames that are used can be changed, certain
-atoms can be specified to be the only ones for which the property is computed, or specified atoms can be substituted with
-different elements/isotopes. Finally, their results can be outputted in a NetCDF file, an HDF5 file, or a set of DAT 
-files, and those can then be plotted directly in MDANSE.
+Each of these analyses can be controlled using a number of parameters. For example, the user can select a subset of trajectory frames or a subset of atoms on which to perform the calculation, or specified atoms can be substituted with
+different elements/isotopes. Finally, their results can be saved in an MDA file (HDF5 format), or a set of DAT files (text format), and those can then be plotted directly in MDANSE.
 
 More detailed information on how MDANSE works, what it can do, and the science can all be found on [our Read the Docs page](https://mdanse.readthedocs.io/en/protos).
 
+## Version Information
+
+The latest development version of MDANSE, now upgraded to Python 3, represents a major change from the previous version. The user interface has transitioned from wxWidgets to Qt, providing a more refined and user-friendly experience. The earlier version, which was located in the 'develop' branch, has been moved to the **legacy** branch.
+
+MDANSE is currently in its _alpha_ phase in this new Python 3 version. The progression to the _beta_ stage is in progress. With the beta release, MDANSE will be available for direct installation via PyPI. Users can install it using the command `pip install`. `pip install`.
+
 ## Citing MDANSE
 
 If you used MDANSE in your research, please cite the following paper:
@@ -127,7 +141,7 @@ 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) and [ScientificPython](https://github.com/khinsen/ScientificPython),
+from the libraries [](https://github.com/khinsen/) and [ScientificPython](https://github.com/khinsen/ScientificPython),
 in order to reduce dependencies and thus facilitate installation.
 
 For more information see:
@@ -137,7 +151,7 @@ K. Hinsen, E. Pellegrini, S. Stachura, G.R. Kneller J. Comput. Chem. (2012) 33:2
 
 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 
-by Bachir Aoun, Vania Calandrini, Paolo Calligari, Gael Goret and Remi Perenon.
+by Bachir Aoun, Vania Calandrini, Paolo Calligari, Gael Goret, Remi Perenon and Rastislav Turanyi.
 
 The MDANSE project is supported by Ada Lovelace Centre, ISIS Neutron and Muon Source, Science
 and Technology Facilities Council, UKRI, and the Institut Laue-Langevin (Grenoble, France). 
@@ -155,3 +169,12 @@ If you want to join the project contact:
 ISIS Neutron and Muon Source \
 Rutherford Appleton Laboratory \
 Didcot, UK
+
+## Software Inquiries
+
+For questions or contributions related to the software, please contact:
+
+>Dr. Maciej Bartkowiak ([email protected])\
+ISIS Neutron and Muon Source \
+Rutherford Appleton Laboratory \
+Didcot, UK

Doc/_static/custom.css

@@ -1,6 +1,65 @@
+/* Custom CSS for Light Blue Theme */
+body {
+    background: #E6F1FF !important; /* Light blue background */
+    color: #0A192F !important; /* Dark blue text */
+}
+
+.title {
+    font-size: 24px; /* Adjust the size as needed */
+}
+
+.rst-versions {
+    border-top: solid 10px #222c32; /* Add a solid top border with the specified color */
+}
+
+a {
+    color: rgb(12, 102, 192); /* Bright color for links */
+}
+
+a:hover {
+    color: #8572f2; /* Slightly different shade for hover state */
+}
+
+/* Header and sidebar styling */
+.wy-nav-side, .wy-nav-side-search {
+    background-color: #0c2547 !important; /* Darker shade of blue for the sidebar */
+}
+
+/* Change background color of top navigation */
+.wy-nav-top {
+    background-color: #0c2547 !important; /* Light blue background for the top navigation */
+}
+
+/* Custom styles for math elements */
 .math {
     text-align: left;
 }
+
 .eqno {
     float: right;
+}
+
+/* Custom styles for grid items */
+.grid-item {
+    background-color: #1a3d79; /* Custom dark blue background */
+    color: #fff; /* White text color */
+    padding: 20px; /* Adjust padding as needed */
+    border-radius: 5px; /* Rounded corners */
+    text-align: center; /* Center-align content */
+    margin: 10px; /* Add spacing between grid items */
+}
+
+/* Custom styles for buttons */
+.button-ref {
+    background-color: #007BFF; /* Blue background for buttons */
+    color: #fff; /* White text color for buttons */
+    padding: 10px 20px; /* Adjust padding as needed */
+    border-radius: 5px; /* Rounded corners for buttons */
+    text-decoration: none; /* Remove underlines from buttons */
+    display: inline-block;
+    transition: background-color 0.3s ease; /* Smooth hover effect */
+}
+
+.button-ref:hover {
+    background-color: #0056b3; /* Slightly different shade of blue for hover state */
 }

Doc/conf.py

@@ -86,7 +86,7 @@
 current_year = datetime.date.today().year
 # General information about the project.
 project = u'MDANSE'
-copyright = u'2015-' + str(current_year) + u', MDANSE is developed and supported by the Institut Laue-Langevin and the ISIS Neutron and Muon Source'
+copyright = u'2015-' + str(current_year) + u', MDANSE is developed and supported by the Institut Laue-Langevin and the ISIS Neutron and Muon Source', '![UKRI Logo](_static/UKRI_Logo.png)'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

Doc/index.rst

@@ -6,10 +6,6 @@
 Welcome to MDANSE's documentation!
 ==================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
 .. note::
    This is the documentation of the MDANSE 2.0 release.
    The documentation, just like the code itself, is still under development.
@@ -36,17 +32,38 @@ G. Goret, B. Aoun, E. Pellegrini, "MDANSE: An Interactive Analysis Environment f
 J Chem Inf Model. 57(1):1-5 (2017).
 
 
+.. raw:: html
+
+   <div class="sd-grid">
+       <div class="grid-item">
+           <h3>💡 Explanations</h3>
+           <p>Learn the basics and core concepts of MDANSE.</p>
+           <a href="pages/explanations.html">Learn More</a>
+       </div>
+       <div class="grid-item">
+           <h3>⚛️ How-To Guides</h3>
+           <p>Practical step-by-step guides to help you utilize MDANSE effectively.</p>
+           <a href="pages/H_gui.html">Learn More</a>
+       </div>
+       <div class="grid-item">
+           <h3>🧪 Tutorials</h3>
+           <p>Detailed tutorials to help you get started with MDANSE.</p>
+           <a href="pages/T_Batch.html">Learn More</a>
+       </div>
+       <div class="grid-item">
+           <h3>📚 Technical References</h3>
+           <p>Deep dive into the technical details of MDANSE.</p>
+           <a href="pages/R_contact.html">Learn More</a>
+       </div>
+   </div>
+
+
 .. toctree::
-   :maxdepth: 4
-   :numbered:
-   :hidden:
-   :caption: MDANSE User Manual
+   :maxdepth: 5
+   :caption: 💡 Explanations
 
-   pages/opening
-   pages/authors
    pages/introduction
    pages/installation
-   pages/build
    pages/files
    pages/gui
    pages/cmd
@@ -57,8 +74,39 @@ J Chem Inf Model. 57(1):1-5 (2017).
    pages/analysis
    pages/trajectory
    pages/plotting
-   pages/parameters
    pages/fca
+
+.. toctree::
+   :maxdepth: 5
+   :caption: ⚛️ How-To Guides
+
+   pages/H_gui
+   pages/H_cli
+   pages/H_Dynamics
+   pages/H_Scattering
+   pages/H_Structure
+   pages/H_other
+   pages/H_gloss
+   pages/H_Plotting
+   pages/H_fca
+
+.. toctree::
+   :maxdepth: 5
+   :caption: 🧪 Tutorials
+
+   pages/T_Batch
+   pages/T_sim
+   pages/T_Analysis
+
+.. toctree::
+   :maxdepth: 5
+   :caption: 📚 Technical References
+
+   pages/R_contact
+   pages/parameters
+   pages/R_traj
+   pages/R_units
+   pages/R_further
    pages/references
 
 Indices and tables