Documentation Review and Suggestions

README.md → Doc/README.md

@@ -6,41 +6,16 @@ MDANSE is a python application designed for computing neutron observables from m
 be directly compared with neutron scattering experiments, particularly inelastic and quasi-elastic neutron scattering 
 spectroscopies.
 
-To do this, it interfaces with a variety of 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. 
+To do this, it interfaces with a variety of 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).
 
-## Quick start
-
-The easiest way to start using MDANSE is to download a built installer from out latest [github release](https://github.com/ISISNeutronMuon/MDANSE/releases/).
-There, we provide installers for the major operating systems, Windows, Linux and MacOS, which can be downloaded and installed
-any other software on that OS. After that, we recommend starting by using the GUI. The typical workflow will look as follows:
-
-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
-
-
-The most complete user documentation of MDANSE can be found on [our Read the Docs page](https://mdanse.readthedocs.io). 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) 
-
-## Installing from source
-
-Since MDANSE is currently written in Python 2.7, installing it from the source code can be challenging. There are guides
-for doing this in the [MDANSE User Guide](https://epubs.stfc.ac.uk/work/51935555), 
-[this issue](https://github.com/ISISNeutronMuon/MDANSE/issues/8), and the [Wiki](https://github.com/ISISNeutronMuon/MDANSE/wiki).
-However, if your system is not included in any of these, or you have any difficulties, please don't hesitate to contact us.
-
 ## 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:
+into -style HDF format, which is then used for all calculations. The following MD packages are supported:
 
 - CASTEP
 - CHARMM
@@ -107,11 +82,32 @@ experimental data, or used as new data to draw conclusions from. The following p
 
 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 
+different elements/isotopes. Finally, their results can be outputted in a HDF file, an HDF5 file, or a set of DAT 
 files, 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 in the 
-**[MDANSE User Guide](https://epubs.stfc.ac.uk/work/51935555)**
+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 advancement from the previous version. This update enhances the software's functionality and compatibility. Additionally, 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`.
+
+## Quick start
+
+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 is named *mdanse_gui*, and will be installed in the `bin/` or `Scripts/` directory of your Python virtual environment. Start it by typing `python PATH/TO/mdanse_gui`.
+
+The typical workflow will look as follows:
+
+1. Convert a trajectory from the file format generated by an MD simulation software into a HDF 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
+
+
+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)**.
+
+Other information including example scripts can be found on the [MDANSE website](https://www.isis.stfc.ac.uk/Pages/MDANSEproject.aspx) 
 
 ## Citing MDANSE
 
@@ -131,7 +127,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:
@@ -159,3 +155,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/pages/H_Dynamics.rst

@@ -0,0 +1,222 @@
+Section 10 How to Analysis: Dynamics
+======================================
+
+Angular Correlation Analysis
+===========================
+
+Index 1: GUI for Angular Correlation Analysis
+
+Purpose: Angular correlation analysis helps users understand the autocorrelation
+of vectors representing molecule extent in three orthogonal directions. This
+guide aims to assist users in effectively utilizing the Angular Correlation
+feature to gain insights into the dynamics of molecular systems.
+
+1. Launch MDANSE:
+   - Open the MDANSE software on your computer.
+
+2. Load Molecular Data:
+   - Load the relevant trajectory or molecular data using the "File" menu.
+
+3. Access the "Angular Correlation" Analysis:
+   - Navigate to the "Analysis" section within the MDANSE interface.
+   - Select the "Angular Correlation" option from the list of available analysis tools.
+
+4. Configure Analysis Parameters:
+   - Frames: Specify the range of frames for analysis. (Default: First: 0, Last: Entire trajectory, Step: 1)
+   - Choose the relevant axis for vector calculations.(Default: Principal axes of the molecule)
+   - Define output settings such as contributions and output files.(Default: Equal contribution unless specified)
+   - Select the appropriate running mode based on the nature of the analysis and desired output (Default: Standard or Basic mode)
+
+5. Initiate the Calculation:
+   - Start the Angular Correlation analysis by clicking on the "Run" button within the MDANSE interface.
+
+6. Analyze and Interpret Results:
+   - Review the autocorrelation function results to understand the dynamics and correlations of the selected molecular vectors within the system effectively.
+   - Interpret the data to gain insights into the rotational dynamics of the molecules and their behavior in the molecular system.
+
+   Recommended Plots:
+   - Autocorrelation Plot for Molecular Vectors in Three Orthogonal Directions (time vs. correlation).
+   visualize the degree of correlation and fluctuations in different directions over time.
+   - Rotational Dynamics Plot for Molecules in the System (angle vs. time).
+   provides insights into how molecules rotate and orient themselves within the molecular system
+
+Density Of States Analysis
+=========================
+
+Index 2: GUI for Density Of States Analysis
+
+Purpose: The Density Of States analysis aids in calculating the power spectrum
+of the VACF (Velocity Autocorrelation Function) to define the discrete DOS
+(Density Of States). This gives a comprehensive understanding of molecular dynamics.
+
+1. Launch MDANSE:
+   - Open the MDANSE software on your computer.
+
+2. Load Molecular Data:
+   - Load the relevant trajectory or molecular data using the "File" menu.
+
+3. Access the "Density Of States" Analysis:
+   - Navigate to the "Analysis" section within the MDANSE interface.
+   - Select the "Density Of States" option from the list of available analysis tools.
+
+4. Configure Analysis Parameters:
+   - Define the desired range of frames for analysis. (Default: First: 0, Last: Entire trajectory, Step: 1)
+   - Specify the instrumental resolution and interpolation order for accurate calculations. (Default: Automatic selection)
+   - Choose the project coordinates, atom selection, and group coordinates for analysis.(Default: All atoms)
+   - Determine the atom transmutation and weights for the calculation.(Default: No transmutation, equal weights)
+   - Configure output files and select the appropriate running mode.(Default: Standard mode)
+
+5. Initiate the Calculation:
+   - Start the Density Of States analysis by clicking on the "Run" or "Calculate" button within the MDANSE interface.
+
+6. Analyze and Interpret Results:
+   - Review the power spectrum results and the density of states characteristics to understand the molecular dynamics and vibrational properties of the system.
+   - Interpret the data to gain insights into the phonon modes and the behavior of the molecular components in the system.
+
+   Recommended Plots:
+   - Power Spectrum Plot of the VACF. Provides information about vibrational modes and frequencies.
+   - Density of States (DOS) Plot.  Illustrates the distribution of vibrational states in the system.
+
+General AutoCorrelation Function Analysis
+========================================
+
+Index 3: GUI for General AutoCorrelation Function Analysis
+
+Purpose: The General AutoCorrelation Function analysis calculates the autocorrelation function
+for a selected variable, typically used for position autocorrelation. 
+
+1. Launch MDANSE:
+   - Open the MDANSE software on your computer.
+
+2. Load Molecular Data:
+   - Load the relevant trajectory or molecular data using the "File" menu.
+
+3. Access the "General AutoCorrelation Function" Analysis:
+   - Navigate to the "Analysis" section within the MDANSE interface.
+   - Select the "General AutoCorrelation Function" option from the list of available analysis tools.
+
+4. Configure Analysis Parameters:
+   - Specify the desired range of frames for the analysis. (Default: First: 0, Last: Entire trajectory, Step: 1)
+   - Choose the relevant atom selection and group coordinates for the correlation function calculation.(Default:All Atoms)
+   - Define the trajectory variable and any required normalization. (Default: No normalization)
+   - Set weights and configure output files based on analysis requirements.(Default: equal weights)
+   - Select the appropriate running mode to obtain the desired output.(Default: Standard mode)
+
+5. Initiate the Calculation:
+   - Start the General AutoCorrelation Function analysis by clicking on the "Run" button within the MDANSE interface.
+
+6. Analyze and Interpret Results:
+   - Review the autocorrelation function results to gain insights into the position dynamics of the molecular system.
+   - Interpret the data to understand the correlation time and behavior of the selected variable within the system effectively.
+
+   Recommended Plots:
+   - Autocorrelation Function Plot for the Selected Variable.How the variable's correlation changes over time.
+   - Correlation Time Plot.Shows characteristic time scales of the system's behavior.
+
+
+Mean Square Displacement Analysis
+=================================
+Index 4: GUI for Mean Square Displacement Analysis
+
+Purpose: Mean Square Displacement (MSD) analysis helps understand particle diffusion.
+This guide aims to assist users in effectively utilizing the Mean Square Displacement feature
+to comprehend the dynamics of molecular systems. Shows characteristic time scales of the system's behavior.
+
+1. Launch MDANSE:
+   - Open the MDANSE software on your computer.
+
+2. Load Molecular Data:
+   - Load the relevant trajectory or molecular data using the "File" menu.
+
+3. Access the "Mean Square Displacement" Analysis:
+   - Navigate to the "Analysis" section within the MDANSE interface.
+   - Select the "Mean Square Displacement" option from the list of available analysis tools.
+
+4. Configure Analysis Parameters:
+   - Define the desired range of frames for analysis. (Default: First: 0, Last: Entire trajectory, Step: 1)
+   - Specify the project coordinates and relevant atom selections for the calculation.(Default:)
+   - Set the necessary group coordinates, atom transmutation, and weights as required.(Default: equal weights)
+   - Configure output files and select the appropriate running mode for the analysis.(Default: Standard mode)
+
+5. Initiate the Calculation:
+   - Start the Mean Square Displacement analysis by clicking on the "Run" button within the MDANSE interface.
+
+6. Analyze and Interpret Results:
+   - Review the MSD results to understand the diffusion behavior of particles in the molecular system.
+   - Analyze the relationship between MSD and the velocity autocorrelation function to gain insights into the system's dynamics effectively.
+
+   Recommended Plots:
+   - Mean Square Displacement vs. Time Plot.(vs) add more info 
+   - Velocity Autocorrelation Function (VACF) Plot.(vs) add more info 
+
+Order Parameter Analysis
+========================
+Index 5: GUI for Order Parameter Analysis
+
+Purpose: The Order Parameter analysis facilitates the study of conformational dynamics of proteins.
+This guide aims to assist users in effectively utilizing the Order Parameter feature to gain insights
+into the behavior and structural changes of proteins in molecular systems.
+
+1. Launch MDANSE:
+   - Open the MDANSE software on your computer.
+
+2. Load Molecular Data:
+   - Load the relevant trajectory or molecular data using the "File" menu.
+
+3. Access the "Order Parameter" Analysis:
+   - Navigate to the "Analysis" section within the MDANSE interface.
+   - Select the "Order Parameter" option from the list of available analysis tools.
+
+4. Configure Analysis Parameters:
+   - Define the desired range of frames for the analysis. (Default: First: 0, Last: Entire trajectory, Step: 1)
+   - Select the appropriate axis selection or reference basis for the order parameter calculation.
+    (Default: equal weights)
+    (Defaults: x-component: 0, y-component: 0, z-component: 1)
+   - Specify the output contributions per axis and configure output files according to the analysis requirements.
+   - Choose the appropriate running mode to obtain the desired output.(Default: Standard mode)
+
+5. Initiate the Calculation:
+   - Start the Order Parameter analysis by clicking on the "Run" button within the MDANSE interface.
+
+6. Analyze and Interpret Results:
+   - Review the order parameter results to understand the conformational dynamics and structural changes of proteins within the molecular system.
+   - Analyze the internal and global correlation functions to gain insights into the protein's behavior effectively.
+
+   Recommended Plots:
+   - Order Parameter vs. Time Plot. order parameter changes over time, reflecting protein conformational dynamics.
+   - Internal and Global Correlation Function Plots. gain insights into the protein's behavior effectively.
+
+Position AutoCorrelation Function Analysis
+==========================================
+ GUI for Position AutoCorrelation Function Analysis
+
+Purpose: The Position AutoCorrelation Function analysis focuses on position autocorrelation.
+This gains insights into the positional dynamics of molecular systems.
+
+1. Launch MDANSE:
+   - Open the MDANSE software on your computer.
+
+2. Load Molecular Data:
+   - Load the relevant trajectory or molecular data using the "File" menu.
+
+3. Access the "Position AutoCorrelation Function" Analysis:
+   - Navigate to the "Analysis" section within the MDANSE interface.
+   - Select the "Position AutoCorrelation Function" option from the list of available analysis tools.
+
+4. Configure Analysis Parameters:
+   - Specify the desired range of frames for the analysis.(Default: First: 0, Last: Entire trajectory, Step: 1)
+   - Define any necessary normalization procedures.(Default: No normalization)
+   - Choose project coordinates, atom selection, and group coordinates for the correlation function calculation.(Default: All available atoms) 
+   - Determine the atom transmutation and set weights as required.(Default: equal weights, standard output)
+   - Configure output files and select the appropriate running mode based on the analysis requirements. (Default: Standard mode)
+
+5. Initiate the Calculation:
+   - Start the Position AutoCorrelation Function analysis by clicking on the "Run" button within the MDANSE interface.
+
+6. Analyze and Interpret Results:
+   - Review the position autocorrelation function results to gain insights into the positional dynamics of the molecular system.
+   - Interpret the data to understand the characteristic time scales and behavior of the system effectively.
+
+   Recommended Plots:
+   - Position AutoCorrelation Function Plot. Visualizes how the variable's correlation changes over time.
+   - Characteristic Time Scales Plot. Shows characteristic time scales of the system's behavior.