From f0c7303fb69ce3ef0eeb00dafa14d48356fa4ed0 Mon Sep 17 00:00:00 2001 From: Chi Cheng Date: Mon, 24 Feb 2025 11:04:18 +0000 Subject: [PATCH] cleanup and update outdated how-to and tutorial sections --- Doc/index.rst | 11 - Doc/pages/H_Batch.rst | 167 -------- Doc/pages/H_Dynamics.rst | 274 ------------- Doc/pages/H_Scattering.rst | 345 ----------------- Doc/pages/H_Structure.rst | 525 ------------------------- Doc/pages/H_cli.rst | 283 -------------- Doc/pages/H_conv.rst | 4 +- Doc/pages/H_fca.rst | 71 ---- Doc/pages/H_gloss.rst | 759 ------------------------------------- Doc/pages/H_gui.rst | 209 ---------- Doc/pages/H_other.rst | 219 ----------- Doc/pages/T_external.rst | 13 +- Doc/pages/T_sim.rst | 323 ---------------- Doc/pages/gui.rst | 657 -------------------------------- 14 files changed, 10 insertions(+), 3850 deletions(-) delete mode 100644 Doc/pages/H_Batch.rst delete mode 100644 Doc/pages/H_Dynamics.rst delete mode 100644 Doc/pages/H_Scattering.rst delete mode 100644 Doc/pages/H_Structure.rst delete mode 100644 Doc/pages/H_cli.rst delete mode 100644 Doc/pages/H_fca.rst delete mode 100644 Doc/pages/H_gloss.rst delete mode 100644 Doc/pages/H_gui.rst delete mode 100644 Doc/pages/H_other.rst delete mode 100644 Doc/pages/T_sim.rst delete mode 100644 Doc/pages/gui.rst diff --git a/Doc/index.rst b/Doc/index.rst index d6d2a2ae61..0e5122dd3e 100644 --- a/Doc/index.rst +++ b/Doc/index.rst @@ -75,17 +75,7 @@ J. Chem. Inf. Model. 2017, 57, 1, 1–5 `__ -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 ------------------------------------------ - -**Purpose:** - -This guide explains how to perform a basic MDANSE analysis from the command line. - -#. **Open Terminal or Command Prompt:** - - Open your computer's terminal or command prompt. - -#. **Navigate to MDANSE Directory:** - - Use the ``cd`` command to go to the MDANSE installation directory. If it's not in your system's PATH, provide the full path to the MDANSE directory. - Example: - - .. code-block:: bash - - cd /path/to/MDANSE - -#. **List Available MDANSE Jobs:** - - To see available analysis tasks, type: - - .. code-block:: bash - - mdanse -r job - -#. **Run a Basic Analysis:** - - Execute an analysis script with this command: - - .. code-block:: bash - - mdanse --jr my_basic_script.py - - Replace ``my_basic_script.py`` with your script's filename. - -#. **Check Results:** - - After the analysis finishes, review the results in the specified output directory, typically defined in your script. - -Running Jobs Using the CLI --------------------------- - -**Purpose:** - -This guide explains how to run MDANSE jobs via the command line interface (CLI) for various analysis tasks. - -#. **Open Terminal or Command Prompt:** - - Begin by opening your computer's terminal or command prompt. - -#. **Navigate to MDANSE Directory:** - - Use the ``cd`` command to go to the MDANSE installation directory. If it's not in your system's PATH, provide the full path to the MDANSE directory. - Example: - - .. code-block:: bash - - cd /path/to/MDANSE - -#. **List Available MDANSE Jobs:** - - To see available analysis tasks, type: - - .. code-block:: bash - - mdanse -r job - -#. **Run a Basic MDANSE Analysis Using the CLI:** - - Execute a basic MDANSE analysis using a command like this: - - .. code-block:: bash - - mdanse --jr my_basic_script.py - - Replace ``my_basic_script.py`` with your script's filename. - -#. **Check the Results:** - - After the analysis completes, check the results in the specified output directory. - -#. **Customize MDANSE Job Parameters Using CLI:** - - Generate a template script for your analysis using a command like this: - - .. code-block:: bash - - mdanse --js job_name - - Replace ``job_name`` with the specific analysis task you want to customize. - -#. **Open the generated script in a text editor.** - -#. **Import the necessary MDANSE modules at the beginning of the script.** - -#. **Define the job parameters as an empty dictionary.** - - Example of importing modules and defining job parameters: - - .. code-block:: python - - # Import the necessary MDANSE modules - from MDANSE.Core.MDANSE import REGISTRY - - # Define the job parameters - parameters = {} - -#. **Customize the parameters within the script to tailor the analysis to your research needs.** - - Example of customizing job parameters: - - .. code-block:: python - - # Set the atom charges if applicable (e.g., '1 2 0' for hydrogen, helium, and no charge) - parameters['atom_charges'] = '1 2 0' - - # Define atom selection if needed (e.g., select atoms by index) - parameters['atom_selection'] = '1-100' # Select atoms with indices from 1 to 100 - - # Specify the frames for analysis (e.g., from frame 0 to 500 with a step of 1) - parameters['frames'] = (0, 500, 1) - - # Set the output directory and format (e.g., HDF) - parameters['output_files'] = ('/path/to/custom_output_directory', ('hdf',)) - - # Choose the running mode (e.g., 'multiprocessor' for multi-core analysis) - parameters['running_mode'] = ('multiprocessor',) - - # Provide the path to the trajectory file in HDF format - parameters['trajectory'] = '/path/to/custom_trajectory_file.hdf' - -#. **Run the customized analysis script using this command:** - - .. code-block:: bash - - mdanse --jr my_custom_script.py - - Replace ``my_custom_script.py`` with your script's filename. - -#. **After the analysis completes, examine the results in the specified output directory, typically defined within your customized script.** diff --git a/Doc/pages/H_conv.rst b/Doc/pages/H_conv.rst index 3c25492a02..495f817d83 100644 --- a/Doc/pages/H_conv.rst +++ b/Doc/pages/H_conv.rst @@ -1,5 +1,5 @@ -Converged Results -================= +Obtaining Converged Results +=========================== In MD, a large number of settings must be chosen correctly to ensure that high quality results are obtained. Some of these include the size of the MD box, the time step and the simulation length. The choice of these settings diff --git a/Doc/pages/H_fca.rst b/Doc/pages/H_fca.rst deleted file mode 100644 index e2bc9ae5e6..0000000000 --- a/Doc/pages/H_fca.rst +++ /dev/null @@ -1,71 +0,0 @@ -Using the FCA algorithm -======================= - -Guide Steps -''''''''''' - -#. **Load Molecular Data** - Use the software's "File" menu to import the molecular - trajectory data. - -#. **Access Correlation Analysis** - Navigate to the "Analysis" section within MDANSE. - -#. **Select Correlation Function** - Choose the specific correlation function to compute, such as - velocity autocorrelation or density autocorrelation. - -#. **Configure Analysis Parameters** - - Specify the range of frames for analysis (e.g., First - Frame: 0, Last Frame: Entire trajectory, Step: 1). - - Choose the interpolation order for precise calculations. - - Select the interpolation mode based on hardware capabilities (automatic - mode is recommended). - - Set the number of preloaded frames if using 'one-time - disk interpolation' mode to optimize memory usage (default: 50). - -#. **Define Q Vectors and Atom Selection** - - Specify the Q vectors needed for the analysis. - - Select the relevant atom selection for the calculation. - -#. **Normalization, Atom Transmutation, and Weights** - - Specify whether normalization is required based on analysis needs. - - Set atom transmutation and weights as necessary for the - analysis. - -#. **Configure Output Files and Running Mode** - - Define the output files for storing the analysis results. - - Choose the running mode (e.g., Standard or Basic) based - on the desired output. - -#. **Start the Calculation** - Start the Current Correlation Function analysis by clicking on - the "Run" or "Calculate" button within the MDANSE interface. - -#. **Analyze and Interpret Results** - Review the obtained results to understand the dynamics of - density fluctuations and propagating shear modes within the molecular system effectively. - -**Implementing Spectral Smoothing in MDANSE** -''''''''''''''''''''''''''''''''''''''''''''' - -#. **Calculate Fourier Transforms** - After obtaining the correlation function results using FCA, proceed - to calculate the discrete Fourier transforms of the correlation function. - -#. **Apply Gaussian Window** - Define a Gaussian window function, W(m), with adjustable parameters - (e.g., width). It is typically defined as: - W(m) = exp(-0.5 * (α * |m| / (N_t-1))^2) for m in -(N_t-1) to N_t-1. - -#. **Compute Spectral Function** - Use the Gaussian window and the inverse transform formula - to compute the spectral function - P_ab(n/2N_t): P_ab(n/2N_t) = Δt * Σ_{m=-(N_t-1)}^{N_t-1} exp(-2πi(nm/2N_t)) * W(m) * (1/(N-|m|)) * S_AB(m). - -#. **Visualization and Analysis** - Visualize and analyze the smoothed spectral function to gain - insights into the system's behavior in the frequency domain. - - - diff --git a/Doc/pages/H_gloss.rst b/Doc/pages/H_gloss.rst deleted file mode 100644 index 4697f116d7..0000000000 --- a/Doc/pages/H_gloss.rst +++ /dev/null @@ -1,759 +0,0 @@ -Configuring Parameters -====================== - -**Purpose:** -This guide provides detailed instructions for configuring parameters -and running analyses within an MDANSE Analysis window. It covers the common -structure of MDANSE Analysis windows and guides you through the process of -customizing parameters for specific analyses. - -#. **Access an Analysis Tool:** - - Access the desired analysis tool tailored to your specific research needs by - navigating to the "Analysis" section in MDANSE. - -#. **Load Trajectory Data in HDF Format:** - - In the trajectory box, specify the path to the trajectory data file in HDF - (Hierarchical Data Format) format. This format is commonly used for efficient - storage and retrieval of trajectory data. It serves as the data source for - your analysis. - - .. note:: - Trajectory data in HDF format is preferred due to its advantages in terms - of data organization and access speed. - -#. **Configure Analysis Parameters:** - - Explore and configure the parameters that are specific to the chosen analysis - tool. These parameters may vary between analyses and are crucial for - customizing your analysis. - - - **Frames Configuration:** - - Adjust the "Frames" parameters to define the range of frames to be - considered for the analysis: - - *First Frame (Default: 0):* Determine the starting frame for your - analysis. It indicates the initial point of data consideration. - - *Last Frame (Default: Last frame in the trajectory):* Set the endpoint - for your analysis. This frame marks the conclusion of data inclusion. - - *Frame Step (Default: 1):* Control the frequency of frame selection. - Higher values skip frames at defined intervals, optimizing the analysis - duration. - -#. **Customize Parameters for Your Analysis:** - - Tailor the parameters to match the specifics of your analysis: - - Explore and adjust analysis-specific parameters, such as axis selection, - output settings, and configuration options. These parameters are essential - for fine-tuning your analysis based on your research objectives. - -#. **Utilize the Buttons:** - - At the bottom of the Analysis window, you'll find several buttons: - - **Save:** Use the "Save" button to preserve the current analysis, including - your configured options, into a Python script. This script can be executed - from the command line, promoting reproducibility and automation. - - **Run:** Start the analysis process by clicking the "Run" button. Upon - completion, you'll be prompted to decide whether you want to close the - window. Note that the status of the analysis can be monitored in the Jobs - panel. Keep in mind that there is a known bug where successful analyses may - not always display in the Jobs panel. - - - - -Q Shells -------- - -**Purpose:** -Q Shells in MDANSE are fundamental for scattering experiments and related analyses. -They play a crucial role in defining the distribution of Q vectors in reciprocal space, -which directly impacts the accuracy and scope of your analysis. - -Define Q Shell Parameters -''''''''''''''''''''''''' - -To effectively configure Q Shells in your MDANSE analysis, follow these steps: - - - Open your MDANSE analysis and locate the "Q Shells" configuration. - - - Configure the following parameters: - - - **From (Default: 0):** This parameter sets the lowest value of |Q| to be used - in Q-vector generation. It defines the starting point for your Q vectors. - - - **To (Default: 10):** Define the highest value of |Q| to be used in your - analysis. This parameter sets the upper limit for Q vectors. - - - **By Step of (Default: 1):** Specify the increment value for |Q| when - transitioning from one Q-shell to the next. This parameter determines the - spacing between Q vectors. Adjust the "Width" parameter accordingly when - changing the step. - - -Adjust for Specific Analysis -'''''''''''''''''''''''''''' - -Customize the Q shell parameters based on the specific requirements of your analysis: - - - Depending on your analysis objectives and the characteristics of your molecular - system, you may need to tailor the Q shell parameters to align with scattering - experiment data effectively. - - - Consider the range and density of Q vectors required to capture the relevant - structural and dynamical information in your system. - - - Collaborate with domain experts or refer to relevant literature to ensure that - your Q shell configuration is suitable for your research goals. - -The accuracy and relevance of your MDANSE analysis results depend significantly on -how well you configure the Q Shells. Properly adjusted Q shell parameters enable you -to extract valuable insights from scattering experiments and advance your understanding -of molecular systems. - - -Creating Selections -------------------- - -**Purpose:** -In MDANSE, creating selections is a powerful way to fine-tune your analysis, -enabling you to precisely target specific data subsets or criteria. These -selections offer various methods to modify your analysis, enhancing the precision -and relevance of your results. - -Understand Selection Types -'''''''''''''''''''''''''' - -MDANSE provides several types of selections, each designed for specific purposes: - - - Axis Selection/Reference Basis (Default: None): Allows you to choose - reference axes for your analysis. - - Atom Selection (Default: None): Enables you to select specific atoms or - groups of atoms in your molecular system. - - Atom Transmutation (Default: None): Provides the capability to change atom - types during analysis. - - Atom Charges (Default: None): Allows you to manipulate atom charges for - advanced analysis. - - Q Vectors (explored separately in the next section): Defines the distribution - of Q vectors in reciprocal space for scattering experiments. - -Access Selection Configuration -'''''''''''''''''''''''''''''' - - - Depending on your analysis needs, you can access selection configurations from - within the MDANSE analysis window or the Molecular Viewer. - -Creating Selections Manually -'''''''''''''''''''''''''''' - - - By default, MDANSE does not save any selections, requiring you to create them - manually. These selections are specific to a trajectory HDF file. - -Ensure Unique Naming -'''''''''''''''''''' - - - To prevent conflicts, assign each selection a unique name, even if you're - creating the same selection for multiple trajectories. This practice ensures - proper organization and prevents the overwriting of selections. - -Utilize User Definition Viewer -'''''''''''''''''''''''''''''' - - - The User Definition Viewer, accessible from the toolbar, simplifies - selection management. It provides an overview of all saved selections, - streamlining the selection process. - -**Step 6: Save Your Selections** - - - To save a selection, follow these steps: - #. Enter a distinctive name for your selection in the provided field next to - the Save button. - #. Click the Save button to store the selection. This action saves the - selection without closing the selection window. - - -Axis Selection/Reference Basis -------------------------------- - -**Purpose:** In MDANSE, Axis Selection/Reference Basis allows you to choose -reference axes for your analysis. This selection is vital for specific analyses -such as Angular Correlation and Order Parameter. - -**Step 1: Access Axis Selection** Inside an analysis window, find the Axis -Selection/Reference Basis configuration. This section enables you to select -reference axes for your analysis. - -**Step 2: Create Definitions** - -- From the drop-down menu, select one of the existing axis definitions. These - definitions are based on the number of selected atoms required for the - analysis. Only definitions matching the analysis's requirements will appear. -- To create a new definition, click the "New definition" button, opening the - configuration window. - -**Step 3: Define Axis Selection** - -The "Number of atoms" field will be automatically set to the number of atoms -required for the analysis. To select atoms, click the "+" button in the -"Molecules" list, displaying the atoms within a molecule. Double-click on an -atom to add it to the "Selected atoms" list, along with its details. To remove -an atom from the selection, click on it in the "Selected atoms" list and press -the Delete key. - -**Step 4: Utilize User Definition Viewer** - -Access the User Definition Viewer from the toolbar to manage and view all saved -axis selections. - -**Step 5: Save Your Axis Selection** - -To save your selection, provide it with a unique name in the field next to the -"Save" button. Click the "Save" button to store the selection. This action saves -the selection without closing the selection window. - -Axis Selection/Reference Basis is essential for fine-tuning your analysis by -specifying reference axes, contributing to the accuracy and relevance of your -results. - -Atom Selection --------------- - -**Purpose:** Atom Selection in MDANSE enables you to select specific atoms or -groups of atoms in your molecular system for analysis customization. - -**Step 1: Access Atom Selection** - -Inside an analysis window, find the Atom Selection configuration. Atom Selection -allows you to choose which atoms or particles to include in your analysis. - -**Step 2: Add Selections** - -The green button adds a line for another selection, allowing you to choose -additional selections for your analysis. You can include multiple selections to -focus on different sets of particles. You can remove a line by clicking the red -button. Use the drop-down menu and the "View selected definition" button to -manage selections. - -**Step 3: Create Atom Selections** - -Click the "Set new selection" button to open the configuration window. Here, you -can define the criteria for selecting atoms. - -**Step 4: Define Selection Criteria** - -Utilize the "Filter by" field to access particles in the trajectory. Selecting a -filter will display relevant particles in the top right box. Click -particles/groups to highlight them and add them to the selection list. Perform -complex selections by combining logical operations. - -**Step 5: Name and Save Your Selection** - -Name each selection uniquely in the field next to the "Save" button. Click -"Save" to store the selection. This action saves the selection without closing -the Atom Selection window. - -Atom Selection provides flexibility to tailor your analysis by selecting specific -particles, enhancing the precision and relevance of your results. - -Atom Transmutation ------------------- - -**Purpose:** Atom Transmutation in MDANSE simulates isotopic substitution, -allowing you to define the atomic makeup of selected particles. - -**Step 1: Access Atom Transmutation** - -Inside an analysis window, find the Atom Transmutation configuration. Atom -Transmutation allows you to change the chemical element of selected atoms in -your analysis. - -**Step 2: Select an Atom Selection** - -Choose an Atom Selection from the left drop-down menu. Atom Transmutation is -applied to the selected particles in this selection. - -**Step 3: Define Transmutation Element** - -Use the white drop-down menu next to the red button to choose the element to -which the selected atoms will be transmuted. - -Atom Transmutation allows you to customize the atomic composition of selected -particles, particularly useful for simulating isotopic substitutions in your -analysis. - -Creating Spherical Lattice Vectors ------------------------------------- - -**Purpose:** - -Spherical Lattice Vectors in MDANSE are used to generate a set of hkl vectors -compatible with the simulation box. This guide will walk you through the -process of creating spherical lattice vectors for your analysis. - -**Step 1: Access Spherical Lattice Vectors** - -Open the MDANSE analysis window. Look for the "Spherical Lattice Vectors" -section within the Q Vectors configuration. - -**Step 2: Define Vector Parameters** - -When configuring Spherical Lattice Vectors in MDANSE, it's essential to specify -the following parameters: - -**Seed:** -- (Default: 0) -- The "Seed" parameter is an integer used to initialize the random number - generation process, ensuring reproducibility. Modify it for different vector - sets. - -**Q Shells:** -- (Default: 50) -- The "Q Shells" parameter, an integer, determines the number of hkl vectors in - each shell. More vectors increase accuracy but extend computation time. - -**Width:** -- (Default: 1.0) -- The "Width" parameter, a float, sets the tolerance for each shell. Usually, it - matches the step value. A smaller width improves Q resolution. Adjust it as - needed for your analysis. - -**Step 3: Generate Vectors** - -Click the "Generate" button to create the hkl vectors based on the specified -parameters. These vectors will be used for your analysis, so ensure the settings -are appropriate. - -**Step 4: Name Your Vectors** - -In the empty box at the bottom of the window, provide a name for the generated -vectors. A descriptive name helps you identify the vectors for future reference. - -**Step 5: Save the Vectors** - -Click the "Save" button to save the generated spherical lattice vectors. Your -vectors are now ready to be used in your analysis. - -**Step 6: Additional Notes** - -- The "Generate" button must be clicked before saving the vectors. -- These vectors are useful for computations like the dynamical coherent - structure factor on an isotropic sample, such as a liquid or crystalline - powder. -- Saving your vectors is essential to use them in subsequent analyses. -- The window does not close automatically after saving, allowing further - adjustments if needed. - - -Circular Lattice vectors --------------------------- - -**Purpose** - -The purpose of this guide is to help users generate Q vectors within the -software interface. Q vectors are generated based on specified axis components to -define a plane. These Q vectors are crucial for various scientific and -computational applications, particularly in materials science and -crystallography. - -**Step 1: Access the Q Vectors Window** - -Open the Q Vectors window within the software interface. It appears to have -fields and buttons for specifying and generating Q vectors. - -**Step 2: Configure Axis 1** - -- **x-component:** [Default: 1] This component specifies the x-coordinate of the - vector that defines the first axis used to specify the plane. -- **y-component:** [Default: 0] This component specifies the y-coordinate of the - vector that defines the first axis used to specify the plane. -- **z-component:** [Default: 0] This component specifies the z-coordinate of the - vector that defines the first axis used to specify the plane. - -**Step 3: Configure Axis 2** - -- **x-component:** [Default: 0] This component specifies the x-coordinate of the - vector that defines the second axis used to specify the plane. -- **y-component:** [Default: 1] This component specifies the y-coordinate of the - vector that defines the second axis used to specify the plane. -- **z-component:** [Default: 0] This component specifies the z-coordinate of the - vector that defines the second axis used to specify the plane. - -**Step 4: Generate Q Vectors** -Click the **"Generate"** button to create the Q vectors based on the default -specifications for Axis 1 and Axis 2. These vectors will be generated and -displayed. - -**Step 5: Name the Generated Vectors** -- In the **"Name"** field, enter a descriptive name for the generated vectors. - This name will help you identify and reference these vectors in the future. - -**Step 6: Set the Number of hkl Vectors** -- **Number of hkl vectors:** [Format: int Default: 50] This parameter specifies - the number of hkl vectors in each shell. Higher values result in higher - accuracy but at the cost of longer computational time. - -**Step 7: Save the Generated Vectors** -Click the **"Save"** button to save the generated Q vectors with the specified -name and the desired number of hkl vectors. The vectors will be saved, and you -can access them for further analysis or use. - -Note: Make sure to set a name before saving the vectors, as the name is required -for identification. The **"Save"** button does not close the Q Vectors window, -allowing you to continue working with the generated vectors or make additional -configurations. - - -Generate Linear Vectors ------------------------- - -Linear Vectors in the software allow you to generate vectors along a specific -direction determined by an axis. Here's how to use this feature: - -#. **Access Linear Vectors Feature:** - - Open the software and locate the Linear Vectors tool. This tool is essential - for generating linear vectors in a specified direction. - -#. **Set the Seed for Random Number Generation:** - - Look for the "Seed" parameter. - - *Format*: int [Default: 0] - - The RNG seed used to generate the vectors. Using the same seed ensures - reproducibility, which is crucial for consistent results. - -#. **Specify the Number of hkl Vectors:** - - Configure the "n vectors" parameter. - - *Format*: int [Default: 50] - - This parameter defines the number of hkl vectors in each shell. Higher values - result in higher accuracy but may require more computational time. - -#. **Set the Width Tolerance for Shells:** - - Adjust the "width" parameter. - - *Format*: float [Default: 1.0] - - The "width" parameter specifies the accepted tolerance for each shell, often - identical to the step. It influences the distribution of vectors. - -#. **Define the Axis:** - - Configure the axis using the following parameters: - - x-component: *Format*: int [Default: 1] - - y-component: *Format*: int [Default: 0] - - z-component: *Format*: int [Default: 0] - - Specify the components of the desired axis that defines the vector - direction. - -#. **Generate Linear Vectors:** - - Click the "Generate" button to create the hkl vectors based on the specified - settings. This step initiates vector generation. - -#. **Name the Generated Vectors:** - - Enter a name for the generated vectors in the "Name" field. A descriptive - name helps you identify them later when working with the vectors. - -#. **Save the Generated Vectors:** - - Click the "Save" button to save the vectors. The window won't close, - allowing you to continue working with the vectors or make additional - configurations. - - - -Generate Grid Vectors ---------------------- - -Grid Vectors in the software allow you to generate hkl vectors within a specified -range and group them according to a qstep. Follow these steps: - -#. **Access Grid Vectors Feature:** - - Open the software and locate the Grid Vectors tool. This tool is essential - for generating grid vectors within a specified range. - -#. **Set the Seed for Random Number Generation:** - - Configure the "seed" parameter. - - *Format*: int [Default: 0] - - The "seed" parameter ensures reproducible random number generation for - consistent results. - -#. **Define h-range, k-range, and l-range:** - - Set the following parameters for each range: - - from: *Format*: int [Default: 0] - - to: *Format*: int [Default: 0] - - by step of: *Format*: int [Default: 1] - - Specify the range and step for h, k, and l vectors, which determine the - grid's dimensions. - -#. **Set the qstep:** - - Adjust the "qstep" parameter. - - *Format*: float [Default: 0.01] - - The "qstep" parameter determines how the hkl vectors are grouped within the - grid. - -#. **Generate Grid Vectors:** - - Click the "Generate" button to create the hkl vectors based on the specified - settings. This step initiates grid vector generation. - -#. **Name the Generated Vectors:** - - Provide a name for the generated vectors in the "Name" field. A descriptive - name helps you identify the grid vectors. - -#. **Save the Generated Vectors:** - - Click the "Save" button to save the vectors. The tool won't close, allowing - further work or configurations with the generated grid vectors. - - - -Generate Approximated Dispersion Vectors ------------------------------------------ - -The Approximated Dispersion Vectors feature allows you to generate Q vectors along -a line connecting two input Q points. Follow these steps: - -#. **Access Approximated Dispersion Vectors Feature:** - - Open the software and find the Approximated Dispersion Vectors tool. This - feature is useful for creating Q vectors along a defined line. - -#. **Select the Generator Type:** - - Use the drop-down menu to choose the generator type, such as - "circular_lattice." - - This selection determines the type of Q Vectors you want to define. - -#. **Specify the First Q Point:** - - Configure the following components: - - x-component: *Format*: int [Default: 1] - - y-component: *Format*: int [Default: 0] - - z-component: *Format*: int [Default: 0] - - Define the components of the first Q point along the line. - -#. **Specify the Second Q Point:** - - Set the components (x, y, z) for the second Q point similarly to the first - one. - - Define the components of the second Q point along the line. - -#. **Set the Q Step:** - - Adjust the "Q step (nm^-1)" parameter. - - *Format*: float [Default: 0.1] - - The "Q step" parameter determines the increment by which Q is increased when - tracing the line between the two points. - -#. **Generate Approximated Dispersion Vectors:** - - Click the "Generate" button to create the Q vectors based on the specified - settings. This step initiates vector generation along the defined line. - -#. **Name the Generated Vectors:** - - Provide a name for the generated vectors in the "Name" field. A descriptive - name helps you identify the dispersion vectors. - -#. **Save the Generated Vectors:** - - Click the "Save" button to save the vectors. The tool will not close - -Group Coordinates ------------------- - -#. **Accessing Group Coordinates:** - - To make use of group coordinates within MDANSE, you must access this feature - during the setup of your analysis. Group coordinates allow you to group atoms - based on specific criteria for customized calculations. - -#. **Default Setting (atom):** - - By default, MDANSE uses the "atom" setting for group coordinates. In this - default configuration: - - - Calculations are performed using the atomic positions of all the selected - atoms in your system. - - All individual atoms are considered independently in the analysis. - -#. **Changing the Group Setting:** - - If you find it necessary to modify the group setting according to your - research requirements, you can do so by selecting an alternative option from - the available choices. The common options include: - - - "group": This setting groups atoms based on specific group assignments. - - "residue": Group atoms based on residue identifiers. - - "chain": Group atoms according to chain designations. - - "molecule": Group atoms by their molecular assignments. - - Your choice among these options depends on the nature of your system and how - MDANSE interpreted it during the conversion process from your input data. - -#. **Application of Group Coordinates:** - - The primary objective of employing group coordinates is to amalgamate all - atoms belonging to a particular group into a single representative position. - This amalgamation effectively combines the selected atoms within the chosen - group into a single point. - - This grouping operation is advantageous for various calculations, such as: - - - Computing the mean square displacement of molecular centers. - - Analyzing the collective behavior of atoms within a specific group. - - Simplifying complex systems for more focused analysis. - -#. **Analysis Availability:** - - The "Group coordinates" parameter is available in numerous analyses offered - by MDANSE. These analyses include: - - - Center Of Masses Trajectory. - - Density Of States. - - Mean Square Displacement. - - Order Parameter. - - And more. - - Depending on your specific analysis goals, you can enable the "Group - coordinates" feature to tailor calculations based on the grouped atomic - positions. - -#. **Default Settings for Group Coordinates:** - - - The default setting for group coordinates in MDANSE is "atom," where - individual atoms are considered independently for analysis. - - The default grouping options ("group," "residue," "chain," "molecule") may - vary depending on the system's nature and input data interpretation. - -Instrument Resolution ----------------------- -**Purpose** - - The instrument resolution serves the crucial purpose of smoothing the data in the - time domain before performing a Fourier Transform into the frequency domain. This - smoothing helps avoid numerical artifacts and ensures more accurate and reliable - results in your analysis. - -#. **Accessing Instrument Resolution:** - - To control the instrument resolution in MDANSE, navigate to the relevant section - of the software interface that allows you to adjust this parameter. - -#. **Available Resolution Shapes:** - - MDANSE supports various resolution shapes, each with specific mathematical - characteristics. The default resolution shape is Gaussian, but you have the - flexibility to choose from a range of options, including Lorentzian, Pseudo- - Voigt, Square, Triangular, and Ideal. - -#. **Selecting a Resolution Shape:** - - Depending on your analysis requirements, you can select the most suitable - resolution shape. For instance: - - - 'gaussian': Provides a standard Gaussian-shaped resolution function. - Example: ('gaussian', {'mu': 0.0, 'sigma': 1.0}) - - - 'lorentzian': Offers a Lorentzian-shaped function. - Example: ('lorentzian', {'mu': 0.0, 'sigma': 1.0}) - - - 'pseudo-voigt': Combines Lorentzian and Gaussian components. - Example: ('pseudo-voigt', {'eta': 0.5, 'mu_lorentzian': 0.0, - 'sigma_lorentzian': 1.0, 'mu_gaussian': 0.0, 'sigma_gaussian': 1.0}) - - - 'square': Represents a square-shaped resolution profile. - Example: ('square', {'mu': 0.0, 'sigma': 1.0}) - - - 'triangular': Utilizes a triangular-shaped resolution function. - Example: ('triangular', {'mu': 0.0, 'sigma': 1.0}) - - - 'ideal': Expresses an ideal resolution as a Dirac function. - Example: ('ideal', {}) - -#. **Setting Parameters (μ and σ):** - - Each resolution shape may have specific parameters that can be adjusted. - Commonly, you can set the center position (μ) and width (σ) of the resolution - function. These parameters define the behavior of the resolution shape and can be - tailored to your analysis needs. - -#. **Resolution in Frequency Units:** - - MDANSE operates in frequency units, so it may be necessary to convert resolution - values into energy units (e.g., meV) for practical use. A typical conversion - factor for Gaussian resolution is σ ≈ 0.65 ps⁻¹, corresponding to a 1 meV - resolution. - - -Setting Interpolation Order ---------------------------- -**Purpose:** - -The interpolation order in MDANSE allows you to control the precision and -accuracy of velocity data interpolation. This feature is essential for -analyses that require atomic velocity data, ensuring reliable results. - -**Step 1: Access the Interpolation Order Setting** -- Open MDANSE on your computer. - -**Step 2: Default Behavior** -- By default, MDANSE attempts to use velocities stored in the HDF trajectory for - analysis. Check if your simulation has stored velocity data in this format. - -**Step 3: Choosing an Interpolation Order** -- If your simulation has velocity data, you can set the interpolation order. -- Click on the "Interpolation Order" setting. -- Choose an interpolation order ranging from 1st to 5th order. - - Default: 1st Order - -**Step 4: Understanding Order 1 Interpolation** -- If you select "Order 1" interpolation, MDANSE calculates the first - time-derivative of each point using neighboring positions and the time step - (∆t). - - Formula: (ṙ(t_i)) = (r(t_i+1) - r(t_i)) / ∆t - -**Step 5: Higher-Order Interpolation (N > 1)** -- For interpolation orders higher than 1 (2nd, 3rd, 4th, or 5th order), - MDANSE employs an Nth-order polynomial interpolation technique. -- This technique involves interpolating multiple points within a given range to - calculate the first time-derivative. - - Supported Orders: {2, 3, 4, 5} - -**Step 6: Analysis Compatibility** -- The "Interpolation Order" parameter is available in several MDANSE analyses, - -- Note that the implementation of interpolation in the Current Correlation - Function analysis may involve additional complexities, which are explained in - the respective section of the MDANSE documentation. - -By following these steps, you can effectively set the interpolation order in -MDANSE for your specific analysis needs, ensuring precise velocity data handling. - - - - - Weights ---------- - -**Purpose:** Adjust how atoms or elements contribute to property -calculations. - -**Step 2: Load Molecular Data** - - - Import your molecular data using the "File" menu. - -**Step 3: Access Analysis with Weights Option** - - - Identify the analysis that includes the "Weights" option. - - *Note:* Most analyses offer the "Weights" option to customize property - computations. - -**Step 4: Customize Weights** - - - Access "Weights" within the analysis settings. - - - *Default Weighting:* - - - In many cases, the default weight is set to 'equal,' treating all - atoms or elements equally. - - *Scattering Analyses:* - - Default weights differ for coherent (bcoh) and incoherent (b2inc) - analyses. - - - *Customization:* - - - You have the flexibility to select any numerical property from the - MDANSE database as a weighting factor. - - Adjust weights based on your research requirements. - -**Step 5: Understand Weighted Property Calculations** - - - Weights allow you to control how atoms or elements contribute to - property calculations. - - The total property is calculated based on the weighted contributions of - individual elements or atom pairs. - - *For single-particle analyses* (e.g., mean square displacement, velocity - autocorrelation function), properties are computed for all different - elements identified in the system. - - *For collective analyses* (e.g., partial distribution function, dynamic - coherent structure factor), properties are calculated for all possible - pairs of different elements. diff --git a/Doc/pages/H_gui.rst b/Doc/pages/H_gui.rst deleted file mode 100644 index 696af8f4c7..0000000000 --- a/Doc/pages/H_gui.rst +++ /dev/null @@ -1,209 +0,0 @@ -Using the MDANSE GUI -==================== - -Opening Trajectories --------------------- - -#. **Load Trajectory:** Once MDANSE GUI is open, you can load a - trajectory by either: - - Clicking on the "Load trajectory" button in the toolbar. - - Using the File menu and selecting "Load data." - - [Index: Load Trajectory Button] - -#. **Select Trajectory File:** A standard file browser window will - appear. Navigate to the location of your trajectory file (in HDF - format), select it, and click "Open." - - [Index: Select Trajectory File] - -#. **Trajectory Tab:** After loading the trajectory, a new tab - representing the trajectory will appear in the "Working panel." You - can now inspect and work with the loaded trajectory. - - [Index: Trajectory Tab in Working Panel] - -Configuring Analysis Parameters -------------------------------- - -Now that we have a trajectory loaded, let's configure the parameters for -the analysis you wish to perform: - -#. **Select Trajectory:** Ensure the trajectory you want to analyze is - open in the "Working panel." - -#. **Access Analysis Options:** To configure analysis parameters, find - the analysis you want to perform in the "Plugins panel." Click the - plus button next to the analysis name to reveal its options. - - [Index: Access Analysis Options] - -#. **Parameter Configuration:** You will see various analysis-specific - parameters. Configure these parameters according to your analysis - requirements. - - [Index: Parameter Configuration] - -Starting Calculations ---------------------- - -With your analysis parameters configured, it's time to initiate the -calculation: - -#. **Start Analysis:** Locate and click the "Run" button at the - bottom of the analysis configuration window. - - [Index: Start Analysis] - -#. **Confirmation:** You will likely receive a prompt asking if you want - to proceed with the analysis. Confirm and proceed. - -#. **Monitor Progress:** The status of your analysis can be monitored in - the "Jobs" panel, which displays ongoing tasks. Keep an eye on this - panel for updates on the progress of your calculation. - - [Index: Monitor Progress] - - -Plotting Analysis Results -------------------------- - -Once you have completed an analysis, you may want to visualize the -results. MDANSE provides a simple way to plot these results: - -#. **Completed Analysis:** Ensure that the analysis you want to - visualize the results of has been completed. - -#. **Access Plotter:** Click on the "2D/3D Plotter" button in the - toolbar. - - *Figure 8: Access Plotter Button* - -#. **Load Data:** In the Plotter, load the analysis data you want to - plot from the list of available data variables. - - *Figure 9: Load Data in Plotter* - -#. **Select Plot Type:** Choose the type of plot you want to create - (e.g., line plot, 2D image). - - *Figure 10: Select Plot Type* - -#. **Plot Data:** Click the "Plot in a new window" button to generate - and display the selected plot. - - *Figure 11: Plot Data* - -File Conversions ----------------- - -#. **Access Trajectory Converter:** Click on the "Trajectory converter" - button in the toolbar. - - - *Figure 12: Access Trajectory Converter Button* - -#. **Select Conversion Type:** Choose the appropriate conversion option - (e.g., from another format to HDF). - - - *Figure 13: Select Conversion Type* - -#. **Configure Conversion Parameters:** Set the required parameters for - the conversion, such as input and output file paths. - - *Figure 14: Configure Conversion Parameters* - -#. **Start Conversion:** Click the "Run" button to start the - conversion process. - - - *Figure 15: Start Conversion* - -Viewing Geometrical Structures -------------------------------- - -MDANSE enables you to visualize the geometrical structures within your -calculations: - -#. **Access Molecular Viewer:** In the "Working panel," locate and open - the trajectory you want to visualize. - -#. **Access Molecular Viewer:** Click on the "Molecular Viewer" button - in the toolbar. - - - *Figure 16: Access Molecular Viewer Button* - -#. **Explore Geometries:** The Molecular Viewer will display the - geometrical structures from your trajectory. You can interactively - explore and analyze these structures. - - *Figure 17: Explore Geometries in Molecular Viewer* - -Creating Input Files --------------------- - -MDANSE allows you to create input files for the command-line interface -and auto-start analysis scripts. These files serve as convenient -starting points for running new analyses directly from the command -line: - -#. **Access Input File Creation:** Click on the "Save analysis template" - button in the toolbar. - - *Figure 18: Access Input File Creation Button* - -#. **Configure Input Parameters:** Specify the parameters for your - analysis as needed. - - ![Configure Input Parameters](images/configure_input_parameters.png) - *Figure 19: Configure Input Parameters* - -#. **Save the Input File:** Click the "Save" button to generate the - input file. You can use this file to set up and run new analyses - from the command line. - - ![Save the Input File](images/save_input_file.png) - *Figure 20: Save the Input File* - -Creating Auto-Start Analysis Scripts ------------------------------------- - -Alternatively, you can also create an auto-start analysis Python script -using the same process. This script can automate the analysis setup and -execution: - -#. **Access Auto-Start Script Generator:** Click on the "Auto-Start - Script Generator" button in the toolbar. - - - *Figure 21: Access Auto-Start Script Generator Button* - -#. **Configure Analysis Parameters:** Specify the analysis parameters you - want to include in the script. You can set up the same analysis - configurations as you would in the GUI. - - - *Figure 22: Configure Analysis Parameters* - -#. **Generate Script:** Click the "Generate Script" button to create - the Python script. - - - *Figure 23: Generate Script Button* - -#. **Save the Script:** Save the generated script to a location of your - choice on your computer. - - - *Figure 24: Save the Script* - -#. **Execute the Script:** You can now execute the script from the - command line to start the analysis. The script will set up the - analysis based on the parameters you specified and initiate the - calculation. - - - *Figure 25: Execute the Script* - diff --git a/Doc/pages/H_other.rst b/Doc/pages/H_other.rst deleted file mode 100644 index 95d1bedfb8..0000000000 --- a/Doc/pages/H_other.rst +++ /dev/null @@ -1,219 +0,0 @@ -Running Other Calculations -========================== - -Infrared: Dipole AutoCorrelation Function ------------------------------------------ - -**Purpose** -The Infrared: Dipole AutoCorrelation Function analysis focuses on studying -molecular vibrations and infrared spectra using dipole auto-correlation. - -#. **Load Trajectory Data:** - - Click on the "File" menu. - - Select "Load Trajectory Data" and choose your trajectory file. - -#. **Access the "Dipole AutoCorrelation Function" Analysis:** - - In the MDANSE interface, navigate to the "Analysis" section. - - Locate and select "Dipole AutoCorrelation Function" from the available - analysis options. - -#. **Configure Analysis Parameters:** - - **Frames:** Specify the frames or time points (Default: First: 0, Last: Entire - trajectory, Step: 1). - - **Atom Selection:** Choose the atoms or particles. - - **Output Files (Optional):** Configure output file settings as needed. - -#. **Run the Calculation:** - - Click on the "Run" button. - -#. **Review Results:** - - Access and interpret the dipole autocorrelation function results to study - molecular vibrations and infrared spectra. - -#. **Recommended Plots:** - - Dipole AutoCorrelation Function Plot: Visualizes how the dipole autocorrelation - changes over time, providing insights into molecular vibrations. - - - Infrared Spectra Plot: Illustrates the infrared spectra obtained from the - analysis, showing the vibrational modes of the system. - - -Thermodynamics: Density ------------------------ - -**Purpose** -The Thermodynamics: Density analysis focuses on calculating the density of a molecular system. - -#. **Load Trajectory Data:** - - Click on the "File" menu. - - Select "Load Trajectory Data" and choose your trajectory file. - -#. **Access the "Density" Analysis:** - - In the MDANSE interface, navigate to the "Analysis" section. - - Select "Density" from the available analysis options. - -#. **Configure Analysis Parameters:** - - **Frames:** Specify the frames or time points (Default: First: 0, Last: Entire trajectory, Step: 1). - - **Atom Selection:** Choose the atoms or particles. - - **Output Files (Optional):** Configure output file settings as needed. - -#. **Run the Calculation:** - - Click on the "Run" button. - -#. **Review Density Results:** - - Access and interpret the density results obtained from the analysis. - -#. **Recommended Plot:** - - Density Plot: Visualizes how the density changes over time, providing insights into the system's behavior. - -Thermodynamics: Density ------------------------ - -**Purpose** -The Thermodynamics: Density analysis focuses on calculating the density of a -molecular system. - -#. **Load Trajectory Data:** - - Click on the "File" menu. - - Select "Load Trajectory Data" and choose your trajectory file. - -#. **Access the "Density" Analysis:** - - In the MDANSE interface, navigate to the "Analysis" section. - - Select "Density" from the available analysis options. - -#. **Configure Analysis Parameters:** - - **Frames:** Specify the frames or time points (Default: First: 0, Last: Entire - trajectory, Step: 1). - - **Atom Selection:** Choose the atoms or particles. - - **Output Files (Optional):** Configure output file settings as needed. - -#. **Run the Calculation:** - - Click on the "Run" button. - -#. **Review Density Results:** - - Access and interpret the density results obtained from the analysis. - -#. **Recommended Plot:** - - Density Plot: Visualizes how the density changes over time, providing insights - into the system's behavior. - -Thermodynamics: Temperature ---------------------------- - -**Purpose** -The Thermodynamics: Temperature analysis focuses on calculating the temperature of -a molecular system. - -#. **Load Trajectory Data:** - - Click on the "File" menu. - - Select "Load Trajectory Data" and choose your trajectory file. - -#. **Access the "Temperature" Analysis:** - - In the MDANSE interface, navigate to the "Analysis" section. - - Select "Temperature" from the available analysis options. - -#. **Configure Analysis Parameters:** - - **Frames:** Specify the frames or time points (Default: First: 0, Last: Entire - trajectory, Step: 1). - - **Atom Selection:** Choose the atoms or particles. - - **Output Files (Optional):** Configure output file settings as needed. - -#. **Run the Calculation:** - - Click on the "Run" button. - -#. **Review Temperature Results:** - - Access and interpret the temperature results obtained from the analysis. - -#. **Recommended Plot:** - - Temperature Plot: Visualizes how the temperature changes over time, providing - insights into the system's thermal behavior. - - -Center Of Masses Trajectory ---------------------------- - -**Purpose** -The Center Of Masses Trajectory analysis aims to reduce the complexity of a -molecular dynamics simulation by focusing on the motion of groups of atoms, such -as molecules or subunits. - -#. **Load Trajectory Data:** - - Click on the "File" menu. - - Select "Load Trajectory Data" and choose your trajectory file. - -#. **Access the "Center Of Masses Trajectory" Analysis:** - - Navigate to the "Analysis" section in the MDANSE interface. - - Select "Center Of Masses Trajectory" from the available plugins. - -#. **Configure Settings:** - - **Frames:** Specify the frames for COMT calculation (Default: First: 0, Last: Entire trajectory, Step: 1). - - **Atom Selection:** Choose atoms for the center of mass computation. - - **Group Coordinates:** Define groups of atoms for calculation. - - **Output Files:** Configure file settings as needed. - - **Running Mode:** Define the mode (Default: 0). - -#. **Run the Calculation:** - - Click the "Run" button for the COMT calculation. - -#. **Recommended Plot:** - - Center Of Masses Trajectory Plot: Visualizes the motion of groups of atoms' - centers of mass, providing insights into the system's overall dynamics. - -Cropped Trajectory ------------------- - -**Purpose** -The Cropped Trajectory analysis allows you to extract a subset of frames from your -trajectory. - -#. **Load Trajectory Data:** - - Follow the same steps as in the "Center Of Masses Trajectory" section. - -#. **Access the "Cropped Trajectory" Analysis:** - - Navigate to the "Analysis" section in MDANSE. - - Select "Cropped Trajectory" from the available plugins. - -#. **Configure Settings:** - - **Frames:** Specify the frames for the cropped trajectory (Default: First: 0, - Last: Entire trajectory, Step: 1). - - **Atom Selection:** Choose atoms to be included. - - **Output Files:** Configure file settings as needed. - - **Running Mode:** Define the mode (Default: 0). - -#. **Run the Calculation:** - - Click the "Run" button to create the cropped trajectory. - -#. **Recommended Plot:** - - Cropped Trajectory Plot: Visualizes the subset of frames extracted from the - trajectory, highlighting specific segments of interest. - -Global Motion Filtered Trajectory ----------------------------------- - -**Purpose** -The Global Motion Filtered Trajectory analysis separates global motion from internal -motion within the trajectory, focusing on relevant internal dynamics. - -#. **Load Trajectory Data:** - - Click on the "File" menu. - - Select "Load Trajectory Data" and choose your trajectory file. - -#. **Access the "Global Motion Filtered Trajectory" Analysis:** - - In MDANSE, navigate to "Analysis" and select "Global Motion Filtered Trajectory." - -#. **Configure Settings:** - - **Frames:** Specify frames for rigid body analysis (Default: First: 0, Last: - Entire trajectory, Step: 1). - - **Atom Selection:** Choose atoms involved in the analysis. - - **Group Coordinates:** Define groups of atoms as rigid bodies. - - **Reference:** Specify reference frame number (Default: 0). - - **Remove Translation:** Optionally remove translation (Default: False). - - **Output Files:** Configure file settings as needed. - - **Running Mode:** Define the mode (Default: 0). - -#. **Run the Calculation:** - - Click "Run" to extract rigid body motions from the trajectory. - -#. **Recommended Plot:** - - Rigid Body Trajectory Plot: Visualizes the extracted rigid body motions, - providing insights into the system's rigid body dynamics. \ No newline at end of file diff --git a/Doc/pages/T_external.rst b/Doc/pages/T_external.rst index e65b5c6245..d3a57f9d70 100644 --- a/Doc/pages/T_external.rst +++ b/Doc/pages/T_external.rst @@ -1,6 +1,6 @@ -Tutorials -========= +MDANSE-Examples +=============== The tutorials are stored in their own `repository `_. @@ -17,8 +17,11 @@ If you are familiar with git, you can also instead. -A -`specific `_ -tutorial can be accessed through your browser. +Specific tutorials can be accessed through your browser. + +* `Tutorial 1: A phase transition `_ +* `Tutorial 2: The van Hove functions `_ +* `Tutorial 3: Quasielastic neutron scattering (QENS) `_ + Once you have downloaded the input files, you can start following the steps explained in the text. diff --git a/Doc/pages/T_sim.rst b/Doc/pages/T_sim.rst deleted file mode 100644 index 8539718f77..0000000000 --- a/Doc/pages/T_sim.rst +++ /dev/null @@ -1,323 +0,0 @@ -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 -HDF format, configuring the analysis, troubleshooting common issues, and saving -simulation data. - -Launching MDANSE and Loading HDF Trajectory -------------------------------------------- - -Launch MDANSE -''''''''''''' - -Begin by launching MDANSE, either by double-clicking its icon or running it -from the command line, if necessary. - -Load HDF Trajectory -''''''''''''''''''' - -Once MDANSE is running, ensure that you have your molecular dynamics -trajectory data in the HDF format loaded into the software, suitable for -neutron scattering analysis. - -To load the HDF trajectory, follow these steps: - -#. Go to the "File" menu at the top of the MDANSE window. -#. Select "Load Trajectory" from the dropdown menu. -#. Browse your file system and select the MDANSE HDF trajectory file you want to analyze. Click "Open" to load it into MDANSE. - -Configuring Dynamic Coherent Structure Factor Analysis ------------------------------------------------------- - -Access Analysis Menu -'''''''''''''''''''' - -In the MDANSE GUI, navigate to the "Analysis" menu located at the top of the -window. - -Pick Analysis Type -'''''''''''''''''' - -From the "Analysis" menu, choose "Dynamic Coherent Structure Factor" to -initiate the analysis. This opens a dialog for configuring the analysis -parameters. - -Configure Analysis Parameters -''''''''''''''''''''''''''''' - -In the "Dynamic Coherent Structure Factor" dialog, configure the analysis -parameters as follows: - - **Frames:** For this analysis, we want to analyze all frames of the HDF - trajectory. You can specify a range of frames if needed (Default: First: 0, - Last: Entire trajectory, Step: 1). - - **Instrument Resolution:** Leave this setting at its default value for this - neutron scattering example (Default: Auto). - - **Q Vectors:** Select the "Isotropic" option for Q vectors as we want to - analyze a wide range of scattering vectors in all directions suitable for - neutron scattering experiments (Default: Isotropic). - - **Atom Selection:** Choose "All" to analyze all atoms in the system relevant - to your neutron scattering analysis (Default: All). - - **Atom Transmutation:** No specific atom transmutation is needed for this - analysis, so leave it at its default setting (Default: None). - - **Weights:** MDANSE will automatically calculate weights based on neutron - coherent scattering lengths, so leave this setting at its default value - (Default: Auto). - - **Output Files:** You can specify the output file format and location. For - this example, we'll use the default settings, which typically include HDF - as the format (Default: Format: HDF, Location: Default). - -Troubleshooting Tips -'''''''''''''''''''' - -- **Issue:** If MDANSE encounters an error during the analysis setup, - double-check the configuration parameters, ensuring they are appropriate for your - data and analysis. Pay special attention to the Q Vectors and Atom Selection. - -- **Issue:** If the analysis takes an unexpectedly long time to complete, - review your system specifications and the number of frames in your trajectory. - It may be beneficial to reduce the number of frames or use a more efficient - workstation. - -Running the Analysis --------------------- - -Start the Analysis -'''''''''''''''''' - -After configuring the analysis parameters in the "Dynamic Coherent Structure -Factor" dialog, click the "Run" button within the dialog to initiate the -analysis. - -Monitor Progress -'''''''''''''''' - -MDANSE will start performing the calculations, and you'll see progress -indicators or logs in the MDANSE interface. - -Review Results -'''''''''''''' - -Once the analysis is complete, MDANSE will generate the results, including the -total and partial dynamic coherent structure factors, and save them in the -default HDF file format, which you specified earlier. These HDF files will -typically be located in the default output location. - -Saving Simulation Data ----------------------- - -Save Script -''''''''''' - -Instead of starting the analysis, you can use the "Save as script" button. -It will save all the inputs of this analysis run into a Python script, -which you can run outside the GUI. There should be no difference in the -results between a job started using the 'Run' button and one started -in a script. - -Analysis results -'''''''''''''''' - -Apart from an MDA file (which is a binary HDF5 file), you can also -pick 'TextFormat' as output. This will create a TAR archive with -every data array saved in a separate file. Depending on your -plans for further data analysis, each format may have its own -advantaged. MDA files are typically easy to load into the MDANSE -GUI, while text files are easier to view using a text editor and -to process using your own software. - -Access DCSF Analysis in MDANSE -------------------------------- - -#. Navigate to the "Analysis" section within the MDANSE interface. -#. 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: - -.. 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_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/gui.rst b/Doc/pages/gui.rst deleted file mode 100644 index 5accfb992e..0000000000 --- a/Doc/pages/gui.rst +++ /dev/null @@ -1,657 +0,0 @@ -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 -information about each step. - -Key Actions in the MDANSE GUI ------------------------------- - -Through the MDANSE GUI, you can perform a range of essential tasks: - -- Converting Trajectories: each MD trajectory has to be converted to - an .mdt file, an HDF5 file storing the MDANSE data structures. -- Viewing Trajectories: each .mdt file can be inspected and visualised. -- Performing Analysis: Specify the parameters for the analysis you wish - to perform. Once all the inputs are valid, the analysis can be run. -- Plotting Analysis Results: Visualize and interpret the outcomes of your - analysis through plots and graphs. -- Creating Input Files and Scripts: Generate input files for the - command-line interface. - -Starting the MDANSE GUI -------------------------------- - -The new MDANSE GUI is a separate Python package that can be installed -using pip. This interface is built on the QtPy interface, which -leverages your existing Python bindings to interact with the Qt -libraries. For optimal functionality, ensure you have one of the -following installed: PyQt5, PyQt6, or PySide 2. The interface is -designed to be compatible with these libraries, providing a seamless -user experience. - -The MDANSE GUI can be initiated on different platforms as follows: - -Windows --------- - -- If you selected the option to create a desktop shortcut during - installation, you can use that shortcut to start MDANSE. -- Alternatively, navigate to the folder where MDANSE is installed - (default path: C:\Program Files\MDANSE). There, you can double-click - the file named "MDANSE" with the MDANSE icon. -- To start MDANSE from the command line, execute the batch file - "MDANSE_launcher.bat." Ensure you use quotation marks if the path - contains spaces. - -MacOS ------- - -- If you installed MDANSE normally, you can find the MDANSE icon in the - Applications folder and start it like any other app. Note that you may - need to adjust your system settings due to Apple's security measures - (see Ref [Ref4] for a guide). -- To start MDANSE GUI from the terminal, use the following command - (replace /Applications if you installed MDANSE elsewhere): - - .. code-block:: bash - - /Applications/MDANSE.app/Contents/MacOS/MDANSE - -Linux ------- - -- If your Linux distribution has an applications menu, you should find - an MDANSE icon there for launching the GUI. -- If not, you can start MDANSE from the terminal using the following - command: - - .. code-block:: bash - - mdanse_gui - - If this command doesn't work, locate the MDANSE installation directory. - By default, it should be in /usr/local. Search for the mdanse_gui script - within /usr/local/bin. Once found, run the following command: - - .. code-block:: bash - - /usr/local/bin/mdanse_gui - -The MDANSE GUI serves as a platform for performing a wide range -of analyses and visualizations. - -The standalone GUI elements ---------------------------- - -Some parts of the GUI can also be started on their own. These are: - -mdanse_elements_database -~~~~~~~~~~~~~~~~~~~~~~~~ - -This script has no options. When run, it opens the `Elements Database -Editor <#_Elements_database_editor>`__ GUI window. - -mdanse_gui -~~~~~~~~~~ - -This script has no options. When run, it opens the main `MDANSE -GUI <#_The_main_window>`__ window. - -mdanse_job -~~~~~~~~~~ - -This script is used to run a `job <#_Analysis>`__. It opens the GUI -window for the selected job without opening the main window. To do this, -two positional arguments are required (meaning only the values should be -placed after mdanse_job, no -- options like for the mdanse script). -These two arguments are as follows: - -- **job** – the short name of the job to be run (e.g., pdf for Pair - Distribution Function). -- **trajectory** – (only required for analyses; should be left blank - for trajectory converters) the path to an MMTK trajectory file used - for the job. - -mdanse_periodic_table -~~~~~~~~~~~~~~~~~~~~~ - -This script has no options. When run, it opens the `Periodic -Table <#_Periodic_table_viewer>`__ GUI window. - -mdanse_plotter -~~~~~~~~~~~~~~ - -This script has no options. When run, it opens the :ref:`2d3dplotter` -GUI window. - -mdanse_ud_editor -~~~~~~~~~~~~~~~~ - -This script has no options. When run, it opens the `User Definitions -Editor <#_User_definition>`__ GUI window. - -mdanse_units_editor -~~~~~~~~~~~~~~~~~~~ - -This script has no options. When run, it opens the Units Editor GUI -window. - - -The main window ---------------- - -Below is an image of the window you will see when you open MDANSE GUI. -All the parts have been marked and their short descriptions can be found -below. Further information on all parts is in the following sections. - -Please note that all pictures come from Windows 10, so the GUI will look -very slightly different on other platforms. However, MDANSE works -equally well, bugs notwithstanding, on all platforms. - - -#. `File menu <#_The_File_menu>`__ handles file manipulation. It can be - used to load NetCDF trajectories or to convert other trajectories - into the NetCDF format. -#. `View menu <#_The_View_menu>`__ allows you to hide/show various - parts of MDANSE. -#. `Help menu <#_The_Help_menu>`__ contains access to files that you - can use to better understand MDANSE and the theory behind it. -#. `Load trajectory button <#_Load_data>`__ can be used to load a - NetCDF trajectory. -#. `Periodic table viewer <#_Periodic_table_viewer>`__ opens a periodic - table containing the constants and data that MDANSE uses for - calculations. -#. `Elements database editor <#_Elements_database_editor>`__ allows you - to change the atomic constants that MDANSE uses for calculations. -#. :ref:`2d3dplotter` launches a window where the - calculated data can be plotted, and the plots formatted. -#. **User definitions editor** opens a window where you can view the - definitions that have been created for each trajectory. More on - definitions in `Selections <#_Creating_selections>`__. -#. `Units editor <#_Unites_Editor>`__ opens a window where the units - used in MDANSE can be managed. -#. **MDANSE classes framework** allows you to peruse the documentation - for the classes that make up MDANSE. This is useful if you want to - use MDANSE from the command line. -#. **Save analysis template** allows you to create a new analysis. This - will be available in My jobs inside the Plugins panel and can be run - like the native analyses. -#. **Open MDANSE API** opens MDANSE documentation in a browser. This is - very similar to MDANSE classes framework. -#. **Open MDANSE website** opens the MDANSE - website [Ref8]_ in a browser. -#. **About** launches a window with very basic information about the - MDANSE you have installed. -#. **Bug report** opens your default mail application. Please use this - or create an issue on MDANSE - GitHub [Ref9]_ to inform us of any issues - you have come across. -#. `Quit MDANSE <#_Quit>`__ closes the MDANSE window. -#. `Data panel <#_Data_panel>`__ contains any NetCDF files you loaded - into MDANSE using either #4 Load trajectory button, or from #1 File - menu > Load trajectory. -#. `Plugins panel <#_Plugins_panel>`__ contains all the options you can - do with the selected trajectory. -#. `Working panel <#_Working_panel>`__ shows the trajectories you have - opened. To open a trajectory, double click a trajectory in #16 Data - panel. You can then inspect the system described by the trajectory. -#. **Logger** shows all the messages generated by MDANSE. These can be - errors or information messages, such as ones confirming you saved a - script etc. -#. **Console** is a Python shell. It can be used like normal when - python is being used from the command line, i.e.. when python is - typed and executed in an OS shell. It contains all the bundled - modules, but you will need to import them first. -#. `Jobs <#_Jobs>`__ shows the status of all current jobs. Once you - start an analysis or trajectory conversion, you can view its - progress here - -Load data -~~~~~~~~~ -This option allows you to select an HDF file. Clicking the Load Data -button opens a standard (platform-specific) file browser, similar to the -one shown below: - -[Image: File Browser] - -Use it as you normally would, and the selected file will appear in the -Data Panel. While the file browser suggests that you can load the MVI trace -file format, please note that this feature is not currently implemented. -Therefore, only load HDF files. If you have a trajectory from another source, -it must first be converted.For more details on converting trajectories, -please refer to the next section. - - -Trajectory Converter ---------------------- - -This option enables the conversion of a trajectory to the HDF trajectory format. -Hovering over the Trajectory Converter -reveals the following menu: - -- **Help** will open MDANSE documentation for the converter class. -- **Save** creates a python script with the values of all the fields - set the way they were when the button is clicked. This script can be - used to quickly run this conversion again in the future. -- **Run** initiates the conversion. Its progress can be seen in - `Jobs <#_Jobs>`__. After a successful Run, the converted trajectory - is saved in the location specified in the field “output files” in the - converter interface. - -The descriptions of all converters will be found in `Appendix -1 <#_Appendix_1>`__. - -Quit ------ - -Selecting this option opens a confirmation prompt. If you select "Yes," MDANSE -will close. - -The View Menu --------------- - -This menu offers several options to show/hide various parts of MDANSE: - -- Toggle Data Tree: Shows/hides the Data Panel. -- Toggle Plugins Tree: Shows/hides the Plugins Panel. -- Toggle Controller: Shows/hides the bottom bar containing Logger, Console, and Jobs. -- Toggle Toolbar: Shows/hides the toolbar. - -The Help Menu --------------- - -Clicking the Help button reveals the following menu: - -- **About** opens a window containing information about MDANSE version, - a short summary, and a list of authors. -- **Simple help** opens a window with a brief summary of MDANSE - workflow and the various options that can be encountered. -- **Theoretical background** opens, in a browser, a document - summarising the theory behind many of the analyses. -- **User guide** opens the DOI to this user guide in the default - browser, showing a RAL Technical Report webpage. From there, this - user guide can be downloaded as a pdf. -- **Bug report** opens the default email app so that you can send us an - email, informing us of any issue you have encountered. When reporting - an issue, please include a picture or copy of the error, such as the - `traceback from job failure <#STATE>`__. - -Toolbar --------- - -The Toolbar is a set of pictographic buttons that enable you to quickly -perform essential actions. Below is a brief overview of each button, from left -to right: - -#. **Load trajectory button** can be used to load a NetCDF trajectory. - More information in `Load data <#_Load_data>`__. -#. `Periodic table viewer <#_Periodic_table_viewer>`__ opens a periodic - table containing the constants and data that MDANSE uses for - calculations. -#. `Elements database editor <#_Elements_database_editor>`__ allows you - to change the atomic constants that MDANSE uses for calculations. -#. :ref:`2d3dplotter` launches a window where the - calculated data can be plotted, and the plots formatted. -#. **User definitions editor** opens a window where you can view the - definitions that have been created for each trajectory. More on - definitions in `Selections <#_Creating_selections>`__. -#. `Units editor <#_Unites_Editor>`__ opens a window where the units - used in MDANSE can be managed. -#. **MDANSE classes framework** allows you to peruse the documentation - for the classes that make up MDANSE. This is useful if you want to - use MDANSE from the command line. -#. **Save analysis template** allows you to create a new analysis. This - will be available in My jobs inside the Plugins panel and can be run - like the native analyses. -#. **Open MDANSE API** opens MDANSE documentation in a browser. This is - very similar to MDANSE classes framework. -#. **Open MDANSE website** opens the MDANSE website in a browser. -#. **About** launches a window with very basic information about the - MDANSE you have installed. -#. **Bug report** opens your default mail application. Please use this - or our GitHub [Ref9]_ to inform us of any - issues you have come across. When reporting an issue, please include - a picture or copy of the error, such as the `traceback from job - failure <#STATE>`__. -#. **Quit MDANSE** closes MDANSE. - - -Periodic table viewer -~~~~~~~~~~~~~~~~~~~~~ - -Once launched, it will open this window: - -.. image:: ./Pictures/100000010000031E000001EB8316D84CE16D60A9.png - :width: 15.806cm - :height: 9.733cm - -By hovering over an element, detailed information from MDANSE elements -database will show up at the top. By clicking on an element, a list of -its isotopes will appear as a menu: - -.. image:: ./Pictures/100000010000007B00000072BD990BE2296AF016.png - :width: 3.254cm - :height: 3.016cm - -When an isotope is selected, all the information that is stored in the -database will be displayed: - -.. image:: ./Pictures/100000010000024600000333543D0D0EC0A01C7E.png - :width: 7.509cm - :height: 10.566cm - -Clicking on the link at the bottom opens a Wikipedia article about that -element. Other than that, you cannot interact with this page in any way. -If you would like to change any of the displayed data, you will have to -use the Elements database editor. - -Elements database editor -~~~~~~~~~~~~~~~~~~~~~~~~ - -Clicking on this button opens this window: - -.. image:: ./Pictures/10000001000003160000018C76F0FE861E14A12B.png - :width: 15.789cm - :height: 7.895cm - -It can be interacted with like a normal spreadsheet; click (or double -click) on a field you want to edit and type the new value. Once you are -done with making changes, don't forget to save them before closing. You -can do that through the file menu. - -File menu -^^^^^^^^^ - -.. image:: ./Pictures/10000001000001000000004B8B80A954F09BBF56.png - :width: 6.773cm - :height: 1.984cm - -- **Save database** overwrites the current database, so it is best to - be careful. Due to that, you will need to confirm a prompt before the - changes are saved. -- **Save database as** opens a file browser which can be used to save - the changes in a new file. - -Database menu -^^^^^^^^^^^^^ - -Clicking on Database opens this menu: - -.. image:: ./Pictures/10000001000000A900000052FEACFDD7C67801BA.png - :width: 4.329cm - :height: 1.99cm - -- **New element** allows you to add a new element. -- **New property** allows you to add a new property. - -.. _2d3dplotter: - -2D/3D Plotter -~~~~~~~~~~~~~ - -Upon clicking on the icon, this window will open: - -.. image:: ./Pictures/10000001000003DA000002B772D53BC965757606.png - :width: 12.173cm - :height: 8.58cm - -To use it, a file has to be loaded first. This can be done using the -File menu -> Load, which will open a file browser. Only NetCDF files -(ending in .nc, .cdf, or .netcdf) and HDF5 files (extension .h5 or .hdf) -can be loaded; other file formats will result in an error. - -.. image:: ./Pictures/1000000100000079000000510978F762503F30F6.png - :width: 3.201cm - :height: 2.081cm - -Once a file is loaded, it will appear in the data panel. This is a table -listing all the files loaded in the Plotter, showing the name MDANSE -assigned to the loaded instance (i.e. a key to e.g. distinguish between -files with the same name), the name of the file, and the full path to -the file. - -.. image:: ./Pictures/1000000100000130000000AFA255BACE473AB186.png - :width: 6.645cm - :height: 3.826cm - -Clicking on a loaded file will show all the variables that can be -plotted in the box below, though the whole Plotter window might have to -be resized so that more than one variable shows up at a time. A preview -of the plot of the first variable will also be shown at the bottom, but -only for 1D and 2D plots. - -|image9| - -Once you have selected a variable from the second box, you can select a -plotter from the Select Plotter drop-down menu. The following plotters -are available in MDANSE: - -+---------------------------+-----------+---------------------------+ -| Plotter | Dimension | Description | -+---------------------------+-----------+---------------------------+ -| Line | 1D | A simple plot depicting | -| | | the dependence of one | -| | | variable on another. It | -| | | consists of a single | -| | | line. Uses normal plot() | -| | | function from matplotlib. | -+---------------------------+-----------+---------------------------+ -| Image | 2D | Plots data as an image, | -| | | i.e. on a 2D regular | -| | | raster. Uses matplotlib | -| | | imshow() function. | -+---------------------------+-----------+---------------------------+ -| Elevation | 2D | Plots data as an image. | -| | | Uses VTK. | -+---------------------------+-----------+---------------------------+ -| 2D Slice | 2D | Plots a subset of a 3D | -| | | variable. | -| | | | -+---------------------------+-----------+---------------------------+ -| Isosurface | 3D | A 3D plot depicting a | -| | | surface through lines or | -| | | one continuous surface. | -| | | Uses VTK. | -+---------------------------+-----------+---------------------------+ -| Scalar-Field | 3D | | -| | | | -+---------------------------+-----------+---------------------------+ - -After all that is selected, the data can be plotted. There are two -options for this, represented by the two buttons: - -- **Plot in new window** creates a new tab, ie. a separate plot, inside - the Multiple Plot Window. - -|image10|\ |image11| - -- **Plot in current figure** plots the chosen data in the currently - selected tab of the Multiple Plot Window, ie. it will create a plot - with multiple lines etc. - -|image12|\ |image13| - -As can be seen, the plot automatically adjusts the axes so that all -plots fit. More details on plotting options is in `Appendix -3 <#_Appendix_3_1>`__. - -.. _units-editor: - -Units Editor -~~~~~~~~~~~~ - -When opened, this window will appear: - -.. image:: ./Pictures/1000000100000248000001ECCC3F9A11E0472AF2.png - :width: 9.693cm - :height: 8.167cm - -Here, the units that MDANSE uses can be managed. The white box on the -left is a list of all the defined units, which includes both the units -that come together with MDANSE as well as any user-defined units. More -information on how units work is in the `Units <#_Units>`__ section. -This list is interactive; any unit in it can be clicked on, which -displays its details, like so: - -.. image:: ./Pictures/1000000100000247000001E9C7FFA85698785E9D.png - :width: 9.804cm - :height: 8.142cm - -The fields in the middle and right of the window show the definition of -the selected unit using SI units. The selected unit is equivalent to -**Factor** \* the product of the SI units listed on the right, where the -values inside the fields are the powers of the SI units. Therefore, the -unit shown in the above example, J_per_mole, is in MDANSE defined as -1.66055927342 \* 10\ :sup:`-24` kg m\ :sup:`2` mol\ :sup:`-1`. - -There are four buttons in the Units Editor window: - -- **Cancel** closes the window without saving any changes made. -- **Save** saves the changes for future use; they can be used in the - current session and in any future ones. The Units Editor window is - also closed. -- **OK** saves the changes for the current session; they can be used - until the main MDANSE window is closed. When MDANSE is closed and - opened again, the changes will not appear. The Units Editor window is - also closed. -- **Add unit** opens the following window, which can be used to add new - units or edit existing ones. - -.. image:: ./Pictures/10000001000000C10000017909613E0AF9D5EED0.png - :width: 2.84cm - :height: 5.547cm - -- **Unit name** - -*Format:* str - -*Default:* None - -*Description:* the name of the unit. If a name not yet registered is -inputted, a new unit will be created. Please note that the names are -case-sensitive, and that already existing units cannot be overwritten. - -- **Factor** - -*Format:* float - -*Default:* 1.0 - -*Description:* - -- **unit** (any of the displayed SI basic units) - -*Format:* int (it must lie in the interval ) - -*Default:* 0 - -*Description:* the power of the SI unit. - -- **OK** adds the new definition to the unit registry, but the change - has to be saved in the Units Editor window to be useable in the rest - of MDANSE. Please not that once, a new unit is added, it cannot be - changed only removed. -- **Cancel** closes the window without saving the changes. - -Further, existing units can be deleted from the Units Editor window. To -do this, the unit to be deleted has to be selected by clicking on it, -and then the 'Delete' button has to be clicked. This will show a prompt -for confirmation, and once that is accepted, the unit will be removed, -though the change has to be saved by clicking on either the OK or Cancel -button. - -Data panel ----------- - -This is where files loaded into MDANSE are displayed. Trajectories and -results of analyses are distinctly separated as 'trajectory' and -'Hdf data' respectively. To proceed, you need to double-click on a -file name here to bring it to the Working panel. This can be done -multiple times for each file. - - -Working panel -------------- - -The selected files appear in the Working panel as tabs. The currently -opened tab is the one that whose file is going to be used for analysis -and other operations when using the Plugins panel. - -The Working panel is also the space which some of the plugins use to do -their job. :ref:`molecular-viewer`, -:ref:`analysis-animation`, and :ref:`2d3dplotter` plugins -all load into the `Working panel <#_Working_panel>`__. Furthermore, it -is possible to bring the windows opened by the other plugins into the -working panel, like below. To do that, you have to drag the window so -that its top is near the top of the working panel, where the tabs are. -An indicator will appear when you got it right. - - -Plugins panel -------------- - -This is the heart of MDANSE, where all the analyses as well as other -important features can be found. If the selected tab in the Working -panel is from a trajectory, the Plugins panel will look like this: - - -If it is from the result of an analysis, it will look like this: - -There are far fewer options available for analysis results. -Nevertheless, in each of the sections below, it will be stated if the -plugin appears for trajectories, results, or both. - -All the options in above are just headings. To get to the actual -plugins, click on the 'plus' buttons next to the text to unhide the -options. If there is no such button next to a text, that means that that -is a plugin and can be launched by double-clicking on the text. - - -.. _analysis: - -Analysis --------- - -This menu contains all data manipulations and appears as in the picture -below when a trajectory is loaded. As indicated by the plus buttons, -each of these options is a menu in itself. - -.. image:: ./Pictures/10000001000000F9000000B9A79707AE37EC9465.png - :width: 6.588cm - :height: 4.895cm - -They are explored in greater depth in the following sections, and the -analyses are in turn explored in their subsections. Some contain a -discussion of the theory behind the computation, and all show the -analysis window of that analysis, the one that is launched by -double-clicking the option in this Plugins panel. - -Each analysis window is different since each requires different -parameters to be configured before it can be run. However, all of them -have the same structure (example window below), consisting of these -parts: - -- **trajectory** box shows the path to the :ref:`netcdf` - trajectory that this analysis will - be performed on. - -- **Parameters** are a group of options, of which the common ones are - discussed in depth in :ref:`parameters`. These are the - options which vary from analysis to analysis. The only parameters - that exist on every analysis are Frames and Output files. - -- **Buttons** are situated at the bottom of each analysis and consist - of these options: - - - **Help** opens the source code documentation for the relevant - class in an MDANSE window. - - **Save** opens a file browser that allows you to save the current - analysis with the set options into a python script which can be - run from the command line. More information about scripts in - :ref:`mdanse-cli` and :ref:`mdanse-scripts`. - - **Run** starts the analysis and prompts you whether you want to - close the window. The status of the analysis can be found in the - `Jobs <#_Jobs>`__ panel, though there is a known bug where - successful analyses do not show up.