6.Workchains and high-throughput study.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*please execute the cell below before starting the tutorial by selecting the cell and pressing Ctrl+Enter*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aiida.orm import Dict, load_node\n",
    "from aiida.engine import submit\n",
    "\n",
    "from aiida import load_profile\n",
    "\n",
    "load_profile()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Workchains and high-throughput study"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the final, sixth part of the AiiDA-FLEUR tutorial, we will cover the main part of AiiDA - workchains. Workchains are key-turn solutions for particular tasks such as finding equation of states or performing structure optimisation. The main goal of a workchain is to automatically perform a certain task keeping the history of all performed actions. The main advantage of using workchains is providing a low entering threshold for newcomers and routine tasks automatization for more advanced users.\n",
    "\n",
    "In this part of the tutorial you will explore and learn how to work with AiiDA-Fleur workchains.\n",
    "\n",
    "Workchains are similar to `CalcJob`: basically they can be treated as a black box using user's input and producing the output. For example, the SCF workchain is an engine that produces self-consistent charge density (and other interesting parameters) for a given structure. Equation Of States (EOS) workchain calculates equation of states for a given structure and etc.\n",
    "\n",
    "<img src=\"files/images/black_box.png\" width=\"1000\">\n",
    "\n",
    "The power of workchains is hidden behind their possible use in other workchains. Workchain A can be used in a workchain B, workchain C can use workchains A and B etc. Using smaller workchains as building blocks for a more complex algorithms, one can develop hierarchic structure of the task that AiiDA can perform."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Workchain hierarchy "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The hierarchy of all implemented workchains in AiiDA-Fleur v1.0.0 is shown below. Black arrows mean the use of a workchain by another one. For instance, the geometry optimization workchain uses the SCF workchain inside it.\n",
    "It is clearly seen that every higher-level workchain uses the SCF workchain.\n",
    "\n",
    "<img src=\"files/images/workchains.png\" width=\"600\">\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "In next section we will cover the central workchain of the AiiDA-FLEUR plugin: the SCF workchain."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## SCF WorkChain "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The SCF workchain is responsible for converging charge density for a given structure. It submits a Fleur calculation several times until the convergence criterion or maximal number of Fleur submissions are reached."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Inputs of the SCF WorkChain"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "|name|type|description| required |\n",
    "|:---:|:---:|:---------:|:---:|\n",
    "|fleur | Code | Fleur code | yes |\n",
    "|inpgen | Code | Inpgen code| no |\n",
    "|wf_parameters | Dict | Settings of the workchain| no |\n",
    "|structure | StructureData | Structure data node| no |\n",
    "|calc_parameters | Dict | FLAPW parameters, used by inpgen| no |\n",
    "|fleurinp | FleurinpData | FLEUR input files| no |\n",
    "|remote_data | RemoteData | Remote folder of another calculation| no |\n",
    "|options | Dict | AiiDA options (computational resources)| no |\n",
    "|settings | Dict | special settings for Fleur calculation| no |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly to the `FleurCalculation`, SCF workchain has only one required input. Again, one *must* provide one of the supported input configurations to ensure the predictable behaviour of the workchain:\n",
    "\n",
    "* **fleur** + **fleurinp**\n",
    "* **fleur** + **fleurinp** + **remote_data**\n",
    "* **fleur** + **remote_data**\n",
    "* **fleur** + **inpgen** + **structure**\n",
    "\n",
    "In this tutorial we will cover **fleur** + **inpgen** + **structure** configuration only, which makes the workchain to submit a single inpgen calculation followed by several Fleur code submissions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## SCF workchain submission"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Inputs preparation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As always, import the `FleurScfWorkChain` first:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aiida_fleur.workflows.scf import FleurScfWorkChain"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, let us setup input parameters for the workchain that control its behaviour. A cell below sets the maximal number of Fleur submission to 3, density convergence criterion to 0.001, maximal number of iterations in a single `FleurCalculation` to 30."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wf_para = Dict(dict={'fleur_runmax' : 3,           # maximal number of Fleur submissions\n",
    "                     'density_converge' : 0.001,   # density convergence criterion\n",
    "                     'mode' : 'density',           # density is converged\n",
    "                     'itmax_per_run' : 30,         # number of scf iterations in each Fleur submission\n",
    "                     'serial' : False})            # use mpi submission"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are going to use StructureData node created in the tutorial number 1. Let us use the stored structure:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# you need to modify this - remind the PK of the silicon structure SI_PK\n",
    "structure = load_node(SI_PK)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Despite **options** and **wf_parameters** are never required, we will set them up because we do not want to use default values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "options = Dict(dict={'resources' : {\"num_machines\": 1, \"num_mpiprocs_per_machine\" : 2},\n",
    "                     'withmpi' : True,\n",
    "                     'max_wallclock_seconds' : 600})\n",
    "\n",
    "calc_parameters = Dict(dict={\n",
    "    'kpt': {\n",
    "        'div1': 2,\n",
    "        'div2' : 2,\n",
    "        'div3' : 2\n",
    "        }})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: inpgen calculation submitted by SCF workchain is always submitted with an option:\n",
    " \n",
    "    {'resources' : {\"num_machines\": 1, \"num_mpiprocs_per_machine\" : 1}, 'withmpi' : False}\n",
    "    \n",
    "which means the resources specified in SCF input apply to `FleurCalculation` only."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we need to load Fleur and inpgen nodes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fleur_code = load_node(146)\n",
    "inpgen_code = load_node(7)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Job submission"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In contrast to `FluerinpgenCalculation` and `FleurCalculation`, there is no need to assemble inputs in a single dictionary (but one can do it for convenience)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "SCF_workchain = submit(FleurScfWorkChain,\n",
    "                          fleur=fleur_code,\n",
    "                          inpgen=inpgen_code,\n",
    "                          calc_parameters=calc_parameters,\n",
    "                          structure=structure,\n",
    "                          wf_parameters=wf_para,\n",
    "                          options=options)\n",
    "print('Submitted SCF workchain pk={}'.format(SCF_workchain.pk))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can check the status of the workchain simply executing a cell below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# you need to modify this\n",
    "!verdi process status PK"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can execute the cell above again and again until it does not say the task is finished. The output for the finished workchain should look like:\n",
    "\n",
    "<img src=\"files/images/scf_print.png\" width=\"400\">\n",
    "\n",
    "\n",
    "You can also check all processes submitted last 24 hours by:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!verdi process list -a -p 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Results analysis"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "SCF workchain returns three outputs:\n",
    "\n",
    "|name| type | comment|\n",
    "|:--:|:----:|:----------:|\n",
    "|output_scf_wc_para|Dict| results of the workchain|\n",
    "|fleurinp| FleurinpData| FleurinpData that was used (after all modifications) |\n",
    "|last_fleur_calc_output| Dict | shortcut for last `FluerCalculation` output dict |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can find all output node PKs running:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# you need to modify this - replace SCF_PK\n",
    "!verdi process show SCF_PK"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some data, given in `output_scf_wc_para` can be visualised via:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# you need to modify this - replace SCF_PK\n",
    "%matplotlib inline\n",
    "from aiida_fleur.tools.plot.fleur import plot_fleur\n",
    "plot_fleur(SCF_PK)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, you can access output_scf_wc_para dictionary via:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# you need to modify this - replace SCF_PK\n",
    "scf_wc = load_node(SCF_PK)\n",
    "scf_wc.outputs.output_scf_wc_para.get_dict()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# you need to modify this - replace OUTPUT_DICT_PK\n",
    "!verdi data dict show OUTPUT_DICT_PK"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Higher-level workchains"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And now - finally - we will see the real power of the workchains. We are going to use two higher-level workchains for Magnetic Anisotropy Energy (MAE) and Spin Spiral Dispersion (SSDisp) calculations. There are two types of MAE and SSDisp workchains: force-theorem and convergence workchains. In this tutorial we will use force-theorem workchains only that first submits a single SCF workchain to obtain the reference charge density and later submits a single `FleurCalculation` task to run the force theorem step."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Magnetic anisotropy workchain "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import the workchain first:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aiida_fleur.workflows.mae import FleurMaeWorkChain"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A table of possible inputs looks the same as for SCF:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "|name|type|description| required |\n",
    "|:---:|:---:|:---------:|:---:|\n",
    "|fleur | Code | Fleur code | yes |\n",
    "|inpgen | Code | Inpgen code| no |\n",
    "|wf_parameters | Dict | Settings of the workchain| no |\n",
    "|structure | StructureData | Structure data node| no |\n",
    "|calc_parameters | Dict | FLAPW parameters, used by inpgen| no |\n",
    "|fleurinp | FleurinpData | FLEUR input files| no |\n",
    "|remote_data | RemoteData | Remote folder to find cdn1| no |\n",
    "|options | Dict | AiiDA options (computational resources)| no |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, there are a lot of optional inputs - however you *must* follow one of the supported input configurations. They are similar to the SCF workchain and I will not cover all of them here, let us just use the **fleur** + **inpgen** + **structure** mode. Let us also specify workchain parameters and computational resources."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "options = Dict(dict={'resources' : {\"num_machines\": 1, \"num_mpiprocs_per_machine\" : 2},\n",
    "                     'withmpi' : True,\n",
    "                     'max_wallclock_seconds' : 600})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wf_para = Dict(dict={'sqa_ref': [0.7, 0.7],                    # theta and phi for reference calculation\n",
    "                     'use_soc_ref': False,                     # True if switch on SOC terms for reference\n",
    "                     'sqas_theta': [0.0, 1.57079, 1.57079],    # a list of theta values to calculate via the FT\n",
    "                     'sqas_phi': [0.0, 0.0, 1.57079],          # a list of phi values to calculate via the FT\n",
    "                     'fleur_runmax': 10,                       # passed to SCF workchain\n",
    "                     'density_converged': 0.02,                # passed to SCF workchain\n",
    "                     'serial': False,                          # passed to SCF workchain\n",
    "                     'itmax_per_run': 30,                       # passed to SCF workchain\n",
    "                     'inpxml_changes': []                      # a list of inpxml changes to be done before submission\n",
    "                    })"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "calc_parameters = Dict(dict={\n",
    "    'kpt': {\n",
    "        'div1': 4,\n",
    "        'div2' : 4,\n",
    "        'div3' : 1\n",
    "        }})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fleur_code = load_node(???)\n",
    "inpgen_code = load_node(???)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this section we want to be even more productive - let us define not a single structure but three of them! Import Fe, Co and Ni structures that we created in tutorial 4:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fe_structure = load_node(xxx)\n",
    "co_structure = load_node(xxx)\n",
    "ni_structure = load_node(xxx)\n",
    "\n",
    "input_structures = [fe_structure, co_structure, ni_structure]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And calculate magnetic anisotropy energy for all of them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for structure in input_structures:\n",
    "    MAE_workchain = submit(FleurMaeWorkChain,\n",
    "                          fleur=fleur_code,\n",
    "                          inpgen=inpgen_code,\n",
    "                          calc_parameters=calc_parameters,\n",
    "                          structure=structure,\n",
    "                          wf_parameters=wf_para)\n",
    "    print('Submitted Mae workchain pk={} for {} structure'.format(MAE_workchain.pk, structure.get_formula()))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, you can check if it is finished via:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# you need to modify this - replace MAE_PK\n",
    "!verdi process status MAE_PK"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!verdi process list -a -p 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using you experience, can you access the output dictionaries and extract values of MAEs for all the structures?\n",
    "\n",
    "Now let us proceed to the final task - Spin spiral dispersion workchain."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Scripting tasks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Spin-spiral dispersion workchain"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Spin spiral dispersion workchain has the same input nodes as MAE workchain. `wf_para` dictionary contains a different set of control keys:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wf_para = Dict(dict={'fleur_runmax' : 3,                    # passed to SCF workchain\n",
    "                     'itmax_per_run' : 30,                  # passed to SCF workchain\n",
    "                     'density_converged' : 0.002,           # passed to SCF workchain\n",
    "                     'serial' : False,                      # passed to SCF workchain\n",
    "                     'beta' : {'all' : 1.57079},            # sets beta angle for all atoms\n",
    "                     'q_vectors': [[0.0, 0.0, 0.0,          # set q-vectors to calculate\n",
    "                                   [0.125, 0.125, 0.0],     \n",
    "                                   [0.250, 0.250, 0.0],     \n",
    "                                   [0.375, 0.375, 0.0],     \n",
    "                                   [0.500, 0.500, 0.0]],     \n",
    "                     'ref_qss' : [0.0, 0.0, 0.0],            # sets a q-vector of the reference calc\n",
    "                     'inpxml_changes': []\n",
    "                    })"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To import SSDisp workchain, run:\n",
    "\n",
    "    from aiida_fleur.workflows.ssdisp import FleurSSDispWorkChain"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " This time we will cover another input configuration: `fleur + fleurinp`. We will use `FleurinpData` objects generated in section 4.\n",
    " \n",
    "In the final task, load three `FleurinpData` objects and run a `FleurSSDispWorkChain` for each of them. Use **wf_para** given above. Do you need to pass **calc_parameters** this time?\n",
    "\n",
    "Explore the outputs, extract spin spiral dispersion. Plot energy of a spin spiral as a function of a q-vector."
   ]
  }
 ],
 "metadata": {
  "@webio": {
   "lastCommId": null,
   "lastKernelId": null
  },
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}