adding files of the tutorial

.gitattributes

+*.zip filter=lfs diff=lfs merge=lfs -text
+*.json filter=lfs diff=lfs merge=lfs -text

.gitignore

-tutorial/
-
 
 .idea/
 .ipython/

tutorial/Tutorial-1_Uploading_MD_Data/Exercise_Answers.md

+### <u> **Exercise Answers** </u>
+
+1. OW, HW1, and HW2 (see **run** &rarr; **method** &rarr; **atom_parameters** &rarr; *atom_index* &rarr; **label**)
+
+2. step = 5000, time = 5 ps (see **system** &rarr; **10** &rarr; **step** and **system** &rarr; **10** &rarr; **time**, respectively)
+
+3. thermostat = "langevin_goga", frequency of coupling = 500 fs (see **workflow** &rarr; **molecular_dynamics** &rarr; **integration_parameters** &rarr; **thermostat_parameters** &rarr; **thermostat_type** and **workflow** &rarr; **molecular_dynamics** &rarr; **integration_parameters** &rarr; **thermostat_parameters** &rarr; **coupling_constant**, respectively).
+

tutorial/Tutorial-1_Uploading_MD_Data/Tutorial-1_Uploading_MD_Data.md

+## <center> **Tutorial 1: Uploading molecular dynamics data and examining the metadata** </center>
+
+NOMAD currently supports 2 molecular dynamics codes: Gromacs and Lammps. Here, we will walk you through uploading data from a series of simulations run in Gromacs.
+
+In the current directory (`Tutorial-1_Uploading_MD_Data/`), unzip the file `data/water_workflow.zip`. Take a minute to example the directory structure. If you are familiar with Gromacs you will immediately see the input/output from 3 simulations: an energy minimization (`Emin/`), an NPT equilibration (`Equil-NPT/`), and an NVT production run (`Prod-NVT/`). In the main directory, you will also see a .yaml file, which contains the NOMAD schema for connecting these 3 simulations into a workflow. This will be covered in Tutorial 2.
+
+In your browser, go to the [NOMAD home page](https://nomad-lab.eu/). At the bottom of the page, click on the NOMAD beta button:
+
+<p align="center">
+  <img src="Images/NOMAD_beta_button.png" />
+</p>
+
+Use the button on the top right to login or, if you are a new user, register for a NOMAD account.  Once you are logged in, at the top left of the page, go to **PUBLISH** &rarr; **UPLOADS**:
+
+<p align="center">
+  <img src="Images/NOMAD_uploads_button.png" />
+</p>
+
+Click **CREATE A NEW UPLOAD**, and then you can either drop the `water_workflow.zip` file directly or click **CLICK OR DROP FILES** to find the file within your file system. Note that there is currently a 32GB file size limit per upload. This will likely be expanded in the future, and exceptions can be received by contacting the NOMAD team. NOMAD's approach to the large data sets generated by molecular dynamics simulations is still under development. A deeper discussion of this topic is beyond the scope of this initial tutorial series, but will be addressed in the future.
+
+At this point, NOMAD will unzip your upload and automatically detect all possible "main" files corresponding to output from supported codes (in this case, the `.log` file from each Gromacs simulation). NOMAD will then proceed to parse all the relevant simulation files and store the simulation data and *metadata* within the NOMAD *Metainfo* schema. In this case, the parsing should take ~ 30 seconds. You should now see the successfully processed data overview:
+
+<p align="center">
+  <img src="Images/Processed_data_edited.png" />
+</p>
+
+Let's examine the production simulation by clicking the 3 dots to the right of the entry labeled `Prod-NVT/mdrun_Prod-NVT.log`, circled in green in the above image. You will now be on the **OVERVIEW** page for this entry, which aims to provide a simple description of this entry through visualizations of the system itself, some key observables, and some of the overarching metadata. The **OVERVIEW** page will be examined in detail in Tutorial 2. For now, we will focus on how the uploaded data is stored within the NOMAD repository. In addition to the **OVERVIEW** tab, there are 3 other tabs at the top of the page: **FILES**, **DATA**, and **LOGS**.
+
+Click on the **FILES** tab. Here you will find all the raw data that was uploaded via the .zip file, retained within the original file system structure. The raw files are stored in the repository and can be downloaded at any time.
+
+Now click on the **LOGS** tab. Here you will find some technical information about the data processing along with any warnings or errors that were raised by the NOMAD software.
+
+Finally, click on the **DATA** tab. Here you can navigate through the NOMAD *Metainfo* for this entry, i.e., the processed and normalized version of the simulation data and metadata.
+
+Navigate to section **run** &rarr; **program**, where we find some basic information about the simulation code (name and version):
+
+<p align="center">
+  <img src="Images/Run_Program.png" />
+</p>
+
+Now navigate to section **run** &rarr; **method**:
+
+<p align="center">
+  <img src="Images/Run_Method.png" />
+</p>
+
+Under **atom_parameters** you will find a list of force-field-dependent atom attributes such as mass and charge. Under **force_field** &rarr; **model** &rarr; **contributions** you will find a list of intramolecular interactions defined for this simulation. The development of metadata for a more comprehensive storage of force fields in NOMAD is currently underway. Under **force_field** &rarr; **force_calculations** you will find some basic input parameters dealing with the calculation of forces in this simulation.
+
+Navigate to section **run** &rarr; **system** &rarr; **0**:
+
+<p align="center">
+  <img src="Images/Run_System_0.png" />
+</p>
+
+The **system** section holds the configurational information from this entry. The first item in this section, **0**, corresponds to the first saved configuration within the simulation trajectory. Now click on the atoms section:
+
+<p align="center">
+  <img src="Images/Run_System_0_Atoms.png" />
+</p>
+
+There will be a prompt to ask if you would like to visualize the system. If you click yes, the particles within the simulation box will be displayed. (The visualizer can also be accessed with additional features in the **OVERVIEW** page). In the **atoms** section, various atom attributes are stored, e.g., the positions and velocities of each atom for this frame. Notice that the simulation trajectory is stored as a list of repeating dictionaries, as opposed to the typical dictionary of lists that may be found in trajectory analysis software, such as *MDAnalysis*. In short, this is done for consistency with data from other methods that are stored in the NOMAD repository. However, when working with the data from a particular entry, there are tools in NOMAD to easily convert the *Metainfo* to a more convenient format for analysis. More about this in Tutorial 3.
+
+Now click on the **atoms_group** section:
+
+<p align="center">
+  <img src="Images/Run_System_0_AtomsGroup.png" />
+</p>
+
+This section holds a hierarchical organization of the system (denoted in the following as the *topology*), based on the *bonds* defined in the force field used for this simulation. By default, the first level of this hierarchy contains *molecule groups*, which group together all molecules of the same type. Now, by clicking the **atoms_group** subsection of this group, you reach the next level down, which contains each molecule within the current molecule group. Similarly to these molecule groups and molecule levels, monomer groups and monomer levels will be defined for polymer systems. The individual atoms within each molecule are not explicitly stored within this hierarchy, but are simply referenced via their indices within the **atoms** section. Take a few minutes to examime this hierarchy and the stored quantities in more detail. Note that at the moment the hierarchy is only stored in the first entry of **system**.
+
+Now go back and navigate to section **run** &rarr; **calculation** &rarr; **0**:
+
+<p align="center">
+  <img src="Images/Run_Calculation_0.png" />
+</p>
+
+The **calculation** section contains any saved thermodynamic quantities that are a function of a single configuration, e.g., energy, pressure, temperature, etc., as well as any saved force information for the atoms within each configuration.
+
+### <u> **Exercises** </u>
+
+1. What are the oxygen and hydrogen atom types used in the force field for this simulation?
+
+2. What is the step number of the last saved configuration of this simulation? What is the corresponding time for this configuration?
+
+3. (CHALLENGE) Which thermostat is used for temperature coupling in this simulation? What is the frequency of temperature coupling?
+

tutorial/Tutorial-2_MD_Overview_Page_and_Workflow_Visualizer/Exercise_Answers.md

+### <u> **Exercise Answers** </u>
+
+1. This is an NVT annealing simulation to cool the system from ~1000 k to ~300 k. As the temperature cools, the molecules aggregate, as indicated by the growing peaks in the rdfs. However, the pressure remains low due to the (fixed) large box size.
+
+2. This is an NPT simulation, performed at ~300 k. Mid-way through the simulation there is a clear transition in the potential energy and an increase in the pressure, indicating that the box is contracting and the system is entering a proper liquid phase. This is validated through the rdfs, which become properly normalized to 1 at large distances later in the trajectory.
+
+3. This is a fully equilibrated NPT simulation.
+

tutorial/Tutorial-2_MD_Overview_Page_and_Workflow_Visualizer/Tutorial-2_Overview_Page_and_Worfklow_Visualizer.md

+## <center> **Tutorial 2: Molecular dynamics overview page and workflow visualizer** </center>
+
+In this tutorial, we will examine the GUI features for molecular dynamics simulations in NOMAD, using as an example a simulation workflow of setting up and equilibrating a binary liquid mixture. For convenience, the simulation data has been pre-parsed and is provided in the NOMAD *Metainfo* format.
+
+In the current directory (`Tutorial-2_MD_Overview_Page_and_Workflow_Visualizer/`), you will find the file `data/binary_mixture_pre-parsed.zip`. Upload the file to [NOMAD](https://nomad-lab.eu/), as demonstrated in Tutorial 1. In the upload page, you should see 6 identified main files: `workflow_archive.json`, &nbsp; `minimEQ1_archive.json`, &nbsp; `EQ1_archive.json`, &nbsp; `EQ2_archive.json`, &nbsp; `EQ3_archive.json`, and &nbsp; `PD1_archive.json`. &nbsp; `workflow_archive.json` corresponds to a workflow entry that describes how the other main files are related to each other. Click on the 3 dots to the right of this workflow entry. You should see a workflow graph:
+
+<p align="center">
+  <img src="Images/workflow_graph.png" />
+</p>
+
+The inputs and outputs of the workflow are depicted with light blue circles. Clicking on the text label above these circles will take you to the *Metainfo* section within the **DATA** tab of the corresponding entry. The dark blue circles represent sub-workflows within this workflow. Here we have a linear workflow consisting of a geometry optimization (i.e., energy minimization), followed by 4 molecular dynamics simulations. Because only a single configuration was saved from the energy minimization (i.e., the final configuration), this configuration by default acts as the input for the entire workflow, and is also the input for the first molecular dynamics simulation.
+
+Scroll down to the bottom of the page, where you will see references to each entry within the workflow. Click on the 3 dots next to the &nbsp; `minimEQ1_archive.json` entry. This will take you to the **OVERVIEW** page of the energy minimization step of the workflow.
+
+At the top of this page is the **Material** section, which provides an overview of the system, including a visualizer (activated by clicking *YES* on the prompt, as in Tutorial 1). To the left of the visualizer, there is an *accordion menu* displaying the molecular topology. By default, the entire system is selected. By selecting one of the molecule groups (**GROUP_MOL** or **GROUP_MON** in this case), the visualizer will display only molecules of the selected type and make all other molecules transparent. Beneath each molecule group is a representative molecule tab, which will display a single molecule of that type in the visualizer when clicked.
+
+Now scroll down to the **Geometry optimization** section. This energy minimization run is automatically labeled as a *geometry optimization* workflow, and the energy convergence plot is displayed in the overview page if the relevant data is available.
+
+Scroll down to the **Workflow Graph** section. Here an automatically generated workflow graph is displayed for this entry only. Notice the *Workflow parameters* input and the *Workflow results* output. Take a few minutes to examine these sections in the *Metainfo* by clicking their text labels.
+
+At the bottom of the page, there is an **Entry References** section, which links you to the overall workflow that we examined at the beginning of the tutorial. Click on the 3 dots next to this entry to return to the global workflow page for this upload.
+
+Let's now examine the first molecular dynamics run of this workflow. Click on the *Molecular Dynamics* text label above the first dark blue circle with this label. This will take you to the corresponding overview page. The **Material** section is identical to the energy minimization entry, since all entries in this upload correspond to simulations of the same system.
+
+Scroll down to the **Thermodynamic properties** section. Here we find plots of the time trajectories of various thermodynamic quantities: temperature, pressure, and potential energy in this case. At the bottom of the section some basic information about the molecular dynamics run are displayed: the timestep and the thermodynamic ensemble. We can see immediately that this *NVT* simulation was run at ~1000 K and at a very low pressure (gas phase, in line with what we observed in the visualizer).
+
+Scroll down to the **Structural properties** section. Once a molecular dynamics workflow is detected, the NOMAD software automatically tries to calculate radial distribution functions (rdfs) as a function of the molecular center of mass for each unique pair of molecule types. These rdfs are determined for various intervals of the trajectory, as a zeroth order measure of equilibration. As expected for the gas phase, the rdfs converge quite quickly here.
+
+Scroll down to the **Dynamical properties** section. Similar to the rdfs, NOMAD also calculated the molecular mean squared displacements for each molecule type. (Note that this requires at least 50 time frames present in the trajectory). A simple linear fitting procedure over the entire resulting msd curve is performed to determine the diffusion constant (displayed in the legend along with the corresponding *Pearson correlation coefficient*).
+
+Again, subsequent sections display the workflow graph for this entry and the reference to the global workflow for this upload. Now go back to the global workflow overview page. Take some time to examine the overview pages for the remainder of the molecular dynamics runs within the overall workflow for this upload, and answer the corresponding questions below.
+
+### <u> **Exercises** </u>
+
+Provide a description of the molecular dynamics run (for example, which ensemble? what temperature? is the system equilibrated? what phase is the system in?) for:
+
+1. the second molecular dynamics run within this workflow
+
+2. the third molecular dynamics run within this workflow
+
+3. the fourth molecular dynamics run within this workflow
+