add tutorials to doc attempt2

Author: JaGeo

.github/workflows/docs.yml

@@ -36,7 +36,10 @@ jobs:
           pip install .[strict,docs]
 
       - name: Copy tutorials
-        run: cp -r tutorials docs/
+        run: |
+          cp -r tutorials docs/
+          jupyter nbconvert --to markdown docs/tutorials/*.ipynb
+          jupyter nbconvert --to markdown docs/tutorials/*/*.ipynb
 
       - name: Build
         run: sphinx-build docs docs_build

docs/index.md

@@ -9,6 +9,7 @@ user/docs-schemas-emmet
 user/fireworks
 user/atomate-1-vs-2
 user/codes/index
+tutorials/tutorials
 ```
 
 ```{toctree}

tutorials/force_fields/phonon_workflow.ipynb

@@ -1,12 +1,16 @@
 {
  "cells": [
   {
+   "metadata": {},
    "cell_type": "markdown",
-   "id": "0",
+   "source": "# Phonon Workflow Tutorial with Force Fields",
+   "id": "86e9d7e2e155339d"
+  },
+  {
    "metadata": {},
-   "source": [
-    "We start with imports necessary to test the tutorial automatically. In practice, you can load a structure file from any other place and you are also not required to generate the data in a temporary directory."
-   ]
+   "cell_type": "markdown",
+   "source": "We start with imports necessary to test the tutorial automatically. In practice, you can load a structure file from any other place and you are also not required to generate the data in a temporary directory.",
+   "id": "0"
   },
   {
    "cell_type": "code",

tutorials/openmm_tutorial.ipynb

@@ -1,15 +1,20 @@
 {
  "cells": [
   {
+   "metadata": {},
    "cell_type": "markdown",
-   "id": "0",
+   "source": "# OpenMM Tutorial",
+   "id": "ace71c1812743076"
+  },
+  {
    "metadata": {
     "jupyter": {
      "outputs_hidden": false
     }
    },
+   "cell_type": "markdown",
    "source": [
-    "### Installing Atomate2 From Source with OpenMM\n",
+    "## Installing Atomate2 From Source with OpenMM\n",
     "\n",
     "```bash\n",
     "# setting up our conda environment\n",
@@ -46,14 +51,15 @@
     "pip uninstall bson\n",
     "pip install pymongo\n",
     "```"
-   ]
+   ],
+   "id": "0"
   },
   {
    "cell_type": "markdown",
    "id": "1",
    "metadata": {},
    "source": [
-    "### Understanding Atomate2 OpenMM \n",
+    "## Understanding Atomate2 OpenMM\n",
     "\n",
     "Atomate2 is really just a collection of jobflow workflows relevant to materials science. In all the workflows, we pass our system of interest between different jobs to perform the desired simulation. Representing the intermediate state of a classical molecular dynamics simulation, however, is challenging. While the intermediate representation between stages of a periodic DFT simulation can include just the elements, xyz coordinates, and box vectors, classical molecular dynamics systems must also include velocities and forces. The latter is particularly challenging because all MD engines represent forces differently. Rather than implement our own representation, we use the `openff.interchange.Interchange` object, which catalogs the necessary system properties and interfaces with a variety of MD engines. This is the object that we pass between stages of a classical MD simulation and it is the starting point of our workflow."
    ]
@@ -63,7 +69,7 @@
    "id": "2",
    "metadata": {},
    "source": [
-    "### Pouring a Glass of Wine\n",
+    "## Pouring a Glass of Wine\n",
     "\n",
     "The first job we need to create generates the `Interchange` object. To specify the system of interest, we use give it the SMILES strings, counts, and names (optional) of the molecules we want to include."
    ]
@@ -173,7 +179,7 @@
    "id": "8",
    "metadata": {},
    "source": [
-    "### The basic simulation\n",
+    "## The basic simulation\n",
     "\n",
     "To run a production simulation, we will create a production flow, link it to our `elyte_interchange_job`, and then run both locally.\n",
     "\n",
@@ -245,7 +251,7 @@
    "id": "11",
    "metadata": {},
    "source": [
-    "### Configuring the Simulation\n",
+    "## Configuring the Simulation\n",
     "\n",
     "All OpenMM jobs, i.e. anything in `atomate2.openmm.jobs`, inherits from the `BaseOpenMMMaker` class. `BaseOpenMMMaker` is highly configurable, you can change the timestep, temperature, reporting frequencies, output types, and a range of other properties. See the docstring for the full list of options.\n",
     "\n",
@@ -277,7 +283,7 @@
    "id": "14",
    "metadata": {},
    "source": [
-    "### Running with Databases\n",
+    "## Running with Databases\n",
     "\n",
     "Before trying this, you should have a basic understanding of JobFlow and [Stores](https://materialsproject.github.io/jobflow/stores.html).\n",
     "\n",
@@ -366,7 +372,7 @@
    "id": "15",
    "metadata": {},
    "source": [
-    "### Running on GPU(s)\n",
+    "## Running on GPU(s)\n",
     "\n",
     "Running on a GPU is nearly as simple as running on a CPU. The only difference is that you need to specify the `platform_properties` argument in the `EnergyMinimizationMaker` with the `DeviceIndex` of the GPU you want to use."
    ]

tutorials/phonon_workflow.ipynb

@@ -30,9 +30,7 @@
    "cell_type": "markdown",
    "id": "2",
    "metadata": {},
-   "source": [
-    "# Phonon Workflow"
-   ]
+   "source": "# Phonon Workflow Tutorial with VASP"
   },
   {
    "cell_type": "markdown",

tutorials/qha_workflow.ipynb

@@ -1,12 +1,16 @@
 {
  "cells": [
   {
+   "metadata": {},
    "cell_type": "markdown",
-   "id": "0",
+   "source": "# Quasi-harmonic Workflow Tutorial with VASP",
+   "id": "b2ab3e6e84f7233b"
+  },
+  {
    "metadata": {},
-   "source": [
-    "This first part is only needed as we have to mock VASP here as we cannot run it directly in a jupyter notebook:"
-   ]
+   "cell_type": "markdown",
+   "source": "This first part is only needed as we have to mock VASP here as we cannot run it directly in a jupyter notebook:",
+   "id": "0"
   },
   {
    "cell_type": "code",
@@ -51,14 +55,6 @@
     "}"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "2",
-   "metadata": {},
-   "source": [
-    "QHA workflow"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "3",
@@ -263,6 +259,12 @@
     "    )"
    ]
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "## Let's retrieve the data and analyze it",
+   "id": "2dc7b73048bebabf"
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -307,7 +309,7 @@
     "    strict=False,\n",
     "):\n",
     "    # Create the plot\n",
-    "    plt.plot(result[\"output\"][\"volumes\"], energy_list, marker=\"o\")\n",
+    "    plt.plot(result[\"output\"][\"volumes\"], energy_list, marker=\"o\", label=temp)\n",
     "    # Add labels and title\n",
     "plt.xlabel(\"Volume\")\n",
     "plt.ylabel(\"Free Energy\")\n",

tutorials/tutorials.md

@@ -0,0 +1,16 @@
+(tutorials)=
+
+# Tutorials
+
+The section includes tutorials for workflows in atomate2. 
+They can also be found in the form of jupyternotebooks in:
+[https://github.com/materialsproject/atomate2/tree/main/tutorials](https://github.com/materialsproject/atomate2/tree/main/tutorials)
+
+```{toctree}
+blob_storage
+lobster_workflow
+openmm_tutorial
+phonon_workflow
+qha_workflow
+force_fields/phonon_workflow
+```