diff --git a/docs/source/index.rst b/docs/source/index.rst
index 4573dc5..6c34c59 100755
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -13,6 +13,7 @@ The aiida-crystal17 plugin for `AiiDA`_
user_guide/get_started
user_guide/calc_basic
user_guide/calc_main
+ user_guide/workflow_base
user_guide/calc_main_immigrant
user_guide/calc_gulp
api_index
diff --git a/docs/source/user_guide/workflow_base.ipynb b/docs/source/user_guide/workflow_base.ipynb
new file mode 100644
index 0000000..30620fa
--- /dev/null
+++ b/docs/source/user_guide/workflow_base.ipynb
@@ -0,0 +1,725 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Main Calculation Restart Workflow"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The `crystal17.main.base` workflow builds on the `crystal.main` calculation, by automating restarts of the calculation for known failure modes:\n",
+ "\n",
+ "- **No SCF convergence within maximum cycles**: the FMIXING value is lowered, and the calculation is restarted from the last known geometry and wave-function (using GUESSP)\n",
+ "- **No geometric convergence within maximum iterations**: the calculation is restarted from the last known geometry and wave-function (using GUESSP)\n",
+ "- **Reaches scheduler wall-time**: the calculation is restarted from the last known geometry.\n",
+ "\n",
+ "Additionally, new SHRINK terms can be computed, to adhere to a minimum desired k-point spacing, given the input structure."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[32m ✓ \u001b[0mprofile: On profile test_crystal17\u001b[0m\n",
+ "\u001b[32m ✓ \u001b[0mrepository: /Users/cjs14/GitHub/aiida-cjs-working/databases/aiida/.aiida/repository/test_crystal17\u001b[0m\n",
+ "\u001b[32m ✓ \u001b[0mpostgres: Connected as cjs14@localhost:5432\u001b[0m\n",
+ "\u001b[32m ✓ \u001b[0mrabbitmq: Connected to amqp://127.0.0.1?heartbeat=600\u001b[0m\n",
+ "\u001b[32m ✓ \u001b[0mdaemon: Daemon is running as PID 35477 since 2019-07-18 12:57:21\u001b[0m\n"
+ ]
+ }
+ ],
+ "source": [
+ "!verdi status"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[31m\u001b[1mInputs\u001b[0m\n",
+ "\u001b[1m cry: required \u001b[0m\n",
+ " basis_family: optional Str An alternative to specifying the basis sets manually: one can specify the n ...\u001b[0m\n",
+ " clean_workdir: optional Bool If `True`, work directories of all called calculation will be cleaned at th ...\u001b[0m\n",
+ " kpoints_distance: optional Float The minimum desired distance in 1/Å between k-points in reciprocal space. T ...\u001b[0m\n",
+ " kpoints_force_parity: optional Bool Optional input when constructing the k-points based on a desired `kpoints_d ...\u001b[0m\n",
+ " max_iterations: optional Int Maximum number of iterations the work chain will restart the calculation to ...\u001b[0m\n",
+ " metadata: optional \u001b[0m\n",
+ "\u001b[31m\u001b[1mOutputs\u001b[0m\n",
+ "\u001b[1m remote_folder: required RemoteData Input files necessary to run the process will be stored in this folder node ...\u001b[0m\n",
+ "\u001b[1m results: required Dict the data extracted from the main output file\u001b[0m\n",
+ " structure: optional StructureData the structure output from the calculation\u001b[0m\n",
+ " symmetry: optional SymmetryData the symmetry data from the calculation\u001b[0m\n",
+ "\u001b[31m\u001b[1mExit codes\u001b[0m\n",
+ " 1: The process has failed with an unspecified error.\u001b[0m\n",
+ " 2: The process failed with legacy failure mode.\u001b[0m\n",
+ " 10: The process returned an invalid output.\u001b[0m\n",
+ " 11: The process did not register a required output.\u001b[0m\n",
+ " 101: The maximum number of iterations was exceeded.\u001b[0m\n",
+ " 102: The calculation failed for an unknown reason, twice in a row.\u001b[0m\n",
+ " 201: The parameters could not be validated against the jsonschema.\u001b[0m\n",
+ " 202: The explicit `basis_sets` or `basis_family` could not be used to get the necessary basis sets.\u001b[0m\n",
+ " 204: The `metadata.options` did not specify both `resources.num_machines` and `max_wallclock_seconds`.\u001b[0m\n",
+ " 300: The calculation failed with an unrecoverable error.\u001b[0m\n",
+ " 320: The initialization calculation failed.\u001b[0m\n"
+ ]
+ }
+ ],
+ "source": [
+ "!verdi plugin list aiida.workflows crystal17.main.base"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 15,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "from aiida.engine import run_get_node\n",
+ "from aiida.plugins import (\n",
+ " DataFactory, WorkflowFactory, CalculationFactory)\n",
+ "from aiida.tools.visualization import Graph\n",
+ "\n",
+ "from aiida_crystal17.tests import get_test_structure_and_symm, TEST_FILES\n",
+ "from aiida_crystal17.tests.utils import get_default_metadata\n",
+ "from aiida_crystal17.tests.utils import get_or_create_local_computer, get_or_create_code"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "'test_crystal17'"
+ ]
+ },
+ "execution_count": 7,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "from aiida import load_profile\n",
+ "profile = load_profile()\n",
+ "profile.name"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "aiida_crystal17.data.basis_set.BasisSetData"
+ ]
+ },
+ "execution_count": 8,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "DataFactory('crystal17.basisset')"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 18,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "computer = get_or_create_local_computer('work_directory', 'localhost')\n",
+ "code = get_or_create_code('crystal17.main', computer, 'mock_crystal17')\n",
+ "\n",
+ "params = {\n",
+ " \"title\": \"NiO Bulk with AFM spin\",\n",
+ " \"scf.single\": \"UHF\",\n",
+ " \"scf.k_points\": (8, 8),\n",
+ " \"scf.spinlock.SPINLOCK\": (0, 15),\n",
+ " \"scf.numerical.FMIXING\": 50,\n",
+ " \"scf.numerical.MAXCYCLE\": 10,\n",
+ " \"scf.post_scf\": [\"PPAN\"]\n",
+ " }\n",
+ "\n",
+ "instruct, symmetry = get_test_structure_and_symm(\"NiO_afm\")\n",
+ "\n",
+ "kind_data = DataFactory('crystal17.kinds')(data={\n",
+ " \"kind_names\": [\"Ni1\", \"Ni2\", \"O\"],\n",
+ " \"spin_alpha\": [True, False, False], \"spin_beta\": [False, True, False]})\n",
+ "\n",
+ "DataFactory('crystal17.basisset').upload_basisset_family(\n",
+ " os.path.join(TEST_FILES, \"basis_sets\", \"sto3g\"),\n",
+ " \"sto3g\",\n",
+ " \"minimal basis sets\",\n",
+ " stop_if_existing=False,\n",
+ " extension=\".basis\")\n",
+ "\n",
+ "# set up calculation\n",
+ "process_class = code.get_builder().process_class\n",
+ "calc_builder = process_class.create_builder(\n",
+ " params, instruct, \"sto3g\", \n",
+ " symmetry=symmetry, \n",
+ " kinds=kind_data, \n",
+ " code=code,\n",
+ " metadata=get_default_metadata(),\n",
+ " unflatten=True)\n",
+ "\n",
+ "wc_builder = WorkflowFactory('crystal17.main.base').get_builder()\n",
+ "wc_builder.cry = dict(calc_builder)\n",
+ "wc_builder.clean_workdir = True"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 19,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "outputs, wc_node = run_get_node(wc_builder)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 25,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[22mCryMainBaseWorkChain<240> Finished [5:results]\n",
+ " ├── CryMainCalculation<242> Finished [411]\n",
+ " └── CryMainCalculation<247> Finished [0]\u001b[0m\n"
+ ]
+ }
+ ],
+ "source": [
+ "!verdi process status {wc_node.pk}"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 26,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[22m2019-07-18 13:02:05 [20 | REPORT]: [240|CryMainBaseWorkChain|run_calculation]: launching CryMainCalculation<242> iteration #1\n",
+ "2019-07-18 13:02:19 [23 | REPORT]: [240|CryMainBaseWorkChain|report_error_handled]: CryMainCalculation<242> failed with exit status 411: SCF convergence did not finalise (usually due to reaching step limit)\n",
+ "2019-07-18 13:02:19 [24 | REPORT]: [240|CryMainBaseWorkChain|report_error_handled]: Action taken: reduced fmixing from 50 to 40 and restarting from last calculation\n",
+ "2019-07-18 13:02:20 [25 | REPORT]: [240|CryMainBaseWorkChain|run_calculation]: launching CryMainCalculation<247> iteration #2\n",
+ "2019-07-18 13:02:30 [26 | REPORT]: [240|CryMainBaseWorkChain|inspect_calculation]: CryMainCalculation<247> completed successfully\n",
+ "2019-07-18 13:02:30 [27 | REPORT]: [240|CryMainBaseWorkChain|results]: work chain completed after 2 iterations\n",
+ "2019-07-18 13:02:30 [28 | REPORT]: [240|CryMainBaseWorkChain|on_terminated]: cleaned remote folders of calculations: 242 247\u001b[0m\n"
+ ]
+ }
+ ],
+ "source": [
+ "!verdi process report {wc_node.pk}"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 24,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "image/svg+xml": [
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n"
+ ],
+ "text/plain": [
+ ""
+ ]
+ },
+ "execution_count": 24,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "graph = Graph(graph_attr={'size': \"8,8!\", \"rankdir\": \"LR\"})\n",
+ "graph.recurse_descendants(\n",
+ " wc_node, annotate_links=\"both\",\n",
+ " include_process_inputs=True\n",
+ ")\n",
+ "graph.graphviz"
+ ]
+ }
+ ],
+ "metadata": {
+ "hide_input": false,
+ "kernelspec": {
+ "display_name": "Python 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.6.5"
+ },
+ "toc": {
+ "base_numbering": 1,
+ "nav_menu": {},
+ "number_sections": true,
+ "sideBar": true,
+ "skip_h1_title": false,
+ "title_cell": "Table of Contents",
+ "title_sidebar": "Contents",
+ "toc_cell": false,
+ "toc_position": {},
+ "toc_section_display": true,
+ "toc_window_display": false
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}