jobflow.ipynb

{
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11.0",
   "mimetype": "text/x-python",
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "pygments_lexer": "ipython3",
   "nbconvert_exporter": "python",
   "file_extension": ".py"
  }
 },
 "nbformat_minor": 4,
 "nbformat": 4,
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "# jobflow"
   ],
   "metadata": {}
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "[`jobflow`](https://materialsproject.github.io/jobflow/index.html) and [`atomate2`](https://materialsproject.github.io/atomate2/index.html) are key packages of the [Materials Project](https://materialsproject.org/) . `jobflow` was especially designed to simplify the execution of dynamic workflows -- when the actual number of jobs is dynamically determined upon runtime instead of being statically fixed before running the workflow(s). `jobflow`'s overall flexibility allows for building workflows that go beyond the usage in materials science. `jobflow` serves as the basis of `atomate2`, which implements data generation workflows in the context of materials science and will be used for data generation in the Materials Project in the future.  "
   ]
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Installation / Setup\n",
    "`jobflow` can be installed via `pip install` and directly run with the default setup. It will then internally rely on a memory database as defined in the software package [`maggma`](https://materialsproject.github.io/maggma/). For large-scale usage, a [MongoDB](https://www.mongodb.com/)-like database might be specified in a jobflow.yaml file.\n",
    "A high-throughput setup (i.e., parallel execution of independent parts in the workflow) of `jobflow` can be achieved using additional packages like [`fireworks`](https://materialsproject.github.io/fireworks/) or [`jobflow-remote`](https://matgenix.github.io/jobflow-remote/). Both packages require a MongoDB database. In case of `FireWorks`, however, the MongoDB database needs to be directly connected to the compute nodes. `jobflow-remote` allows remote submission options that only require a MongoDB database on the submitting computer but not the compute nodes. It can also deal with multi-factor authentication."
   ]
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Basic introduction to `jobflow` concepts\n",
    "Before diving into the simulation code and more details, we need to discuss the core concepts of `jobflow` (written in Python). It defines `job` and `Flow` objects to handle the correct sequential execution of a workflow. A `job` is a class that allows for the delayed execution of a function. Functions can be easily transformed into a `job` with the `@job` decorator, as demonstrated here with a test function:"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:43.383373Z",
     "start_time": "2024-07-03T11:59:42.489756Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from __future__ import annotations\n",
    "from jobflow import job\n",
    "\n",
    "\n",
    "@job\n",
    "def my_function(my_parameter: int) -> int:\n",
    "    return my_parameter\n",
    "\n",
    "\n",
    "job1 = my_function(my_parameter=1)"
   ],
   "outputs": [],
   "execution_count": 1
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "When we connect several `job`s to generate a `Flow` object, we can construct a whole workflow. The list of connected `jobs` has to be passed to initialize a `Flow`. The order of the `jobs` is automatically determined by the job connectivity via the `job.output` upon runtime. We can also connect several `job`s and `Flows` to create a new `Flow`.\n"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:43.391580Z",
     "start_time": "2024-07-03T11:59:43.386059Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from jobflow import job, Flow\n",
    "\n",
    "\n",
    "@job\n",
    "def my_function(my_parameter: int) -> int:\n",
    "    return my_parameter\n",
    "\n",
    "\n",
    "@job\n",
    "def my_second_function(my_parameter: int) -> int:\n",
    "    return my_parameter\n",
    "\n",
    "\n",
    "job1 = my_function(my_parameter=1)\n",
    "job2 = my_second_function(job1.output)\n",
    "flow = Flow([job1, job2], job2.output)"
   ],
   "outputs": [],
   "execution_count": 2
  },
  {
   "cell_type": "markdown",
   "source": [
    "The following simple [Mermaid](https://mermaid.live) graph will illustrate the workflow `flow` from the example above:"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "import base64\n",
    "from IPython.display import Image, display\n",
    "from jobflow.utils.graph import to_mermaid\n",
    "\n",
    "\n",
    "def mm(graph):\n",
    "    graphbytes = graph.encode(\"utf8\")\n",
    "    base64_bytes = base64.b64encode(graphbytes)\n",
    "    base64_string = base64_bytes.decode(\"ascii\")\n",
    "    display(Image(url=\"https://mermaid.ink/img/\" + base64_string))\n",
    "\n",
    "\n",
    "graph_source = to_mermaid(flow, show_flow_boxes=True)\n",
    "\n",
    "mm(graph_source)"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:43.810036Z",
     "start_time": "2024-07-03T11:59:43.392933Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<img src=\"https://mermaid.ink/img/Zmxvd2NoYXJ0IFRECiAgICBhMzU0MTg2OC1kNGQ3LTQ4MDktOTFhMS02NWE5NmM1YmFjMzMobXlfZnVuY3Rpb24pIC0tPnxvdXRwdXR8IDZiYTNiYjhlLTVjNWEtNDA5Ni04NGE5LWZjMGNhNjE0ZmFkMihteV9zZWNvbmRfZnVuY3Rpb24pCiAgICBhMzU0MTg2OC1kNGQ3LTQ4MDktOTFhMS02NWE5NmM1YmFjMzMobXlfZnVuY3Rpb24pCiAgICA2YmEzYmI4ZS01YzVhLTQwOTYtODRhOS1mYzBjYTYxNGZhZDIobXlfc2Vjb25kX2Z1bmN0aW9uKQ==\"/>"
      ],
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "execution_count": 3
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "With a so-called `Maker` object, the implementation of `job` and `Flow` objects can be further simplified. It is an extended dataclass object that generates a `job` or `Flow` with the `make` method. Dataclasses are used as they allow defining immutable default values and simplify initialisation of attributes. These `Makers` can then be used to reuse code via the usual inheritance in Python.\n"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:43.817918Z",
     "start_time": "2024-07-03T11:59:43.811514Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from dataclasses import dataclass\n",
    "from jobflow import Maker\n",
    "\n",
    "\n",
    "@dataclass\n",
    "class MyMaker(Maker):\n",
    "    name: str = \"My Maker\"\n",
    "    scaling: float = 1.1\n",
    "\n",
    "    @job\n",
    "    def make(self, my_parameter: int) -> float:\n",
    "        return my_parameter * self.scaling\n",
    "\n",
    "\n",
    "@dataclass\n",
    "class MyInheritedMaker(MyMaker):\n",
    "    name: str = \"My inherited Maker\"\n",
    "\n",
    "\n",
    "job1 = MyMaker().make(my_parameter=1)\n",
    "job2 = MyInheritedMaker().make(my_parameter=job1.output)"
   ],
   "outputs": [],
   "execution_count": 4
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "When faced with dynamic workflows (where the number of jobs is unclear before execution) a `Response` object instead of a `job` or `Flow` object can be returned. There are several options to insert the new list of jobs into the `Response` object."
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Implementation of Quantum Espresso Workflow\n",
    "We will use this knowledge to implement the Quantum Espresso-related tasks for calculating an \"Energy vs. Volume\" curve. It’s important to note that this is only a basic implementation, and further extensions towards data validation or for a simplified user experience can be added. For example, one can typically configure run commands for quantum-chemical programs via configuration files in atomate2."
   ]
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "> ℹ️ Note: all outputs of a job need to be transformable into a JSON-like format. Therefore, we use a pymatgen `MSONAtoms` object here instead of an ase `Atoms` object. `MSONAtoms` inherits from the Python package monty’s MSONable class allowing an easy serialization into a `dict`. "
  },
  {
   "cell_type": "markdown",
   "source": "For building the Quantum Espresso (QE)-related tasks, we start by importing essential tools to be able to create and navigate directories (`os`) and execute programs like the QE binary (`subprocess`). `pydantic` is very convenient for validating all kinds of data types. These Pydantic models can then also be directly used for API development as part of [FAST-API](https://fastapi.tiangolo.com/).",
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "import subprocess\n",
    "import os\n",
    "from pydantic import BaseModel, Field"
   ],
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:43.822983Z",
     "start_time": "2024-07-03T11:59:43.820356Z"
    }
   },
   "outputs": [],
   "execution_count": 5
  },
  {
   "cell_type": "markdown",
   "source": [
    "Then, we import tools for data plotting as well as mathematical operations and manipulation."
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-06-30T18:49:41.083780748Z",
     "start_time": "2024-06-30T18:49:40.328009350Z"
    }
   }
  },
  {
   "cell_type": "code",
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np"
   ],
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:44.103958Z",
     "start_time": "2024-07-03T11:59:43.824324Z"
    }
   },
   "outputs": [],
   "execution_count": 6
  },
  {
   "cell_type": "markdown",
   "source": [
    "ASE provides us with a method to create bulk crystal systems and a writer to handle output. "
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "from ase.build import bulk\n",
    "from ase.io import write"
   ],
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:44.490896Z",
     "start_time": "2024-07-03T11:59:44.105647Z"
    }
   },
   "outputs": [],
   "execution_count": 7
  },
  {
   "cell_type": "markdown",
   "source": "Additionally, we take the QE XML output parser written for this tutorial.",
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "from adis_tools.parsers import parse_pw"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:44.614351Z",
     "start_time": "2024-07-03T11:59:44.492579Z"
    }
   },
   "outputs": [],
   "execution_count": 8
  },
  {
   "cell_type": "markdown",
   "source": "To calculate a (E, V) curve with QE, we implement a function that applies a certain strain to the original structure.",
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "from pymatgen.io.ase import MSONAtoms\n",
    "from ase import Atoms\n",
    "\n",
    "\n",
    "def generate_structures(\n",
    "    structure: Atoms, strain_lst: list[float]\n",
    "):  # structure should be of ase Atoms type\n",
    "    structure = MSONAtoms(structure)\n",
    "    structure_lst = []\n",
    "    for strain in strain_lst:\n",
    "        structure_strain = structure.copy()\n",
    "        structure_strain.set_cell(\n",
    "            structure_strain.cell * strain ** (1 / 3), scale_atoms=True\n",
    "        )\n",
    "        structure_lst.append(structure_strain)\n",
    "    return structure_lst"
   ],
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:45.187502Z",
     "start_time": "2024-07-03T11:59:44.615864Z"
    }
   },
   "outputs": [],
   "execution_count": 9
  },
  {
   "cell_type": "markdown",
   "source": [
    "Then we define a function to plot and save the (E, V) curve as a PNG file."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "def plot_energy_volume_curve(volume_lst: list[float], energy_lst: list[float]):\n",
    "    plt.plot(volume_lst, energy_lst)\n",
    "    plt.xlabel(\"Volume\")\n",
    "    plt.ylabel(\"Energy\")\n",
    "    plt.savefig(\"evcurve.png\")"
   ],
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:45.196059Z",
     "start_time": "2024-07-03T11:59:45.190692Z"
    }
   },
   "outputs": [],
   "execution_count": 10
  },
  {
   "cell_type": "markdown",
   "source": [
    "Next, we need a function to write the QE input files. The `input_dict` has to contain all essential input information like the structure, the pseudopotentials, the number of kpoints, the calculation type and the smearing type."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "def write_input(input_dict: dict, working_directory: str = \".\"):\n",
    "    filename = os.path.join(working_directory, \"input.pwi\")\n",
    "    os.makedirs(working_directory, exist_ok=True)\n",
    "    write(\n",
    "        filename=filename,\n",
    "        images=input_dict[\"structure\"],\n",
    "        Crystal=True,\n",
    "        kpts=input_dict[\"kpts\"],\n",
    "        input_data={\n",
    "            \"calculation\": input_dict[\"calculation\"],\n",
    "            \"occupations\": \"smearing\",\n",
    "            \"degauss\": input_dict[\"smearing\"],\n",
    "        },\n",
    "        pseudopotentials=input_dict[\"pseudopotentials\"],\n",
    "        tstress=True,\n",
    "        tprnfor=True,\n",
    "    )"
   ],
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:45.203075Z",
     "start_time": "2024-07-03T11:59:45.198354Z"
    }
   },
   "outputs": [],
   "execution_count": 11
  },
  {
   "cell_type": "markdown",
   "source": [
    "Then, we also need to define a function to collect the output from the QE calculation to pass it to `plot_energy_volume_curve` in order to plot the actual figure. Here we make use of the ADIS QE XML output parser `parse_pw`."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "def collect_output(working_directory=\".\"):\n",
    "    output = parse_pw(os.path.join(working_directory, \"pwscf.xml\"))\n",
    "    return {\n",
    "        \"structure\": MSONAtoms(output[\"ase_structure\"]),\n",
    "        \"energy\": output[\"energy\"],\n",
    "        \"volume\": output[\"ase_structure\"].get_volume(),\n",
    "    }"
   ],
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:45.208945Z",
     "start_time": "2024-07-03T11:59:45.205071Z"
    }
   },
   "outputs": [],
   "execution_count": 12
  },
  {
   "cell_type": "markdown",
   "source": [
    "Now, we need to systematically handle the QE input. We make use of the pymatgen `InputSet` and `InputGenerator` classes to control and define the input data format. The `QEInputSet` defines the input information format which will be followed by the `QEInputGenerator`. We also define an extra `QEInputStaticGenerator` class (inheriting from `QEInputGenerator`) to be able to separately handle the static QE calculations for every strained structure in a convenient way.  Finally, we define the function `write_qe_input_set` to write the QE input files into the current working directory."
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-06-30T19:44:34.646615479Z",
     "start_time": "2024-06-30T19:44:34.599326311Z"
    }
   }
  },
  {
   "cell_type": "code",
   "source": [
    "from pymatgen.io.core import InputSet, InputGenerator\n",
    "from dataclasses import dataclass, field\n",
    "\n",
    "\n",
    "class QEInputSet(InputSet):\n",
    "    \"\"\"\n",
    "    Writes an QE input based on an input_dict\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, input_dict):\n",
    "        self.input_dict = input_dict\n",
    "\n",
    "    def write_input(self, working_directory=\".\"):\n",
    "        write_input(self.input_dict, working_directory=working_directory)\n",
    "\n",
    "\n",
    "@dataclass\n",
    "class QEInputGenerator(InputGenerator):\n",
    "    \"\"\"\n",
    "    Generates an QE input based on the format given in QEInputSet.\n",
    "    \"\"\"\n",
    "\n",
    "    pseudopotentials: dict = field(\n",
    "        default_factory=lambda: {\"Al\": \"Al.pbe-n-kjpaw_psl.1.0.0.UPF\"}\n",
    "    )\n",
    "    kpts: tuple = (3, 3, 3)\n",
    "    calculation: str = \"vc-relax\"\n",
    "    smearing: float = 0.02\n",
    "\n",
    "    def get_input_set(self, structure) -> QEInputSet:\n",
    "\n",
    "        input_dict = {\n",
    "            \"structure\": structure,\n",
    "            \"pseudopotentials\": self.pseudopotentials,\n",
    "            \"kpts\": self.kpts,\n",
    "            \"calculation\": self.calculation,\n",
    "            \"smearing\": self.smearing,\n",
    "        }\n",
    "        return QEInputSet(input_dict=input_dict)\n",
    "\n",
    "\n",
    "@dataclass\n",
    "class QEInputStaticGenerator(QEInputGenerator):\n",
    "    calculation: str = \"scf\"\n",
    "\n",
    "\n",
    "def write_qe_input_set(\n",
    "    structure: Atoms,\n",
    "    input_set_generator: InputGenerator = QEInputGenerator(),\n",
    "    working_directory: str = \".\",\n",
    ") -> None:\n",
    "    qis = input_set_generator.get_input_set(structure=structure)\n",
    "    qis.write_input(working_directory=working_directory)"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:45.220507Z",
     "start_time": "2024-07-03T11:59:45.210945Z"
    }
   },
   "outputs": [],
   "execution_count": 13
  },
  {
   "cell_type": "markdown",
   "source": [
    "The next steps are all about handling the execution of QE and the output data collection. We start by defining a QE task document `QETaskDoc` to systematically collect the output data. For the (E, V) curve, the energy and volume are of course the most important information. The task document could be further extended to contain other relevant information. Next, we define a `BaseQEMaker` to handle generic QE jobs (in our case for the structural relaxation) and a separate `StaticQEMaker` for the static QE calculations. The `BaseQEMaker` is expecting the generic input set generated by `QEInputGenerator`, while `StaticQEMaker` expects the `QEInputStaticGenerator` type. As the `StaticQEMaker` inherits from the `BaseQEMaker`, we only need to make sure to pass the correct input set generator type."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "from dataclasses import dataclass, field\n",
    "from jobflow import job, Maker\n",
    "from typing import Any, Optional, Union\n",
    "\n",
    "\n",
    "QE_CMD = \"mpirun -np 1 pw.x -in input.pwi > output.pwo\"\n",
    "\n",
    "\n",
    "def run_qe(qe_cmd: str = QE_CMD):\n",
    "    subprocess.check_output(qe_cmd, shell=True, universal_newlines=True)\n",
    "\n",
    "\n",
    "class QETaskDoc(BaseModel):\n",
    "    structure: Optional[MSONAtoms] = Field(None, description=\"ASE structure\")\n",
    "    energy: Optional[float] = Field(None, description=\"DFT energy in eV\")\n",
    "    volume: Optional[float] = Field(None, description=\"volume in Angstrom^3\")\n",
    "\n",
    "    @classmethod\n",
    "    def from_directory(cls, working_directory):\n",
    "        output = collect_output(working_directory=working_directory)\n",
    "        # structure object needs to be serializable, i.e., we need an additional transformation\n",
    "        return cls(\n",
    "            structure=output[\"structure\"],\n",
    "            energy=output[\"energy\"],\n",
    "            volume=output[\"volume\"],\n",
    "        )\n",
    "\n",
    "\n",
    "@dataclass\n",
    "class BaseQEMaker(Maker):\n",
    "    \"\"\"\n",
    "    Base QE job maker.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    name : str\n",
    "        The job name.\n",
    "    input_set_generator : .QEInputGenerator\n",
    "        A generator used to make the input set.\n",
    "    \"\"\"\n",
    "\n",
    "    name: str = \"base qe job\"\n",
    "    input_set_generator: QEInputGenerator = field(default_factory=QEInputGenerator)\n",
    "\n",
    "    @job(output_schema=QETaskDoc)\n",
    "    def make(self, structure: Atoms | MSONAtoms) -> QETaskDoc:\n",
    "        \"\"\"\n",
    "        Run a QE calculation.\n",
    "\n",
    "        Parameters\n",
    "        ----------\n",
    "        structure : MSONAtoms|Atoms\n",
    "            An Atoms or MSONAtoms object.\n",
    "\n",
    "        Returns\n",
    "        -------\n",
    "            Output of a QE calculation\n",
    "        \"\"\"\n",
    "        # copy previous inputs\n",
    "\n",
    "        # write qe input files\n",
    "        write_qe_input_set(\n",
    "            structure=structure, input_set_generator=self.input_set_generator\n",
    "        )\n",
    "\n",
    "        # run the QE software\n",
    "        run_qe()\n",
    "\n",
    "        # parse QE outputs in form of a task document\n",
    "        task_doc = QETaskDoc.from_directory(\".\")\n",
    "\n",
    "        return task_doc\n",
    "\n",
    "\n",
    "@dataclass\n",
    "class StaticQEMaker(BaseQEMaker):\n",
    "    \"\"\"\n",
    "    Base QE job maker.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    name : str\n",
    "        The job name.\n",
    "    input_set_generator : .QEInputGenerator\n",
    "        A generator used to make the input set.\n",
    "    \"\"\"\n",
    "\n",
    "    name: str = \"static qe job\"\n",
    "    input_set_generator: QEInputGenerator = field(\n",
    "        default_factory=QEInputStaticGenerator\n",
    "    )"
   ],
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-03T11:59:45.236298Z",
     "start_time": "2024-07-03T11:59:45.224011Z"
    }
   },
   "outputs": [],
   "execution_count": 14
  },
  {
   "cell_type": "markdown",
   "source": [
    "Finally, it's time to orchestrate all functions and classes together into an actual flow. Note how the number of jobs in `get_ev_curve` can be flexibly controlled by using `strain_lst` and therefore we use a `Response` object to handle the flexible job output. By making `get_ev_curve` and `plot_energy_volume_curve_job` into `job` objects using the `@job` decorator, we ensure that first all the (E, V) data points are calculated before they are plotted. The `qe_flow` contains the list of the jobs that need to be executed in this workflow. The jobs are connected by the respective `job.output` objects that also ensures the correct order in executing the jobs."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "from jobflow import job, Response, Flow, run_locally\n",
    "\n",
    "# set up QE PP env\n",
    "os.environ[\"ESPRESSO_PSEUDO\"] = f\"{os.getcwd()}/espresso/pseudo\"\n",
    "\n",
    "\n",
    "@job\n",
    "def get_ev_curve(structure: Atoms | MSONAtoms, strain_lst: list(float)):\n",
    "    structures = generate_structures(structure, strain_lst=strain_lst)\n",
    "    jobs = []\n",
    "    volumes = []\n",
    "    energies = []\n",
    "    for istructure in range(len(strain_lst)):\n",
    "        new_job = StaticQEMaker().make(structures[istructure])\n",
    "        jobs.append(new_job)\n",
    "        volumes.append(new_job.output.volume)\n",
    "        energies.append(new_job.output.energy)\n",
    "    return Response(\n",
    "        replace=Flow(jobs, output={\"energies\": energies, \"volumes\": volumes})\n",
    "    )\n",
    "\n",
    "\n",
    "@job\n",
    "def plot_energy_volume_curve_job(volume_lst: list(float), energy_lst: list(float)):\n",
    "    plot_energy_volume_curve(volume_lst=volume_lst, energy_lst=energy_lst)\n",
    "\n",
    "\n",
    "structure = bulk(\"Al\", a=4.15, cubic=True)\n",
    "relax = BaseQEMaker().make(structure=MSONAtoms(structure))\n",
    "ev_curve_data = get_ev_curve(\n",
    "    relax.output.structure, strain_lst=np.linspace(0.9, 1.1, 5)\n",
    ")\n",
    "# structure optimization job and (E, V) curve data job connected via relax.output\n",
    "plot_curve = plot_energy_volume_curve_job(\n",
    "    volume_lst=ev_curve_data.output[\"volumes\"],\n",
    "    energy_lst=ev_curve_data.output[\"energies\"],\n",
    ")\n",
    "# (E, V) curve data job and plotting the curve job connected via ev_curve_data.output\n",
    "qe_flow = [relax, ev_curve_data, plot_curve]\n",
    "qe_fw = Flow(qe_flow)\n",
    "# qe_flow is the QE flow that consists of the job for structural optimization, calculating the (E, V) curve data points and plotting the curve\n",
    "run_locally(\n",
    "    qe_fw, create_folders=True\n",
    ")  # order of the jobs in the flow determined by connectivity\n",
    "\n",
    "graph = to_mermaid(qe_fw, show_flow_boxes=True)\n",
    "mm(graph)"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-03T12:01:06.585706Z",
     "start_time": "2024-07-03T11:59:45.237648Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2024-07-03 13:59:45,257 INFO Started executing jobs locally\n",
      "2024-07-03 13:59:45,266 INFO Starting job - base qe job (fb7e4f95-15fe-4ae0-aa3b-3d0f5dc8b65a)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Note: The following floating-point exceptions are signalling: IEEE_INVALID_FLAG\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2024-07-03 14:00:31,075 INFO Finished job - base qe job (fb7e4f95-15fe-4ae0-aa3b-3d0f5dc8b65a)\n",
      "2024-07-03 14:00:31,078 INFO Starting job - get_ev_curve (8df443c4-f690-4c1b-9126-8455b6458d9d)\n",
      "2024-07-03 14:00:31,099 INFO Finished job - get_ev_curve (8df443c4-f690-4c1b-9126-8455b6458d9d)\n",
      "2024-07-03 14:00:31,105 INFO Starting job - static qe job (8c2ce097-6b17-43dd-9f03-d4477338688b)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Note: The following floating-point exceptions are signalling: IEEE_INVALID_FLAG\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2024-07-03 14:00:37,026 INFO Finished job - static qe job (8c2ce097-6b17-43dd-9f03-d4477338688b)\n",
      "2024-07-03 14:00:37,029 INFO Starting job - static qe job (046ab976-1dc9-4b45-816d-86297a209912)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Note: The following floating-point exceptions are signalling: IEEE_INVALID_FLAG\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2024-07-03 14:00:43,878 INFO Finished job - static qe job (046ab976-1dc9-4b45-816d-86297a209912)\n",
      "2024-07-03 14:00:43,883 INFO Starting job - static qe job (2e1199a8-12c0-4df0-afdc-2543f0a1652b)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Note: The following floating-point exceptions are signalling: IEEE_INVALID_FLAG\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2024-07-03 14:00:50,753 INFO Finished job - static qe job (2e1199a8-12c0-4df0-afdc-2543f0a1652b)\n",
      "2024-07-03 14:00:50,759 INFO Starting job - static qe job (b6118649-654f-445c-ba44-091c6bf6a5af)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Note: The following floating-point exceptions are signalling: IEEE_INVALID_FLAG\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2024-07-03 14:00:58,591 INFO Finished job - static qe job (b6118649-654f-445c-ba44-091c6bf6a5af)\n",
      "2024-07-03 14:00:58,598 INFO Starting job - static qe job (ed35e52e-fd72-495a-ae7f-4f2f949d8031)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Note: The following floating-point exceptions are signalling: IEEE_INVALID_FLAG\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2024-07-03 14:01:06,332 INFO Finished job - static qe job (ed35e52e-fd72-495a-ae7f-4f2f949d8031)\n",
      "2024-07-03 14:01:06,337 INFO Starting job - store_inputs (8df443c4-f690-4c1b-9126-8455b6458d9d, 2)\n",
      "2024-07-03 14:01:06,340 INFO Finished job - store_inputs (8df443c4-f690-4c1b-9126-8455b6458d9d, 2)\n",
      "2024-07-03 14:01:06,343 INFO Starting job - plot_energy_volume_curve_job (4bb64989-7cc3-4dc4-900f-19c10d959dfa)\n",
      "2024-07-03 14:01:06,497 INFO Finished job - plot_energy_volume_curve_job (4bb64989-7cc3-4dc4-900f-19c10d959dfa)\n",
      "2024-07-03 14:01:06,498 INFO Finished executing jobs locally\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<img src=\"https://mermaid.ink/img/Zmxvd2NoYXJ0IFRECiAgICBmYjdlNGY5NS0xNWZlLTRhZTAtYWEzYi0zZDBmNWRjOGI2NWEoYmFzZSBxZSBqb2IpCiAgICA4ZGY0NDNjNC1mNjkwLTRjMWItOTEyNi04NDU1YjY0NThkOWQoZ2V0X2V2X2N1cnZlKQogICAgNGJiNjQ5ODktN2NjMy00ZGM0LTkwMGYtMTljMTBkOTU5ZGZhKHBsb3RfZW5lcmd5X3ZvbHVtZV9jdXJ2ZV9qb2Ip\"/>"
      ],
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ],
      "image/png": "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"
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "execution_count": 15
  },
  {
   "cell_type": "markdown",
   "source": [
    "And with using the `job.output` connectivity, the mermaid graph looks like:"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "mm(\n",
    "    \"\"\"\n",
    "flowchart TD\n",
    "    6883bfe0-2b20-49de-92df-c166d6f91dbc(base qe job) --> |output.structure| dfc9a5cd-fb91-4582-b6c6-c42b4c65cb83(get_ev_curve)\n",
    "    dfc9a5cd-fb91-4582-b6c6-c42b4c65cb83(get_ev_curve) --> |'volumes', 'energies'| 92d14a25-bb90-4c86-b970-af05db90550e(plot_energy_volume_curve_job)\n",
    "\"\"\"\n",
    ")"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-03T12:01:06.592117Z",
     "start_time": "2024-07-03T12:01:06.587277Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<img src=\"https://mermaid.ink/img/CmZsb3djaGFydCBURAogICAgNjg4M2JmZTAtMmIyMC00OWRlLTkyZGYtYzE2NmQ2ZjkxZGJjKGJhc2UgcWUgam9iKSAtLT4gfG91dHB1dC5zdHJ1Y3R1cmV8IGRmYzlhNWNkLWZiOTEtNDU4Mi1iNmM2LWM0MmI0YzY1Y2I4MyhnZXRfZXZfY3VydmUpCiAgICBkZmM5YTVjZC1mYjkxLTQ1ODItYjZjNi1jNDJiNGM2NWNiODMoZ2V0X2V2X2N1cnZlKSAtLT4gfCd2b2x1bWVzJywgJ2VuZXJnaWVzJ3wgOTJkMTRhMjUtYmI5MC00Yzg2LWI5NzAtYWYwNWRiOTA1NTBlKHBsb3RfZW5lcmd5X3ZvbHVtZV9jdXJ2ZV9qb2IpCg==\"/>"
      ],
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "execution_count": 16
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-06-30T21:20:50.166986280Z",
     "start_time": "2024-06-30T21:20:50.152786964Z"
    }
   },
   "cell_type": "markdown",
   "source": [
    "## Submission to an HPC / Check pointing / Error handling\n",
    "* Use the `jobflow` command `run_locally` to run jobs in serial with a simple job script\n",
    "* Use `fireworks` and `jobflow-remote` to simplify and parallelize the submission of jobs, and allows for checkpointing\n",
    "* Use [`custodian`](http://materialsproject.github.io/custodian/) error handling (not directly handled by `jobflow`), e.g. like in `atomate2`"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Data Storage / Data Sharing\n",
    "Key data can be saved in a dedicated MongoDB-like database. This data can be validated with the help of\n",
    "`pydantic`. The latter also allows a direct connection to Fast-API. The Materials Project data generation\n",
    "relies on similar features. Direct calculation outputs will be saved on the compute machine. \n",
    "There are no dedicated mechanisms to save whole projects, but the database can be used to achieve this."
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-06-30T21:19:50.638818400Z",
     "start_time": "2024-06-30T21:19:50.628780294Z"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Publication of the workflow\n",
    "The `jobflow` infrastructure does not provide a dedicated platform for publishing a workflow currently. However, workflows related to computational materials science have been collected in the package `atomate2`. In addition, users can build their own package by relying on `jobflow` and share it as a new Python-based program. There are also additional materials science packages like [NanoParticleTools](https://github.com/BlauGroup/NanoParticleTools) or [QuAcc](https://github.com/Quantum-Accelerators/quacc) that rely on `jobflow`."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [],
   "metadata": {
    "collapsed": false
   }
  }
 ]
}