192 add and test tutorials in documentation

.github/workflows/ci.yml

@@ -70,6 +70,26 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
+
+    services:
+      postgres:
+        image: postgres:10
+        env:
+          POSTGRES_DB: test_aiida
+          POSTGRES_PASSWORD: ''
+          POSTGRES_HOST_AUTH_METHOD: trust
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+      rabbitmq:
+        image: rabbitmq:latest
+        ports:
+          - 5672:5672
+
     steps:
       - uses: actions/checkout@v4
 
@@ -79,8 +99,27 @@ jobs:
           version: "0.6.14"
           python-version: "3.12"
 
+      - name: Install pandoc
+        uses: pandoc/actions/setup@v1
+
       - name: Install dependencies
-        run: uv sync
+        run: |
+          uv sync --group docs
+          uv venv janus
+          source janus/bin/activate
+          uv pip install "janus_core[mace]" matplotlib-inline
+          deactivate
+
+      - name: Setup verdi
+        run: |
+          uv run verdi presto --use-postgres
+          uv run verdi code create core.code.installed -n \
+             -Y localhost \
+             -X janus \
+             -L janus \
+             -P mlip.sp \
+             --prepend-text "source $(pwd)/janus/bin/activate" \
+             --append-text "deactivate"
 
       - name: Build docs
         run: uv run make html

.github/workflows/docs.yml

@@ -23,6 +23,25 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
 
+    services:
+      postgres:
+        image: postgres:10
+        env:
+          POSTGRES_DB: test_aiida
+          POSTGRES_PASSWORD: ''
+          POSTGRES_HOST_AUTH_METHOD: trust
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+      rabbitmq:
+        image: rabbitmq:latest
+        ports:
+          - 5672:5672
+
     steps:
       - uses: actions/checkout@v4
 
@@ -32,8 +51,27 @@ jobs:
           version: "0.6.14"
           python-version: "3.12"
 
+      - name: Install pandoc
+        uses: pandoc/actions/setup@v1
+
       - name: Install dependencies
-        run: uv sync
+        run: |
+          uv sync --group docs
+          uv venv janus
+          source janus/bin/activate
+          uv pip install "janus_core[mace]" matplotlib-inline
+          deactivate
+
+      - name: Setup verdi
+        run: |
+          uv run verdi presto --use-postgres
+          uv run verdi code create core.code.installed -n \
+             -Y localhost \
+             -X janus \
+             -L janus \
+             -P mlip.sp \
+             --prepend-text "source $(pwd)/janus/bin/activate" \
+             --append-text "deactivate"
 
       - name: Build docs
         run: uv run make html

docs/source/conf.py

@@ -42,6 +42,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinxcontrib.contentui",
+    "nbsphinx",
 ]
 
 # Add the numpydoc_show_inherited_class_members option
@@ -201,6 +202,22 @@
     ("py:class", "QbFields"),
     ("py:class", "aiida_workgraph.workgraph.WorkGraph"),
     ("py:class", "AiidaLoggerType"),
+    # AiiDA internal classes not exposed in intersphinx
+    ("py:class", "aiida.engine.processes.calcjobs.calcjob.CalcJob"),
+    ("py:class", "aiida.common.folders.Folder"),
+    ("py:class", "aiida.engine.processes.process_spec.CalcJobProcessSpec"),
+    ("py:class", "aiida.common.datastructures.CalcInfo"),
+    ("py:class", "aiida.engine.processes.ports.PortNamespace"),
+    ("py:class", "aiida.orm.nodes.data.singlefile.SinglefileData"),
+    ("py:class", "aiida.orm.nodes.data.structure.StructureData"),
+    ("py:class", "aiida.orm.nodes.data.array.trajectory.TrajectoryData"),
+    ("py:class", "aiida.orm.nodes.process.process.ProcessNode"),
+    ("py:class", "aiida.parsers.parser.Parser"),
+    ("py:class", "aiida.engine.processes.exit_code.ExitCode"),
+    ("py:class", "aiida.engine.processes.workchains.workchain.WorkChain"),
+    ("py:class", "aiida.orm.nodes.data.str.Str"),
+    ("py:class", "aiida.orm.utils.managers.NodeLinksManager"),
+    ("py:class", "plumpy.utils.AttributesFrozendict"),
 ]
 
 
@@ -247,3 +264,5 @@ def run_apidoc(_):
 
 def setup(app):
     app.connect("builder-inited", run_apidoc)
+
+nbsphinx_allow_errors = False

docs/source/developer_guide/index.rst

@@ -146,7 +146,7 @@ Building the documentation
 Packages in the ``docs`` dependency group install `Sphinx <https://www.sphinx-doc.org>`_
 and other Python packages required to build ``aiida-mlip``'s documentation.
 
-Individual individual documentation pages can be edited directly::
+Individual documentation pages can be edited directly::
 
         docs/source/index.rst
         docs/source/developer_guide/index.rst

docs/source/user_guide/get_started.rst

@@ -80,3 +80,6 @@ These are the available calculations
    * Train
 
 For more details on the calculations, please refer to the `calculations section <https://stfc.github.io/aiida-mlip/user_guide/calculations.html>`_.
+
+If you would like a refresher on how to use AiiDA in general, please refer to the `AiiDA user guide <https://aiida.readthedocs.io/projects/aiida-core/en/stable/user_guide/index.html>`_.
+An excellent introduction to Aiida Basics can be found in the `AiiDA Basics tutorial <https://aiida-tutorials.readthedocs.io/en/latest/sections/getting_started/basics.html>`_.

docs/source/user_guide/index.rst

@@ -10,3 +10,7 @@ User guide
     data
     calculations
     training
+    notebooks/singlepoint
+    notebooks/descriptors
+    notebooks/geometry-optimisation
+    notebooks/high-throughput-screening

docs/source/user_guide/notebooks/config_sp.yaml

@@ -0,0 +1,5 @@
+arch: mace_mp
+calc-kwargs:
+    calc_kwargs:
+      dispersion: True
+properties: [energy]

examples/tutorials/calculations/descriptors.ipynb → docs/source/user_guide/notebooks/descriptors.ipynb

@@ -180,7 +180,7 @@
     "id": "BhWwGwm2uvYR"
    },
    "source": [
-    "In this case, since we are running a single point calculation the entry point for the calculation is `mlip.sp`.\n",
+    "In this case, since we are running a descriptors calculation the entry point for the calculation is `mlip.descriptors`.\n",
     "Finally, run the calculation:\n"
    ]
   },
@@ -203,7 +203,7 @@
     "id": "OSt6cQMeu5w9"
    },
    "source": [
-    "`result` is a dictionary of the available results obtained from the calculation, while node contains the infor on the node where the calculation is run:\n"
+    "`result` is a dictionary of the available results obtained from the calculation, while node contains the info on the node where the calculation is run:\n"
    ]
   },
   {
@@ -232,7 +232,7 @@
    "outputs": [],
    "source": [
     "if node.is_finished_ok:\n",
-    "    print(f\"Caculation is finished without errors with exit status {node.exit_status}\")\n",
+    "    print(f\"Calculation is finished without errors with exit status {node.exit_status}\")\n",
     "else:\n",
     "    print(f\"Some errors occurred with exit status {node.exit_status}\")"
    ]
@@ -308,7 +308,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "! verdi calcjob res pk"
+    "! verdi calcjob res {node.pk}"
    ]
   },
   {
@@ -324,7 +324,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "! verdi node show pk  "
+    "! verdi node show {node.pk}"
    ]
   }
  ],
@@ -334,7 +334,7 @@
    "provenance": []
   },
   "kernelspec": {
-   "display_name": "venv_aiida_11",
+   "display_name": "aiida-mlip",
    "language": "python",
    "name": "python3"
   },
@@ -348,7 +348,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.10"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

examples/tutorials/calculations/geometry-optimisation.ipynb → docs/source/user_guide/notebooks/geometry-optimisation.ipynb

@@ -153,7 +153,6 @@
     "        \"fmax\": Float(0.1), \n",
     "        \"opt_cell_lengths\": Bool(False), \n",
     "        \"opt_cell_fully\": Bool(True),\n",
-    "        \"pressure\": Float(0.0),\n",
     "        \"minimize_kwargs\": Dict({\"filter_kwargs\": {\"constant_volume\": True}}),\n",
     "        \"metadata\": {\"options\": {\"resources\": {\"num_machines\": 1}}},\n",
     "    }"
@@ -220,7 +219,7 @@
     "id": "OSt6cQMeu5w9"
    },
    "source": [
-    "`result` is a dictionary of the available results obtained from the calculation, while node contains the infor on the node where the calculation is run:\n"
+    "`result` is a dictionary of the available results obtained from the calculation, while node contains the info on the node where the calculation is run:\n"
    ]
   },
   {
@@ -294,7 +293,8 @@
    },
    "outputs": [],
    "source": [
-    "! verdi calcjob res PK"
+    "# ! verdi calcjob res 1 #for example if you want to see results of calcjob with PK=1\n",
+    "! verdi calcjob res {node.pk}"
    ]
   },
   {
@@ -310,7 +310,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "! verdi node show PK"
+    "# ! verdi node show PK #for example if you want to see info of node with PK=1\n",
+    "! verdi node show {node.pk}"
    ]
   },
   {
@@ -331,7 +332,8 @@
     "from aiida.orm import load_node\n",
     "\n",
     "print(f\"Initial cell parameters: {structure.cell}\")\n",
-    "final_structure = load_node(PK)\n",
+    "#final_structure = load_node(PK) where PK is the final structure node and should be replaced with the correct PK as found above\n",
+    "final_structure = node.outputs.final_structure\n",
     "print(f\"Final cell parameters: {final_structure.cell}\")"
    ]
   },
@@ -363,8 +365,8 @@
     "from aiida.engine import calcfunction\n",
     "\n",
     "\n",
-    "#traj = node.outputs.traj_output\n",
-    "traj = load_node(PK) \n",
+    "traj = node.outputs.traj_output\n",
+    "# traj = load_node(PK) \n",
     "    \n",
     "@calcfunction\n",
     "def prepare_struct_inputs(traj, index):\n",
@@ -396,7 +398,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let's print the list of alcjob nodes that we just created"
+    "Let's print the list of calcjob nodes that we just created"
    ]
   },
   {
@@ -463,7 +465,7 @@
    },
    "outputs": [],
    "source": [
-    "! verdi node graph generate PK"
+    "! verdi node graph generate {node.pk} "
    ]
   },
   {
@@ -481,7 +483,7 @@
    "provenance": []
   },
   "kernelspec": {
-   "display_name": "venv_aiida_11",
+   "display_name": "aiida-mlip",
    "language": "python",
    "name": "python3"
   },
@@ -495,7 +497,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.10"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,