From 9a9568ac9a3bb4d36a87a1d221bd158a09990aac Mon Sep 17 00:00:00 2001 From: Chi Cheng Date: Mon, 29 Apr 2024 15:59:55 +0100 Subject: [PATCH] documentation refactor 1 --- Doc/_static/custom.css | 2 +- Doc/conf.py | 8 +- Doc/index.rst | 39 ++-- Doc/pages/{T_Batch.rst => H_Batch.rst} | 4 +- Doc/pages/H_Dynamics.rst | 4 +- Doc/pages/H_Plotting.rst | 155 +++++++++++++- Doc/pages/H_Scattering.rst | 28 +-- Doc/pages/H_Structure.rst | 4 +- Doc/pages/H_cli.rst | 151 +++++++++++++- Doc/pages/H_fca.rst | 4 +- Doc/pages/H_gloss.rst | 8 +- Doc/pages/H_gui.rst | 5 +- Doc/pages/H_other.rst | 4 +- Doc/pages/{T_start.rst => H_start.rst} | 4 +- .../{trajectory.rst => H_trajectory.rst} | 20 +- Doc/pages/T_Analysis.rst | 190 ------------------ Doc/pages/T_Water_IR.rst | 2 + Doc/pages/T_sim.rst | 180 ++++++++++++++++- Doc/pages/analysis.rst | 7 +- Doc/pages/cmd.rst | 149 -------------- Doc/pages/dynamics.rst | 5 +- Doc/pages/files.rst | 4 +- Doc/pages/gui.rst | 3 +- Doc/pages/installation.rst | 12 +- Doc/pages/introduction.rst | 13 +- Doc/pages/plotting.rst | 158 --------------- Doc/pages/scattering.rst | 4 +- Doc/pages/structure.rst | 4 +- Doc/pages/workflow.rst | 105 +++++----- 29 files changed, 624 insertions(+), 652 deletions(-) rename Doc/pages/{T_Batch.rst => H_Batch.rst} (98%) rename Doc/pages/{T_start.rst => H_start.rst} (96%) rename Doc/pages/{trajectory.rst => H_trajectory.rst} (89%) delete mode 100644 Doc/pages/T_Analysis.rst create mode 100644 Doc/pages/T_Water_IR.rst delete mode 100644 Doc/pages/cmd.rst delete mode 100644 Doc/pages/plotting.rst diff --git a/Doc/_static/custom.css b/Doc/_static/custom.css index 249892e47..8a936a3e0 100644 --- a/Doc/_static/custom.css +++ b/Doc/_static/custom.css @@ -32,7 +32,7 @@ a:hover { /* Custom styles for math elements */ .math { - text-align: left; + text-align: center; } .eqno { diff --git a/Doc/conf.py b/Doc/conf.py index d7595d471..bbdef7e1f 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -65,7 +65,13 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.graphviz', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.imgmath']#,'rst2pdf.pdfbuilder'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.graphviz', + 'sphinx.ext.inheritance_diagram', + 'sphinx.ext.mathjax', +]#,'rst2pdf.pdfbuilder'] imgmath_latex_preamble = "\\usepackage{mathrsfs}" diff --git a/Doc/index.rst b/Doc/index.rst index 392ef7b98..cc6adc7dd 100644 --- a/Doc/index.rst +++ b/Doc/index.rst @@ -10,22 +10,17 @@ Welcome to MDANSE's documentation! This is the documentation of the MDANSE 2.0 release. The documentation, just like the code itself, is still under development. -Introduction -============ - -`MDANSE Project Website `_ - -`MDANSE GitHub Page `_ +**Useful links**: `MDANSE Project Website `_ | `MDANSE GitHub Page `_ **MDANSE** (**Molecular Dynamics Analysis for Neutron Scattering Experiments**) -is a python application designed for computing neutron observables +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. -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. +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", @@ -57,49 +52,51 @@ J Chem Inf Model. 57(1):1-5 (2017). - .. toctree:: :maxdepth: 5 + :hidden: :caption: 💡 Explanations pages/introduction pages/installation pages/files - pages/gui - pages/cmd pages/workflow pages/dynamics pages/scattering pages/structure pages/analysis - pages/trajectory - pages/plotting pages/fca .. toctree:: :maxdepth: 5 + :hidden: :caption: ⚛️ How-To Guides - pages/H_gui + pages/H_start pages/H_cli + pages/H_gui + pages/gui + pages/H_trajectory + pages/H_gloss pages/H_Dynamics pages/H_Scattering pages/H_Structure pages/H_other - pages/H_gloss - pages/H_Plotting pages/H_fca + pages/H_Plotting + pages/H_Batch .. toctree:: :maxdepth: 5 + :hidden: :caption: 🧪 Tutorials - pages/T_Batch + pages/T_Water_IR pages/T_sim - pages/T_Analysis .. toctree:: :maxdepth: 5 + :hidden: :caption: 📚 Technical References pages/R_contact @@ -109,7 +106,7 @@ J Chem Inf Model. 57(1):1-5 (2017). pages/R_further pages/references -Indices and tables +Indices and Tables ================== * :ref:`genindex` diff --git a/Doc/pages/T_Batch.rst b/Doc/pages/H_Batch.rst similarity index 98% rename from Doc/pages/T_Batch.rst rename to Doc/pages/H_Batch.rst index 5358b25f9..b78315ebc 100644 --- a/Doc/pages/T_Batch.rst +++ b/Doc/pages/H_Batch.rst @@ -1,5 +1,5 @@ -Running Batch Jobs in MDANSE: Tutorial -============================================= +Running Batch Jobs +================== Introduction ------------ diff --git a/Doc/pages/H_Dynamics.rst b/Doc/pages/H_Dynamics.rst index dcb4d7426..7173673a5 100644 --- a/Doc/pages/H_Dynamics.rst +++ b/Doc/pages/H_Dynamics.rst @@ -1,5 +1,5 @@ -How to Guide: Analysis Dynamics -====================================== +Running Dynamics Calculations +============================= Angular Correlation ------------------- diff --git a/Doc/pages/H_Plotting.rst b/Doc/pages/H_Plotting.rst index 3150b0527..d6389c1c2 100644 --- a/Doc/pages/H_Plotting.rst +++ b/Doc/pages/H_Plotting.rst @@ -1,5 +1,156 @@ -How to guide: Plotting Options -=============================== +Plotting the Results +==================== + +In this section, we'll explore various plotting options tailored to MDANSE +(Molecular Dynamics Analysis for Neutron Scattering Experiments) data, helping +you effectively analyze and visualize your scientific findings. + +To learn more about how to use these plots and make the most out of MDANSE's +visualization tools, refer to the technical references and user guides available +in the MDANSE documentation. These resources provide in-depth instructions, +examples, and tips on utilizing the plotting capabilities. + +Understanding the Plotting Options +---------------------------------- + +**Line Plotter:** + Visualize dynamic trends in MDANSE data, e.g., temperature fluctuations, + energy profiles, or scattering intensities over time. Customize line styles, + colors, and axes settings. + +**Image Plotter:** + Display MDANSE data as heatmaps or spatial distributions. Adjust aspect + ratios, colormaps, and settings for neutron scattering patterns, electron + density maps, or spatial correlations. + +**Elevation Plotter:** + Explore 3D MDANSE structures and landscapes. Zoom in on molecular + structures and adjust contrast for detailed examination of complex systems, + like biomolecules or nanomaterials. + +**2D Slice Plotter:** + Visualize specific 3D MDANSE data slices, focusing on dimensions and regions + of interest. Simplify density profiles, radial distribution functions, or + cross-sectional views of molecular assemblies. + +**Iso Surface Plotter:** + Create 3D surface visualizations with various rendering modes. Adjust opacity, + contours, and slice orientations to highlight features in volumetric data, + such as solvent density distributions or macromolecular structures. + +Choosing the Right Plotting Option +---------------------------------- + +Selecting the appropriate plotting option is crucial for meaningful insights: + +**Line Plotter:** + For tracking temporal changes like temperature and energy during simulations. + +**Image Plotter:** + To display spatial information, such as scattering patterns, electron + densities, or diffusion maps. + +**Elevation Plotter:** + Useful for gaining a 3D perspective on complex molecular structures, + nanomaterials, or biomolecules. + +**2D Slice Plotter:** + When focusing on specific 3D data sections, aiding local property analysis. + +**Iso Surface Plotter:** + Great for rendering 3D volumetric data, highlighting complex structures like + solvent-solute interfaces or protein conformations. + + + +Line Plotter +------------- + +Figure 1 shows a Line Plot of temperature vs. time. In this Line Plotter, +the x-axis represents time (in picoseconds), while the y-axis represents +temperature (in Kelvin). The graph shows how the temperature of a molecular +system evolves during a 1000 ps molecular dynamics simulation. This plot +allows for tracking variations and trends in the system's temperature, +revealing valuable insights into its thermal behavior over time. + +MDANSE's Line Plotter is an essential tool for visualizing dynamic data trends. +It's particularly valuable for tracking changes in critical parameters, such as +temperature fluctuations, energy profiles, or scattering intensities, as they +evolve over time during simulations. Users can adjust line styles, colors, and +axes settings to enhance data clarity. This tool is useful for analyzing +temporal behavior. For instance, it can identify temperature shifts that may +indicate phase transitions, fluctuations in energy levels signifying critical +events, or scattering intensity variations revealing structural changes. + +Image Plotter +------------- + +Figure 2 shows an Image Plot of a neutron scattering pattern from a +crystalline material. It employs scattering angles (in degrees) on both +the x and y-axes, while the colormap represents neutron scattering +intensity. This visualization aids in the identification of +crystallographic peaks and provides structural insights. + +The Image Plotter in MDANSE simplifies spatial data visualization, +making it suitable for systems with complex data structures, including +neutron scattering patterns or electron density maps. Its user-friendly +interface allows you to customize aspect ratios and select colormaps +that best highlight essential data features. This tool aids in pattern +recognition and structural analysis. It is particularly beneficial for +understanding structural insights within diverse systems. + +Elevation Plotter +----------------- + +Figure 3 shows a three-dimensional elevation plot of a biomolecule. The +x and y-axes denote spatial coordinates (in angstroms), while the z-axis +represents elevation, offering a three-dimensional view of a protein's +structure. It provides a view of its spatial arrangement, including bond +angles and structural features. + +MDANSE's Elevation Plotter is for exploring complex three-dimensional +structures like biomolecules and nanomaterials. Researchers can zoom in +on molecular structures, adjust contrast settings, and navigate 3D +topography. This tool reveals subtle spatial details often concealed in +2D representations, aiding in visualizing surface characteristics or +deconstructing the structure of biomolecules. + +2D Slice Plotter +---------------- + +Figure 4 shows a Density Profile Slice. The 2D Slice Plotter reveals the +density profile of solvent molecules within a specific plane of a +nanomaterial. Spatial coordinates (in nanometers) are depicted on the x +and y-axes, while the color map indicates particle density. This plot is +instrumental in understanding spatial variations in solvent distribution. + +The 2D Slice Plotter simplifies the visualization of cross-sectional +views within 3D datasets. It streamlines the examination of localized +properties, enabling in-depth analysis of factors like density profiles +or composition within specific sections of a system. Researchers employ +it to study particle distribution in nanomaterials or conduct +compositional analyses of specific molecular layers. + +Iso Surface Plotter +------------------- + +Figure 5 shows an Electron Density Iso Surface. This provides a detailed +visualization of the electron density distribution around a molecule. It +utilizes spatial coordinates (in angstroms) on the x, y, and z-axes, +while the isosurface illustrates specific electron density levels. +Researchers can manipulate parameters to emphasize molecular shapes and +binding sites within the electron density data. + +MDANSE's Iso Surface Plotter effectively visualizes volumetric data. +Researchers can customize parameters like opacity and contour levels to +emphasize features within 3D datasets, such as solvent density +distributions or protein conformations. This tool aids in visualizing and +analyzing complex structures and interfaces within molecular or material +systems, facilitating tasks like visualizing molecular binding sites or +solvent molecule arrangements around nanoparticles. Researchers gain a +comprehensive understanding of intricate structures and their scientific +significance. + Line Plotter ------------ diff --git a/Doc/pages/H_Scattering.rst b/Doc/pages/H_Scattering.rst index ffcdc005b..0d751719f 100644 --- a/Doc/pages/H_Scattering.rst +++ b/Doc/pages/H_Scattering.rst @@ -1,8 +1,8 @@ -How to Guide Analysis: Scattering -================================== +Running Scattering Calculations +=============================== -Current Correlation Function Analysis -'''''''''''''''''''''''''''''''''''''' +Current Correlation Function +'''''''''''''''''''''''''''' **Index 1:** Current Correlation Function Analysis **Purpose:** @@ -69,8 +69,8 @@ of density fluctuations and propagating shear modes within the molecular system. - Overlay multiple CCF plots to facilitate comparisons. -Dynamic Coherent Structure Factor Analysis -''''''''''''''''''''''''''''''''''''''''''' +Dynamic Coherent Structure Factor +''''''''''''''''''''''''''''''''' **Index 2:** Dynamic Coherent Structure Factor Analysis **Purpose:** @@ -126,8 +126,8 @@ following plotting suggestions for better visualization and interpretation: - Use contour plots to visualize the evolution of the dynamic incoherent structure factor over time. -Dynamic Incoherent Structure Factor Analysis -''''''''''''''''''''''''''''''''''''''''''''' +Dynamic Incoherent Structure Factor +''''''''''''''''''''''''''''''''''' **Index 3:** Dynamic Incoherent Structure Factor Analysis **Purpose:** @@ -187,8 +187,8 @@ system. of Q and time, highlighting prominent features. -Elastic Incoherent Structure Factor Analysis -''''''''''''''''''''''''''''''''''''''''''''' +Elastic Incoherent Structure Factor +''''''''''''''''''''''''''''''''''' **Index 4:** Elastic Incoherent Structure Factor Analysis **Purpose:** @@ -243,8 +243,8 @@ and the EISF within the system. - Generate 2D contour plots to explore correlations between Q vectors and their impact on the EISF. -Gaussian Dynamic Incoherent Structure Factor Analysis -'''''''''''''''''''''''''''''''''''''''''''''''''''''' +Gaussian Dynamic Incoherent Structure Factor +'''''''''''''''''''''''''''''''''''''''''''' **Index 5:** Gaussian Dynamic Incoherent Structure Factor Analysis **Purpose:** @@ -300,8 +300,8 @@ neutron-specific studies. dynamic changes within the system. -Neutron Dynamic Total Structure Factor Analysis -'''''''''''''''''''''''''''''''''''''''''''''''' +Neutron Dynamic Total Structure Factor +'''''''''''''''''''''''''''''''''''''' **Index 6:** Neutron Dynamic Total Structure Factor Analysis **Purpose:** diff --git a/Doc/pages/H_Structure.rst b/Doc/pages/H_Structure.rst index 90d182e4a..26b55d8c7 100644 --- a/Doc/pages/H_Structure.rst +++ b/Doc/pages/H_Structure.rst @@ -1,5 +1,5 @@ -How-to Guide: Analysis Structure -================================= +Running Structure Calculations +============================== Area Per Molecule ----------------- diff --git a/Doc/pages/H_cli.rst b/Doc/pages/H_cli.rst index 03b49834a..2650d3492 100644 --- a/Doc/pages/H_cli.rst +++ b/Doc/pages/H_cli.rst @@ -1,5 +1,152 @@ -How to Guide: Using the Command Line Interface (CLI) -==================================================== +Using the MDANSE CLI +==================== + +MDANSE (Molecular Dynamics Analysis and Visualization) software offers a +versatile and powerful command line interface (CLI) alongside its +graphical user interface (GUI). While the GUI provides an interactive and +user-friendly environment for analysis, the command line interface is a +valuable alternative that offers distinct advantages. In this section of +the user guide, we will explore why the MDANSE command line interface is +useful and discuss its various features. + +Additionally, for important commands and usage instructions on the command +line (CMD), please refer to the **Command Line Reference** section in the +MDANSE documentation. + +Advantages of Using the MDANSE Command Line Interface +----------------------------------------------------- + +**Automation and Scripting:** The CLI allows users to automate repetitive +analysis tasks by creating scripts or batch files. This is particularly +useful for users who need to perform the same analysis on multiple datasets, +saving time and effort. For example, you have a dataset of protein +simulations, and you want to calculate the root mean square deviation +(RMSD) for each frame in the trajectory. Instead of manually loading each +trajectory file into the GUI and setting up the analysis for each file, you +can create a script that automates this process. This approach enhances +efficiency, ensures methodological consistency, and eliminates the need for +manual repetition. + +**Batch Processing:** MDANSE CLI supports batch processing, enabling users +to analyze a series of datasets sequentially or in parallel. This feature +is beneficial when working with large datasets or conducting extensive +parameter sweeps. For example, imagine you have ten different molecular +dynamics simulations, and you want to calculate the radial distribution +function (RDF) for each of them with varying parameters. You can create a +batch processing script that iterates through each simulation, applies +different parameter settings, and generates RDF plots. This allows you to +analyze all simulations efficiently without manual intervention. + +**Remote and Cluster Computing:** The command line interface is well-suited +for remote and cluster computing environments. Users can execute MDANSE +analysis tasks on remote servers or high-performance computing clusters, +leveraging their computational resources. Suppose you have a massive dataset +requiring substantial computational resources for analysis. In that case, +MDANSE CLI enables you to submit analysis tasks to a remote +high-performance computing cluster. This strategy offloads the computational +workload to remote servers, optimally utilizing cluster resources and +facilitating concurrent execution of multiple simulations. This is +especially useful when rapid analysis of large datasets or computationally +intensive calculations is necessary, exceeding the capabilities of a local +machine. + +**Reproducibility:** Using scripts with the CLI ensures analysis +reproducibility. Scripted workflows document steps and parameters, making +it easier to recreate results or share with collaborators. By employing +scripts with the MDANSE CLI, you create a comprehensive workflow that +meticulously documents each step of the analysis, encompassing parameter +settings and data processing. This practice guarantees that you can easily +replicate the analysis, enhancing transparency and facilitating +collaborative research efforts. For example, you have conducted an analysis +of a complex molecular system using MDANSE, and you want to share your +findings with a colleague. Instead of sharing a set of GUI-driven steps, +you can provide them with a script that contains all the analysis steps +and parameters used. This script ensures that your colleague can reproduce +your analysis exactly, promoting transparency and collaboration. + +Managing jobs using the MDANSE CLI +----------------------------------- + +The MDANSE Command Line Interface (CLI) provides robust capabilities for +managing and monitoring various analysis jobs. Whether you're running +molecular dynamics simulations, calculating properties, or conducting +complex analyses, the CLI allows you to efficiently handle and keep track +of your tasks. + +With the MDANSE CLI, you can submit, monitor, and control the execution of +analysis jobs effortlessly. It offers features like job status checking, +error handling, and detailed logging, ensuring that you have full visibility +into the progress and results of your analyses. Whether you're dealing with +single tasks or complex workflows, the MDANSE CLI simplifies job management, +making it an indispensable tool for researchers and analysts. + +Additionally, for important commands and usage instructions related to +managing and monitoring jobs using the MDANSE CLI, please refer to the +**Job Management Reference** section in the MDANSE documentation. + +MDANSE Included Scripts +------------------------ + +When you install MDANSE, it comes bundled with several useful scripts. These +scripts are located in the `Scripts\` directory on Windows and the `bin/` +directory on Unix systems. + +In the following table, which will describe some of these scripts in +more detail. + ++--------------------------+-------------------------------------------------------------------+ +| Script | Description | ++==========================+===================================================================+ +| `mdanse` | The main MDANSE script that serves as the entry point for various | +| | MDANSE functionalities. | ++--------------------------+-------------------------------------------------------------------+ +|`mdanse_elements_database`| Provides access to the MDANSE elements database, allowing users | +| | to retrieve information about chemical elements. | ++--------------------------+-------------------------------------------------------------------+ +| `mdanse_gui` | Launches the graphical user interface (GUI) for MDANSE, offering | +| | an interactive and user-friendly environment for molecular | +| | dynamics analysis and visualization. | ++--------------------------+-------------------------------------------------------------------+ +| `mdanse_job` | Manages MDANSE job execution, facilitating the execution of | +| | analysis tasks, simulations, and other computational tasks within | +| | MDANSE. | ++--------------------------+-------------------------------------------------------------------+ +| `mdanse_periodic_table` | Displays the periodic table with detailed information on chemical | +| | elements, including atomic numbers, symbols, atomic weights, and | +| | more. | ++--------------------------+-------------------------------------------------------------------+ +| `mdanse_plotter` | Allows for data plotting and visualization within MDANSE, enabling| +| | users to create various plots and graphs for analyzing simulation | +| | results. | ++--------------------------+-------------------------------------------------------------------+ +| `mdanse_ud_editor` | Opens the MDANSE units definition editor, providing a tool for | +| | defining and managing units used in MDANSE simulations and | +| | analyses. | ++--------------------------+-------------------------------------------------------------------+ +| `mdanse_units_editor` | Opens the MDANSE units editor, which allows users to define and | +| | manage units used in MDANSE, ensuring consistency and accuracy in | +| | simulations and analyses. | ++--------------------------+-------------------------------------------------------------------+ + +For more in-depth information on running and utilizing these scripts, please +consult the **Technical References** provided in the MDANSE documentation. + +Custom Scripts +--------------- + +It is possible to edit MDANSE scripts or even write new ones from +scratch. To run an analysis using the MDANSE python library, two steps +are necessary; first, set up the parameters that the analysis requires +(equivalent to filling in the fields in the GUI), then running the +analysis (equivalent to clicking the Run button). For both of these, it +is necessary to understand how the analysis’ class works. This can be +done by reading MDANSE documentation, either by clicking the analysis’ +Help button or by clicking the `Open MDANSE API <#open_mdanse_api>`__ +button on the toolbar. + +For more in-depth information on running and utilizing custom scripts, please +consult the **Technical References** provided in the MDANSE documentation. + Run a Basic MDANSE Analysis Using the CLI ----------------------------------------- diff --git a/Doc/pages/H_fca.rst b/Doc/pages/H_fca.rst index 90ef9f69b..d6a4f7de8 100644 --- a/Doc/pages/H_fca.rst +++ b/Doc/pages/H_fca.rst @@ -1,5 +1,5 @@ -How to Guide: FCA algorithm -=========================== +Using the FCA algorithm +======================= Guide Steps ''''''''''' diff --git a/Doc/pages/H_gloss.rst b/Doc/pages/H_gloss.rst index fa52af3bf..76022a3fa 100644 --- a/Doc/pages/H_gloss.rst +++ b/Doc/pages/H_gloss.rst @@ -1,8 +1,6 @@ -How-to Guide: Glossary of Parameters -===================================== +Configuring Parameters +====================== -Configuring Parameters and Running Analyses in MDANSE -------------------------------------------------------- **Index 1: Configuring Parameters and Running Analyses** **Purpose:** @@ -110,7 +108,7 @@ of molecular systems. Creating Selections -=================== +------------------- **Purpose:** In MDANSE, creating selections is a powerful way to fine-tune your analysis, diff --git a/Doc/pages/H_gui.rst b/Doc/pages/H_gui.rst index 3981454f3..c23403d86 100644 --- a/Doc/pages/H_gui.rst +++ b/Doc/pages/H_gui.rst @@ -1,6 +1,5 @@ -How to Guide: Using MDANSE Graphical User Interface -=================================================== - +Using the MDANSE GUI +==================== Opening Trajectories -------------------- diff --git a/Doc/pages/H_other.rst b/Doc/pages/H_other.rst index 8dfec0737..ce06b34d1 100644 --- a/Doc/pages/H_other.rst +++ b/Doc/pages/H_other.rst @@ -1,5 +1,5 @@ -How to Guide Analysis: Other Options -===================================== +Running Other Calculations +========================== Infrared: Dipole AutoCorrelation Function ----------------------------------------- diff --git a/Doc/pages/T_start.rst b/Doc/pages/H_start.rst similarity index 96% rename from Doc/pages/T_start.rst rename to Doc/pages/H_start.rst index 68a88c8d5..fadd26d96 100644 --- a/Doc/pages/T_start.rst +++ b/Doc/pages/H_start.rst @@ -1,5 +1,5 @@ -Tutorial: Get started (Installation) -==================================== +Installing MDANSE +================= .. _installation_tutorial: diff --git a/Doc/pages/trajectory.rst b/Doc/pages/H_trajectory.rst similarity index 89% rename from Doc/pages/trajectory.rst rename to Doc/pages/H_trajectory.rst index dc8732158..4098c17c6 100644 --- a/Doc/pages/trajectory.rst +++ b/Doc/pages/H_trajectory.rst @@ -1,13 +1,13 @@ -Trajectory Converters -===================== +Converting Trajectories +======================= -Below is the list of converters present in MDANSE. These allow for the +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 HDF format that can be -used by MDANSE. All converters convert the positions and other vital -values such as unit cell parameters, but velocities and forces are -converted by only select converters. This section explains why they are -used. +MDANSE by converting the various file formats to the HDF format. These trajectory +converters convert positions and other vital +information such as the unit cell parameters. Additionally when available the trajectory +converters also converter information such as velocities and forces. +This section explains why they are used. To utilize the trajectory converters effectively, please refer to the comprehensive technical reference documentation provided with MDANSE. @@ -59,9 +59,9 @@ the trajectory data. DL_POLY Converter ----------------- -The DL_POLY Converter is capable of converting DL POLY trajectory data to HDF +The DL_POLY Converter is capable of converting DL_POLY trajectory data to HDF format. It not only includes positions but also velocities and forces of -particles in the output HDF file. Researchers who utilize DL POLY for molecular +particles in the output HDF file. Researchers who utilize DL_POLY for molecular dynamics simulations can benefit from this converter to analyze their simulation results. diff --git a/Doc/pages/T_Analysis.rst b/Doc/pages/T_Analysis.rst deleted file mode 100644 index 59e2dba78..000000000 --- a/Doc/pages/T_Analysis.rst +++ /dev/null @@ -1,190 +0,0 @@ -Analyzing Dynamic Coherent Structure Factor (DCSF) -==================================================== - -Introduction ------------- - -This tutorial will guide you through the analysis of DCSF (Dynamic Coherent -Structure Factor) plots using the MDANSE software and Python. DCSF analysis -provides insights into the scattering behavior of a molecular system. - -**Prerequisites**: -- MDANSE software installed. -- Basic knowledge of Python. - -Access DCSF Analysis in MDANSE -------------------------------- - -1. Navigate to the "Analysis" section within the MDANSE interface. -2. Select "Dynamic Coherent Structure Factor" to access the DCSF analysis. - -Analysis of the Total DCSF Plot -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The "Total DCSF Plot" in MDANSE offers valuable insights into the scattering -behavior of your molecular system. Understanding and interpreting this plot is -essential for gaining a deeper understanding of your system's structural -characteristics and dynamic behavior. - -Here are the key components and steps to analyze the Total DCSF Plot: - -- **Scattering Vector (Q) Magnitude**: - - The x-axis of the Total DCSF Plot represents the scattering vector magnitude - (Q). - - Scattering vector (Q) quantifies the spatial distribution of scatterers in - your system. - - Different Q values correspond to different structural features and scattering - events in your system. - -- **Dynamic Coherent Structure Factor (DCSF) Value**: - - The y-axis of the Total DCSF Plot represents the DCSF value. - - The DCSF value reflects the intensity of scattering at a specific Q value. - - High DCSF values indicate strong scattering, while low values indicate weak - scattering. - - The DCSF value at a particular Q value represents the overall scattering - contribution from all atoms or components in your system at that Q value. - -- **Analyzing Peaks**: - - Peaks in the Total DCSF Plot indicate significant scattering contributions at - specific Q values. - - The presence of peaks suggests the existence of structural features or - scattering events in your system. - - The height of a peak indicates the intensity of scattering at the - corresponding Q value. - - The shape and width of a peak provide additional information about the - characteristics of the scattering event. - -- **Peak Interpretation**: - - Broad Peaks: Broad peaks in the Total DCSF Plot may suggest diffusive motion - within your system. These motions can indicate disordered or liquid-like - regions. - - Sharp Peaks: Sharp and well-defined peaks suggest ordered structures or - scattering events with distinct spatial arrangements of atoms or components. - -- **Comparative Analysis**: - - Compare the Total DCSF Plot with other experimental data or simulations to - validate your findings and gain a deeper understanding of your system's - behavior. - - Consider how changes in system parameters or conditions impact the DCSF plot. - For example, compare different simulation trajectories or conditions to - observe variations in scattering behavior. - -To assist in your analysis, here's a Python code snippet that demonstrates how to -analyze the Total DCSF Plot: - -```python -import numpy as np -import matplotlib.pyplot as plt -from scipy.signal import find_peaks - -# Replace with your actual data -q_values_total = np.linspace(0, 10, 100) -dcsf_values_total = np.sin(q_values_total) + np.random.normal(0, 0.2, 100) - -# Analyze the Total DCSF Plot -peak_indices_total, peak_heights_total = find_peaks(dcsf_values_total, - height=0.5) - -# Print peak information for Total DCSF Plot -print("Total DCSF Peaks:") -for i, idx in enumerate(peak_indices_total): - print(f"Peak {i + 1}: Q = {q_values_total[idx]:.2f}, Height = {peak_heights_total[i]:.2f}") - -# Plot Total DCSF with peaks -plt.figure(figsize=(10, 6)) -plt.plot(q_values_total, dcsf_values_total, label="Total DCSF") -plt.scatter(q_values_total[peak_indices_total], peak_heights_total, color='red', marker='x', label='Peaks') -plt.xlabel("Scattering Vector (Q)") -plt.ylabel("DCSF Value") -plt.title("Total DCSF Plot with Peaks") -plt.legend() -plt.grid(True) -plt.show() - - -Analysis of the Partial DCSF Plot -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once you've selected the relevant atom type or group for your Partial Dynamic Coherent -Structure Factor (DCSF) analysis, a partial DCSF plot specific to that selection will be -displayed. Analyzing this plot is essential for gaining insights into the scattering behavior -of the chosen component. Here's how to analyze the Partial DCSF Plot effectively: - -- **Scattering Intensity**: - - Examine the intensity of scattering at different Q values (scattering vectors) within the - partial DCSF plot. - - Peaks in the partial DCSF plot indicate significant scattering contributions from the - selected atoms or group. - - High peak values indicate pronounced scattering at specific Q values, signifying structural - features or dynamic events associated with the chosen component. - -- **Peak Characteristics**: - - Evaluate the height, shape, and width of the peaks in the partial DCSF plot. - - These peak characteristics provide valuable insights into the scattering behavior of the - selected component. - - Height: The peak height reflects the intensity of scattering at the corresponding Q value. - Higher peaks indicate more intense scattering events. - - Shape and Width: The shape and width of peaks offer information about the nature of - scattering events. Broad peaks may suggest diffusive motion, while sharp, well-defined - peaks indicate ordered structures or distinct scattering events. - -- **Interactions and Correlations**: - - Consider any interactions or correlations between the selected atoms or groups within your - molecular system. - - Peaks in the partial DCSF plot can reveal how these components scatter X-rays or neutrons, - providing insights into structural features or dynamic motions. - - Identify scattering events that may result from interactions between the chosen component - and its surroundings. - -- **Comparative Analysis**: - - To better understand the relative contributions of different components to the overall - scattering pattern, compare the partial DCSF plot for the selected component with the Total - DCSF Plot. - - This comparison allows you to assess how the scattering behavior of the chosen component - influences the overall system scattering. - -By following these guidelines and considering scattering intensity, peak characteristics, -interactions, and comparisons, you can thoroughly analyze the Partial DCSF Plot. This analysis -helps you uncover valuable information about the scattering behavior and contributions of the -selected atom type or group within your molecular system. - - - -.. code-block:: python - - import numpy as np - import matplotlib.pyplot as plt - from scipy.signal import find_peaks - - # Replace with your actual data - q_values_partial = np.linspace(0, 10, 100) - dcsf_values_partial = np.cos(q_values_partial) + np.random.normal(0, 0.2, 100) - - # Analyze the Partial DCSF Plot - peak_indices_partial, peak_heights_partial = find_peaks(dcsf_values_partial, height=0.5) - - # Print peak information for Partial DCSF Plot - print("\nPartial DCSF Peaks:") - for i, idx in enumerate(peak_indices_partial): - print(f"Peak {i + 1}: Q = {q_values_partial[idx]:.2f}, Height = {peak_heights_partial[i]:.2f}") - - # Plot Partial DCSF with peaks - plt.figure(figsize=(10, 6)) - plt.plot(q_values_partial, dcsf_values_partial, label="Partial DCSF") - plt.scatter(q_values_partial[peak_indices_partial], peak_heights_partial, color='red', marker='x', label='Peaks') - plt.xlabel("Scattering Vector (Q)") - plt.ylabel("DCSF Value") - plt.title("Partial DCSF Plot with Peaks") - plt.legend() - plt.grid(True) - plt.show()# - - -Conclusion ----------- - -This tutorial has shown you how to access and analyze Dynamic Coherent Structure Factor (DCSF) -plots in MDANSE and perform peak analysis using Python. DCSF analysis provides valuable insights -into the scattering behavior of molecular systems, allowing you to understand structural features -and motions. - diff --git a/Doc/pages/T_Water_IR.rst b/Doc/pages/T_Water_IR.rst new file mode 100644 index 000000000..830e92cb1 --- /dev/null +++ b/Doc/pages/T_Water_IR.rst @@ -0,0 +1,2 @@ +1. Water IR Absorption Spectrum +=============================== diff --git a/Doc/pages/T_sim.rst b/Doc/pages/T_sim.rst index a91f1490c..7423987dc 100644 --- a/Doc/pages/T_sim.rst +++ b/Doc/pages/T_sim.rst @@ -1,5 +1,5 @@ -Tutorial: Neutron Scattering Dynamic Coherent Structure Factor (DCSF) -====================================================================== +2. Dynamic Coherent Structure Factor +==================================== This tutorial provides a guide on performing neutron scattering analysis using the MDANSE software. We will cover launching MDANSE, loading trajectory data in @@ -109,3 +109,179 @@ simulation data. - Additionally, consider using version control systems or documenting your work to track changes and ensure reproducibility of your simulations. + +Access DCSF Analysis in MDANSE +------------------------------- + +1. Navigate to the "Analysis" section within the MDANSE interface. +2. Select "Dynamic Coherent Structure Factor" to access the DCSF analysis. + +Analysis of the Total DCSF Plot +------------------------------- + +The "Total DCSF Plot" in MDANSE offers valuable insights into the scattering +behavior of your molecular system. Understanding and interpreting this plot is +essential for gaining a deeper understanding of your system's structural +characteristics and dynamic behavior. + +Here are the key components and steps to analyze the Total DCSF Plot: + +- **Scattering Vector (Q) Magnitude**: + - The x-axis of the Total DCSF Plot represents the scattering vector magnitude + (Q). + - Scattering vector (Q) quantifies the spatial distribution of scatterers in + your system. + - Different Q values correspond to different structural features and scattering + events in your system. + +- **Dynamic Coherent Structure Factor (DCSF) Value**: + - The y-axis of the Total DCSF Plot represents the DCSF value. + - The DCSF value reflects the intensity of scattering at a specific Q value. + - High DCSF values indicate strong scattering, while low values indicate weak + scattering. + - The DCSF value at a particular Q value represents the overall scattering + contribution from all atoms or components in your system at that Q value. + +- **Analyzing Peaks**: + - Peaks in the Total DCSF Plot indicate significant scattering contributions at + specific Q values. + - The presence of peaks suggests the existence of structural features or + scattering events in your system. + - The height of a peak indicates the intensity of scattering at the + corresponding Q value. + - The shape and width of a peak provide additional information about the + characteristics of the scattering event. + +- **Peak Interpretation**: + - Broad Peaks: Broad peaks in the Total DCSF Plot may suggest diffusive motion + within your system. These motions can indicate disordered or liquid-like + regions. + - Sharp Peaks: Sharp and well-defined peaks suggest ordered structures or + scattering events with distinct spatial arrangements of atoms or components. + +- **Comparative Analysis**: + - Compare the Total DCSF Plot with other experimental data or simulations to + validate your findings and gain a deeper understanding of your system's + behavior. + - Consider how changes in system parameters or conditions impact the DCSF plot. + For example, compare different simulation trajectories or conditions to + observe variations in scattering behavior. + +To assist in your analysis, here's a Python code snippet that demonstrates how to +analyze the Total DCSF Plot: + +```python +import numpy as np +import matplotlib.pyplot as plt +from scipy.signal import find_peaks + +# Replace with your actual data +q_values_total = np.linspace(0, 10, 100) +dcsf_values_total = np.sin(q_values_total) + np.random.normal(0, 0.2, 100) + +# Analyze the Total DCSF Plot +peak_indices_total, peak_heights_total = find_peaks(dcsf_values_total, + height=0.5) + +# Print peak information for Total DCSF Plot +print("Total DCSF Peaks:") +for i, idx in enumerate(peak_indices_total): + print(f"Peak {i + 1}: Q = {q_values_total[idx]:.2f}, Height = {peak_heights_total[i]:.2f}") + +# Plot Total DCSF with peaks +plt.figure(figsize=(10, 6)) +plt.plot(q_values_total, dcsf_values_total, label="Total DCSF") +plt.scatter(q_values_total[peak_indices_total], peak_heights_total, color='red', marker='x', label='Peaks') +plt.xlabel("Scattering Vector (Q)") +plt.ylabel("DCSF Value") +plt.title("Total DCSF Plot with Peaks") +plt.legend() +plt.grid(True) +plt.show() + + +Analysis of the Partial DCSF Plot +--------------------------------- + +Once you've selected the relevant atom type or group for your Partial Dynamic Coherent +Structure Factor (DCSF) analysis, a partial DCSF plot specific to that selection will be +displayed. Analyzing this plot is essential for gaining insights into the scattering behavior +of the chosen component. Here's how to analyze the Partial DCSF Plot effectively: + +- **Scattering Intensity**: + - Examine the intensity of scattering at different Q values (scattering vectors) within the + partial DCSF plot. + - Peaks in the partial DCSF plot indicate significant scattering contributions from the + selected atoms or group. + - High peak values indicate pronounced scattering at specific Q values, signifying structural + features or dynamic events associated with the chosen component. + +- **Peak Characteristics**: + - Evaluate the height, shape, and width of the peaks in the partial DCSF plot. + - These peak characteristics provide valuable insights into the scattering behavior of the + selected component. + - Height: The peak height reflects the intensity of scattering at the corresponding Q value. + Higher peaks indicate more intense scattering events. + - Shape and Width: The shape and width of peaks offer information about the nature of + scattering events. Broad peaks may suggest diffusive motion, while sharp, well-defined + peaks indicate ordered structures or distinct scattering events. + +- **Interactions and Correlations**: + - Consider any interactions or correlations between the selected atoms or groups within your + molecular system. + - Peaks in the partial DCSF plot can reveal how these components scatter X-rays or neutrons, + providing insights into structural features or dynamic motions. + - Identify scattering events that may result from interactions between the chosen component + and its surroundings. + +- **Comparative Analysis**: + - To better understand the relative contributions of different components to the overall + scattering pattern, compare the partial DCSF plot for the selected component with the Total + DCSF Plot. + - This comparison allows you to assess how the scattering behavior of the chosen component + influences the overall system scattering. + +By following these guidelines and considering scattering intensity, peak characteristics, +interactions, and comparisons, you can thoroughly analyze the Partial DCSF Plot. This analysis +helps you uncover valuable information about the scattering behavior and contributions of the +selected atom type or group within your molecular system. + + + +.. code-block:: python + + import numpy as np + import matplotlib.pyplot as plt + from scipy.signal import find_peaks + + # Replace with your actual data + q_values_partial = np.linspace(0, 10, 100) + dcsf_values_partial = np.cos(q_values_partial) + np.random.normal(0, 0.2, 100) + + # Analyze the Partial DCSF Plot + peak_indices_partial, peak_heights_partial = find_peaks(dcsf_values_partial, height=0.5) + + # Print peak information for Partial DCSF Plot + print("\nPartial DCSF Peaks:") + for i, idx in enumerate(peak_indices_partial): + print(f"Peak {i + 1}: Q = {q_values_partial[idx]:.2f}, Height = {peak_heights_partial[i]:.2f}") + + # Plot Partial DCSF with peaks + plt.figure(figsize=(10, 6)) + plt.plot(q_values_partial, dcsf_values_partial, label="Partial DCSF") + plt.scatter(q_values_partial[peak_indices_partial], peak_heights_partial, color='red', marker='x', label='Peaks') + plt.xlabel("Scattering Vector (Q)") + plt.ylabel("DCSF Value") + plt.title("Partial DCSF Plot with Peaks") + plt.legend() + plt.grid(True) + plt.show()# + + +Conclusion +---------- + +This tutorial has shown you how to access and analyze Dynamic Coherent Structure Factor (DCSF) +plots in MDANSE and perform peak analysis using Python. DCSF analysis provides valuable insights +into the scattering behavior of molecular systems, allowing you to understand structural features +and motions. diff --git a/Doc/pages/analysis.rst b/Doc/pages/analysis.rst index de689b826..523135286 100644 --- a/Doc/pages/analysis.rst +++ b/Doc/pages/analysis.rst @@ -3,13 +3,16 @@ This section is dealing with specific types of analysis performed by MDANSE. If you are not sure where these fit into the general workflow of data analysis, please read :ref:`workflow-of-analysis`. -Analysis: other options -======================= +Analysis Theory: Other +====================== Infrared ^^^^^^^^ +Infrared +'''''''' + Dipole AutoCorrelation Function ''''''''''''''''''''''''''''''' Dipole AutoCorrelation Function is valuable for studying diff --git a/Doc/pages/cmd.rst b/Doc/pages/cmd.rst deleted file mode 100644 index 18b73f659..000000000 --- a/Doc/pages/cmd.rst +++ /dev/null @@ -1,149 +0,0 @@ -Using MDANSE Command Line Interface -==================================== - -MDANSE (Molecular Dynamics Analysis and Visualization) software offers a -versatile and powerful command line interface (CLI) alongside its -graphical user interface (GUI). While the GUI provides an interactive and -user-friendly environment for analysis, the command line interface is a -valuable alternative that offers distinct advantages. In this section of -the user guide, we will explore why the MDANSE command line interface is -useful and discuss its various features. - -Additionally, for important commands and usage instructions on the command -line (CMD), please refer to the **Command Line Reference** section in the -MDANSE documentation. - -Advantages of Using the MDANSE Command Line Interface ------------------------------------------------------ - -**Automation and Scripting:** The CLI allows users to automate repetitive -analysis tasks by creating scripts or batch files. This is particularly -useful for users who need to perform the same analysis on multiple datasets, -saving time and effort. For example, you have a dataset of protein -simulations, and you want to calculate the root mean square deviation -(RMSD) for each frame in the trajectory. Instead of manually loading each -trajectory file into the GUI and setting up the analysis for each file, you -can create a script that automates this process. This approach enhances -efficiency, ensures methodological consistency, and eliminates the need for -manual repetition. - -**Batch Processing:** MDANSE CLI supports batch processing, enabling users -to analyze a series of datasets sequentially or in parallel. This feature -is beneficial when working with large datasets or conducting extensive -parameter sweeps. For example, imagine you have ten different molecular -dynamics simulations, and you want to calculate the radial distribution -function (RDF) for each of them with varying parameters. You can create a -batch processing script that iterates through each simulation, applies -different parameter settings, and generates RDF plots. This allows you to -analyze all simulations efficiently without manual intervention. - -**Remote and Cluster Computing:** The command line interface is well-suited -for remote and cluster computing environments. Users can execute MDANSE -analysis tasks on remote servers or high-performance computing clusters, -leveraging their computational resources. Suppose you have a massive dataset -requiring substantial computational resources for analysis. In that case, -MDANSE CLI enables you to submit analysis tasks to a remote -high-performance computing cluster. This strategy offloads the computational -workload to remote servers, optimally utilizing cluster resources and -facilitating concurrent execution of multiple simulations. This is -especially useful when rapid analysis of large datasets or computationally -intensive calculations is necessary, exceeding the capabilities of a local -machine. - -**Reproducibility:** Using scripts with the CLI ensures analysis -reproducibility. Scripted workflows document steps and parameters, making -it easier to recreate results or share with collaborators. By employing -scripts with the MDANSE CLI, you create a comprehensive workflow that -meticulously documents each step of the analysis, encompassing parameter -settings and data processing. This practice guarantees that you can easily -replicate the analysis, enhancing transparency and facilitating -collaborative research efforts. For example, you have conducted an analysis -of a complex molecular system using MDANSE, and you want to share your -findings with a colleague. Instead of sharing a set of GUI-driven steps, -you can provide them with a script that contains all the analysis steps -and parameters used. This script ensures that your colleague can reproduce -your analysis exactly, promoting transparency and collaboration. - -Managing jobs using the MDANSE CLI ------------------------------------ - -The MDANSE Command Line Interface (CLI) provides robust capabilities for -managing and monitoring various analysis jobs. Whether you're running -molecular dynamics simulations, calculating properties, or conducting -complex analyses, the CLI allows you to efficiently handle and keep track -of your tasks. - -With the MDANSE CLI, you can submit, monitor, and control the execution of -analysis jobs effortlessly. It offers features like job status checking, -error handling, and detailed logging, ensuring that you have full visibility -into the progress and results of your analyses. Whether you're dealing with -single tasks or complex workflows, the MDANSE CLI simplifies job management, -making it an indispensable tool for researchers and analysts. - -Additionally, for important commands and usage instructions related to -managing and monitoring jobs using the MDANSE CLI, please refer to the -**Job Management Reference** section in the MDANSE documentation. - -MDANSE Included Scripts ------------------------- - -When you install MDANSE, it comes bundled with several useful scripts. These -scripts are located in the `Scripts\` directory on Windows and the `bin/` -directory on Unix systems. - -In the following table, which will describe some of these scripts in -more detail. - -+--------------------------+-------------------------------------------------------------------+ -| Script | Description | -+==========================+===================================================================+ -| `mdanse` | The main MDANSE script that serves as the entry point for various | -| | MDANSE functionalities. | -+--------------------------+-------------------------------------------------------------------+ -|`mdanse_elements_database`| Provides access to the MDANSE elements database, allowing users | -| | to retrieve information about chemical elements. | -+--------------------------+-------------------------------------------------------------------+ -| `mdanse_gui` | Launches the graphical user interface (GUI) for MDANSE, offering | -| | an interactive and user-friendly environment for molecular | -| | dynamics analysis and visualization. | -+--------------------------+-------------------------------------------------------------------+ -| `mdanse_job` | Manages MDANSE job execution, facilitating the execution of | -| | analysis tasks, simulations, and other computational tasks within | -| | MDANSE. | -+--------------------------+-------------------------------------------------------------------+ -| `mdanse_periodic_table` | Displays the periodic table with detailed information on chemical | -| | elements, including atomic numbers, symbols, atomic weights, and | -| | more. | -+--------------------------+-------------------------------------------------------------------+ -| `mdanse_plotter` | Allows for data plotting and visualization within MDANSE, enabling| -| | users to create various plots and graphs for analyzing simulation | -| | results. | -+--------------------------+-------------------------------------------------------------------+ -| `mdanse_ud_editor` | Opens the MDANSE units definition editor, providing a tool for | -| | defining and managing units used in MDANSE simulations and | -| | analyses. | -+--------------------------+-------------------------------------------------------------------+ -| `mdanse_units_editor` | Opens the MDANSE units editor, which allows users to define and | -| | manage units used in MDANSE, ensuring consistency and accuracy in | -| | simulations and analyses. | -+--------------------------+-------------------------------------------------------------------+ - -For more in-depth information on running and utilizing these scripts, please -consult the **Technical References** provided in the MDANSE documentation. - -Custom Scripts ---------------- - -It is possible to edit MDANSE scripts or even write new ones from -scratch. To run an analysis using the MDANSE python library, two steps -are necessary; first, set up the parameters that the analysis requires -(equivalent to filling in the fields in the GUI), then running the -analysis (equivalent to clicking the Run button). For both of these, it -is necessary to understand how the analysis’ class works. This can be -done by reading MDANSE documentation, either by clicking the analysis’ -Help button or by clicking the `Open MDANSE API <#open_mdanse_api>`__ -button on the toolbar. - -For more in-depth information on running and utilizing custom scripts, please -consult the **Technical References** provided in the MDANSE documentation. - diff --git a/Doc/pages/dynamics.rst b/Doc/pages/dynamics.rst index 4af5cae2b..d3cfda829 100644 --- a/Doc/pages/dynamics.rst +++ b/Doc/pages/dynamics.rst @@ -3,8 +3,8 @@ This section is dealing with specific types of analysis performed by MDANSE. If you are not sure where these fit into the general workflow of data analysis, please read :ref:`workflow-of-analysis`. -Analysis: Dynamics -================== +Analysis Theory: Dynamics +========================= This section contains the following Plugins: @@ -171,6 +171,7 @@ should be calculated. .. _figure-one: .. figure:: ./Pictures/10000000000001BC00000163C18A769B32940652.png + :align: center :width: 11.748cm :height: 9.393cm diff --git a/Doc/pages/files.rst b/Doc/pages/files.rst index 49b6d8df0..3cc711f2c 100644 --- a/Doc/pages/files.rst +++ b/Doc/pages/files.rst @@ -1,7 +1,7 @@ .. _file_formats: -How to Guide Supported File Formats -================================== +Supported File Formats +====================== In the updated MDANSE version, there have been significant changes to the supported file formats for input and output. This section provides an diff --git a/Doc/pages/gui.rst b/Doc/pages/gui.rst index 47716586e..d34badac3 100644 --- a/Doc/pages/gui.rst +++ b/Doc/pages/gui.rst @@ -1,6 +1,5 @@ - Navigating the MDANSE GUI -========================== +========================= The MDANSE Graphical User Interface (GUI) is set up to walk the user through all the steps of the analysis while providing additional diff --git a/Doc/pages/installation.rst b/Doc/pages/installation.rst index 22594a007..517d3c922 100644 --- a/Doc/pages/installation.rst +++ b/Doc/pages/installation.rst @@ -1,17 +1,15 @@ -Getting Started with MDANSE -============================= +Getting Started +=============== MDANSE (Molecular Dynamics Analysis for Neutron Scattering Experiments) is a powerful tool for analyzing molecular dynamics -simulations in the context of neutron scattering experiments. To -begin using MDANSE, here are some helpful tips: +simulations in the context of neutron scattering experiments. MDANSE Installation -------------------- -To get started with MDANSE, you can follow the MDANSE Installation Tutorial below: - -- :ref:`installation_tutorial` +To get started with MDANSE, you can follow the MDANSE Installation Tutorial +at :ref:`installation_tutorial`. Explore the Documentation diff --git a/Doc/pages/introduction.rst b/Doc/pages/introduction.rst index f76d7f71c..7b174fa8d 100644 --- a/Doc/pages/introduction.rst +++ b/Doc/pages/introduction.rst @@ -1,15 +1,15 @@ Introduction ============ -Neutron scattering experiments are valuable tools for investigating atomic -positions and molecular dynamics in materials. Computational simulations and -modeling play a crucial role in analyzing and interpreting such experiments, +Neutron scattering experiments are valuable tools for investigating the +structure and dynamics of materials. Computational simulations and +modeling plays a crucial role in analyzing and interpreting such experiments, leading to improvements in existing materials and the design of new ones. Atomistic simulations, particularly molecular dynamics (MD) simulations, are increasingly employed for these purposes. However, predicting neutron observables from MD trajectories is a complex process that involves various calculations and transformations, such as mean square displacements, densities of states, velocity -and position auto- and cross-correlation functions, Fourier transformations, and +and position auto- and cross-correlation functions, and convolutions with instrument parameters, to obtain neutron observables that can be directly compared with experimental data. @@ -17,8 +17,8 @@ Compare Simulation and Experiment Results ----------------------------------------- Some of these steps have been implemented within MDANSE -(Molecular Dynamics Analysis of Neutron Scattering Experiments) [^Ref1^]. This -Python-based application has established connections with more than ten MD packages, +(Molecular Dynamics Analysis of Neutron Scattering Experiments) [Ref1]_. This +Python-based application has support with more than ten MD packages, both those employing classical and ab-initio force calculations. Purpose and Capabilities @@ -39,7 +39,6 @@ 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. -- Possiblity of exporting analysis jobs as Python scripts. - Specialised trajectory converters for specific MD engines. - A general trajectory converter based on ASE. diff --git a/Doc/pages/plotting.rst b/Doc/pages/plotting.rst deleted file mode 100644 index 1c63cf7f9..000000000 --- a/Doc/pages/plotting.rst +++ /dev/null @@ -1,158 +0,0 @@ - -Plotting Options -================ - -Plots ------ - -In this section, we'll explore various plotting options tailored to MDANSE -(Molecular Dynamics Analysis for Neutron Scattering Experiments) data, helping -you effectively analyze and visualize your scientific findings. - -To learn more about how to use these plots and make the most out of MDANSE's -visualization tools, refer to the technical references and user guides available -in the MDANSE documentation. These resources provide in-depth instructions, -examples, and tips on utilizing the plotting capabilities. - -Understanding Plotting Options -------------------------------- - -**Line Plotter:** - Visualize dynamic trends in MDANSE data, e.g., temperature fluctuations, - energy profiles, or scattering intensities over time. Customize line styles, - colors, and axes settings. - -**Image Plotter:** - Display MDANSE data as heatmaps or spatial distributions. Adjust aspect - ratios, colormaps, and settings for neutron scattering patterns, electron - density maps, or spatial correlations. - -**Elevation Plotter:** - Explore 3D MDANSE structures and landscapes. Zoom in on molecular - structures and adjust contrast for detailed examination of complex systems, - like biomolecules or nanomaterials. - -**2D Slice Plotter:** - Visualize specific 3D MDANSE data slices, focusing on dimensions and regions - of interest. Simplify density profiles, radial distribution functions, or - cross-sectional views of molecular assemblies. - -**Iso Surface Plotter:** - Create 3D surface visualizations with various rendering modes. Adjust opacity, - contours, and slice orientations to highlight features in volumetric data, - such as solvent density distributions or macromolecular structures. - -Choosing the Right Plotting Option ----------------------------------- - -Selecting the appropriate plotting option is crucial for meaningful insights: - -**Line Plotter:** - For tracking temporal changes like temperature and energy during simulations. - -**Image Plotter:** - To display spatial information, such as scattering patterns, electron - densities, or diffusion maps. - -**Elevation Plotter:** - Useful for gaining a 3D perspective on complex molecular structures, - nanomaterials, or biomolecules. - -**2D Slice Plotter:** - When focusing on specific 3D data sections, aiding local property analysis. - -**Iso Surface Plotter:** - Great for rendering 3D volumetric data, highlighting complex structures like - solvent-solute interfaces or protein conformations. - - - -Line Plotter -------------- - -Figure 1 shows a Line Plot of temperature vs. time. In this Line Plotter, -the x-axis represents time (in picoseconds), while the y-axis represents -temperature (in Kelvin). The graph shows how the temperature of a molecular -system evolves during a 1000 ps molecular dynamics simulation. This plot -allows for tracking variations and trends in the system's temperature, -revealing valuable insights into its thermal behavior over time. - -MDANSE's Line Plotter is an essential tool for visualizing dynamic data trends. -It's particularly valuable for tracking changes in critical parameters, such as -temperature fluctuations, energy profiles, or scattering intensities, as they -evolve over time during simulations. Users can adjust line styles, colors, and -axes settings to enhance data clarity. This tool is useful for analyzing -temporal behavior. For instance, it can identify temperature shifts that may -indicate phase transitions, fluctuations in energy levels signifying critical -events, or scattering intensity variations revealing structural changes. - -Image Plotter -------------- - -Figure 2 shows an Image Plot of a neutron scattering pattern from a -crystalline material. It employs scattering angles (in degrees) on both -the x and y-axes, while the colormap represents neutron scattering -intensity. This visualization aids in the identification of -crystallographic peaks and provides structural insights. - -The Image Plotter in MDANSE simplifies spatial data visualization, -making it suitable for systems with complex data structures, including -neutron scattering patterns or electron density maps. Its user-friendly -interface allows you to customize aspect ratios and select colormaps -that best highlight essential data features. This tool aids in pattern -recognition and structural analysis. It is particularly beneficial for -understanding structural insights within diverse systems. - -Elevation Plotter ------------------ - -Figure 3 shows a three-dimensional elevation plot of a biomolecule. The -x and y-axes denote spatial coordinates (in angstroms), while the z-axis -represents elevation, offering a three-dimensional view of a protein's -structure. It provides a view of its spatial arrangement, including bond -angles and structural features. - -MDANSE's Elevation Plotter is for exploring complex three-dimensional -structures like biomolecules and nanomaterials. Researchers can zoom in -on molecular structures, adjust contrast settings, and navigate 3D -topography. This tool reveals subtle spatial details often concealed in -2D representations, aiding in visualizing surface characteristics or -deconstructing the structure of biomolecules. - -2D Slice Plotter ----------------- - -Figure 4 shows a Density Profile Slice. The 2D Slice Plotter reveals the -density profile of solvent molecules within a specific plane of a -nanomaterial. Spatial coordinates (in nanometers) are depicted on the x -and y-axes, while the color map indicates particle density. This plot is -instrumental in understanding spatial variations in solvent distribution. - -The 2D Slice Plotter simplifies the visualization of cross-sectional -views within 3D datasets. It streamlines the examination of localized -properties, enabling in-depth analysis of factors like density profiles -or composition within specific sections of a system. Researchers employ -it to study particle distribution in nanomaterials or conduct -compositional analyses of specific molecular layers. - -Iso Surface Plotter -------------------- - -Figure 5 shows an Electron Density Iso Surface. This provides a detailed -visualization of the electron density distribution around a molecule. It -utilizes spatial coordinates (in angstroms) on the x, y, and z-axes, -while the isosurface illustrates specific electron density levels. -Researchers can manipulate parameters to emphasize molecular shapes and -binding sites within the electron density data. - -MDANSE's Iso Surface Plotter effectively visualizes volumetric data. -Researchers can customize parameters like opacity and contour levels to -emphasize features within 3D datasets, such as solvent density -distributions or protein conformations. This tool aids in visualizing and -analyzing complex structures and interfaces within molecular or material -systems, facilitating tasks like visualizing molecular binding sites or -solvent molecule arrangements around nanoparticles. Researchers gain a -comprehensive understanding of intricate structures and their scientific -significance. - - diff --git a/Doc/pages/scattering.rst b/Doc/pages/scattering.rst index 3c8c7e937..40c47b036 100644 --- a/Doc/pages/scattering.rst +++ b/Doc/pages/scattering.rst @@ -3,8 +3,8 @@ This section is dealing with specific types of analysis performed by MDANSE. If you are not sure where these fit into the general workflow of data analysis, please read :ref:`workflow-of-analysis`. -Analysis: Scattering -==================== +Analysis Theory: Scattering +=========================== This section discusses plugins used to calculate neutron spectroscopy observables from the trajectory. diff --git a/Doc/pages/structure.rst b/Doc/pages/structure.rst index 38730ca0f..c7d4557d7 100644 --- a/Doc/pages/structure.rst +++ b/Doc/pages/structure.rst @@ -3,8 +3,8 @@ This section is dealing with specific types of analysis performed by MDANSE. If you are not sure where these fit into the general workflow of data analysis, please read :ref:`workflow-of-analysis`. -Analysis: Structure -=================== +Analysis Theory: Structure +========================== Area Per Molecule ''''''''''''''''' diff --git a/Doc/pages/workflow.rst b/Doc/pages/workflow.rst index be7429dce..0828ce8e1 100644 --- a/Doc/pages/workflow.rst +++ b/Doc/pages/workflow.rst @@ -1,90 +1,83 @@ .. _workflow-of-analysis: -Workflow of the Analysis -======================== +The MDANSE Workflow +=================== -Most analysis jobs offered by MDANSE follow the same pattern of execution: +Here we describe a typical computational workflow for most users +which goes through three main stages (1) trajectory conversion, (2) +analysis calculation and (3) results plotting. -Input ------ +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. -Trajectory -^^^^^^^^^^ - -The trajectory must be in the MDANSE format, saved as a HDF file. - -(Most likely -your trajectory is in whatever format was output by your preferred Molecular Dynamics +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 -analysis. See also :ref:`trajectory-converters`) +analysis. See also :ref:`trajectory-converters` + +2a. Analysis parameters +----------------------- +Most analysis jobs offered by MDANSE allow a number of different parameters +which can be adjusted. We describe some of the more common parameters found +in MDANSE below. Frames ^^^^^^ - It is not necessary to use all the time frames of your MD simulation. You can decide to limit the range of simulation time, and reduce the number of the frames taken in that range by increasing the step between them. Only the frames you selected will -be passed to the analysis. See also :ref:`param-frames`. +be passed to the analysis job. See also :ref:`param-frames`. Atom selection ^^^^^^^^^^^^^^ - Just as it is not necessary to include all the time frames in the analysis, it is also possible to select only a subset of all the atoms present in the trajectory. Once you -have defined a selection, you can decide to run an analysis on the selected atoms, and +have defined a selection, you can decide to run an analysis job on the selected atoms, and ignore the rest. This is useful if you are trying to determine which atoms contribute -to a specific feature in your signal. See also :ref:`param-atom-selection`. - -Analysis --------- - -The analysis is run in steps, iterating over parts of the trajectory. - -If you chose to -determine the atom velocities by **interpolation**, it will be done at this stage. - -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 in the next step of the workflow. - -Finalising ----------- - -At this stage the partial properties have been calculated, typically per atom type, -or per pair of atom types. They will now be combined into the final result. +to a specific feature in your results. See also :ref:`param-atom-selection`. Resolution ^^^^^^^^^^ - -If the analysis allows for applying instrumental resolution, it will be done first. The resolution is enabled only for the analysis types which calculate an energy spectrum. -This is normally done by calculating a Fourier transform of a correlation function. -The resolution is applied by multiplying the time-dependent function by a window function -before applying the Fourier transform. The details are given in the section +This is normally applied to calculations involving Fourier transform of a correlation function. +The resolution is applied by multiplying the time-dependent function with a window function +before applying the Fourier transform. The details are given in the section :ref:`param-instrument-resolution`. -Normalisation -^^^^^^^^^^^^^ - -If the analysis offers the option of normalising the results, it is done at this stage. -The normalisation is described in the section :ref:`param-normalize`. - Weighting ^^^^^^^^^ - -The partial properties calculated so far will now be combined using the weights +The partial (usually by element) properties calculated can be combined using the weights chosen by the user, as described in the section :ref:`param-weights`. Please remember -that the MDANSE GUI normally recommends the weighting scheme appropriate to the +that the MDANSE_GUI normally recommends the weighting scheme appropriate to the type of analysis performed. -Writing output --------------- - +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 have chosen the HDF5 format. If, however, you were planning -to process the results further using other software, then you have most likely picked +the MDANSE_GUI, you will need to use the HDF5 format. 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`) + +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. + +3. Plotting +----------- +If the HDF5 format 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 +calculations store unit information with results, MDANSE_GUI +allows users to interactively switch between different units.