Add tutorial for to setting up an external computer (#214)

Co-authored-by: Elliott Kasoar <[email protected]>

Author: MM0hsin

examples/tutorials/config_computer.yml renamed to examples/tutorials/aiida_setup/config_computer.yml

@@ -0,0 +1,249 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "afe742d7",
+   "metadata": {},
+   "source": [
+    "# Setting up an external computer"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "927e4a25",
+   "metadata": {},
+   "source": [
+    "## Aim"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1c46a870",
+   "metadata": {},
+   "source": [
+    "This tutorial walks through the steps that may be required to submit AiiDA jobs to an external computer, including configuring a new profile, setting up the remote computer, configuring the transport layer and creating an external code."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1ab75593",
+   "metadata": {},
+   "source": [
+    "## Setup"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e7ba5ac9",
+   "metadata": {},
+   "source": [
+    "For this tutorial we will assume you have:\n",
+    "\n",
+    "<ul>\n",
+    "        <li>AiiDA installed locally</li>\n",
+    "        <li>Quantum Espresso installed on the remote computer</li>\n",
+    "</ul>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f16a8c8e",
+   "metadata": {},
+   "source": [
+    "### Profile"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "01a1e762",
+   "metadata": {},
+   "source": [
+    "For simplicity, we will use `verdi presto` to set up our profile, which creates a profile and default user, sets up the localhost computer, and configures the database. \n",
+    "\n",
+    "By default, this will use SQLite for the database, and RabbitMQ will be configured if it is discoverable, but it is not required.\n",
+    "\n",
+    "\n",
+    "For production work, PostgreSQL and RabbitMQ are both strongly recommended, which can be configured either through `verdi presto`, or manually through `verdi profile setup`.\n",
+    "\n",
+    "Please refer to the [AiiDA's \"Create a Profile\" documentation](https://aiida.readthedocs.io/projects/aiida-core/en/stable/installation/guide_complete.html#create-a-profile) for more details."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1bdc9a19",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! verdi presto -p scarf"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a4c7c122",
+   "metadata": {},
+   "source": [
+    "### Computer"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a6696a1e",
+   "metadata": {},
+   "source": [
+    "We will set up the remote computer, STFC's [SCARF HPC cluster](https://www.scarf.rl.ac.uk) in this example. The values in square brackets should be changed as required for your remote system.\n",
+    "\n",
+    "For more information on these settings, refer to the [AiiDA's \"Computer Setup\" documentation](https://aiida.readthedocs.io/projects/aiida-core/en/stable/howto/run_codes.html#computer-setup).\n",
+    "\n",
+    "**Note:** We are loading the module we want in `prepend_text`. As we will be needing Quantum Espresso to load the code in the later steps we will load it now, otherwise you can leave it empty (`prepend_text: ''`)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "65057015",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%writefile ~/computer.yaml\n",
+    "label: [scarf]\n",
+    "description: [https://www.scarf.rl.ac.uk/index.html]\n",
+    "hostname: [ui1.scarf.rl.ac.uk]\n",
+    "transport: core.ssh\n",
+    "scheduler: core.slurm\n",
+    "shebang: '#!/bin/bash'\n",
+    "work_dir: [/work4/scd/scarf/aiida]\n",
+    "mpirun_command: srun -u -n {tot_num_mpiprocs}\n",
+    "mpiprocs_per_machine: 32\n",
+    "use_double_quotes: False\n",
+    "prepend_text: |\n",
+    "  module load amd-modules\n",
+    "  module load QuantumESPRESSO/7.2-foss-2023a\n",
+    "append_text: ''"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c7b34fe6",
+   "metadata": {},
+   "source": [
+    "Run the following commands. First we set up the computer."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "811e10d3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! verdi computer setup -n --config ~/computer.yaml"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "963d43fa",
+   "metadata": {},
+   "source": [
+    "If you have an SSH config file setup in ~/.ssh/config, AiiDA can automatically parse most of the required information to set up the transport layer, as described in the [\"AiiDA Configuration\" documentation](https://aiida.readthedocs.io/projects/aiida-core/en/stable/howto/ssh.html#id1).\n",
+    "\n",
+    "If not, we can configure the computer for the ssh transport manually. Make sure to change the settings in square brackets with your settings.\n",
+    "\n",
+    "[AiiDA's \"Computer Connection Configuration\" documentation](https://aiida.readthedocs.io/projects/aiida-core/en/stable/howto/run_codes.html#computer-connection-configuration) goes over how to configure a computer in more detail."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "eaf2e067",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! verdi computer configure core.ssh [scarf] -n --username [scarf] --key-filename ['/path/to/ssh/key'] --key-policy AutoAddPolicy --safe-interval 30.0"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a8fccf0e",
+   "metadata": {},
+   "source": [
+    "Once the computer is set up, you can test the connection"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ce2132c3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! verdi computer test [scarf]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "25efa7b3",
+   "metadata": {},
+   "source": [
+    "### External Code"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c376a8be",
+   "metadata": {},
+   "source": [
+    "If you want to run a calculation that is only available on the external machine, you can set up a code which accesses the external library. For more information, use `verdi code create -h`, or refer to the [AiiDA \"Create a Code\" documentation](https://aiida.readthedocs.io/projects/aiida-core/en/stable/howto/run_codes.html#how-to-create-a-code)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "475b35b9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%writefile ~/qe_code.yaml\n",
+    "label: qe\n",
+    "description: Quantum ESPRESSO pw.x\n",
+    "default_calc_job_plugin: quantumespresso.pw\n",
+    "computer: scarf\n",
+    "filepath_executable: /work4/scd/scarf562/eb-amd/software/QuantumESPRESSO/7.2-foss-2023a/bin/pw.x\n",
+    "use_double_quotes: true\n",
+    "prepend_text: ''\n",
+    "append_text: ''"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c354f007",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! verdi code create core.code.installed -n --config ~/qe_code.yaml"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "aiida-mlip (3.12.3)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/tutorials/config_profile.yml renamed to examples/tutorials/aiida_setup/config_profile.yml

@@ -80,7 +80,9 @@
    "outputs": [],
    "source": [
     "Calculation = CalculationFactory(\"mlip.sp\")\n",
-    "model = ModelData.from_local(\"mlips/mace_mp/mace_mp_small.model\", architecture=\"mace_mp\")\n",
+    "uri = \"https://github.com/stfc/janus-core/raw/main/tests/models/mace_mp_small.model\"\n",
+    "model = ModelData.from_uri(uri, architecture=\"mace_mp\")\n",
+    "# model = ModelData.from_local(\"path/to/model\", architecture=\"mace_mp\")\n",
     "metadata = {\"options\": {\"resources\": {\"num_machines\": 1}}}\n",
     "code = load_code(\"janus@localhost\")"
    ]
@@ -98,7 +100,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "conf = JanusConfigfile(\"/home/jovyan/config_sp.yaml\")"
+    "conf = JanusConfigfile(Path(\"config_sp.yaml\").absolute())"
    ]
   },
   {
@@ -274,7 +276,7 @@
    "provenance": []
   },
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "aiida-mlip (3.12.3)",
    "language": "python",
    "name": "python3"
   },
@@ -288,7 +290,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,