:::{admonition} Learning Objectives :class: learning-objectives
In this section we will present a complete example of an AiiDA workflow, which defines the sequence of calculations needed to compute the band structure of silicon.
How to setup the input data and the details of the workflow execution will be discussed in subsequent sections. Here we simply give an initial overview of what it means to run an AiiDA workflow.
:::
AiiDA can be controlled in two ways:
verdi
command line interface (CLI), or %verdi
magic in Jupyter notebooks.aiida
Python APIFor each project in AiiDA, we set up a profile, which defines the connection to the data storage, and other settings.
from local_module import load_temp_profile
data = load_temp_profile(
name="bands_workflow",
add_computer=True,
add_pw_code=True,
add_sssp=True,
add_structure_si=True,
)
data
%verdi status --no-rmq
Within this profile, we have stored the initial input components for our workflow, including the pseudo-potentials, and the silicon structure:
%verdi storage info --detailed
We have also set up the compute resource that we will use to run the calculations, and the code (pw.x
) installed on that computer, which we will use to perform the electronic structure calculations.
Here, we will use our "local" machine to run the computations, but AiiDA can also be used to submit calculations to remote supercomputer schedulers, transporting data between the local machine and the remote computer.
%verdi computer show local_direct
%verdi code show pw.x@local_direct
AiiDA plugins can declare workflow plugins, for use within AiiDA. These are workflows that are pre-defined, and can be used as-is, or as a starting point for your own workflows.
Here we utilise the quantumespresso.pw.bands
workflow defined by the aiida-quantumespresso
plugin.
%verdi plugin list aiida.workflows
%verdi plugin list aiida.workflows quantumespresso.pw.bands
{height=250px align=center}
The quantumespresso.pw.bands
workflow provides a helpful method for setting up the default inputs for a given "protocol", as to how fast/precise the calculation should be.
This provides a "builder" object, which stores all the inputs for the workflow.
from aiida_quantumespresso.workflows.pw.bands import PwBandsWorkChain
builder = PwBandsWorkChain.get_builder_from_protocol(
code=data.code,
structure=data.structure,
protocol="fast",
)
builder
Workflows can be run in the interpreter using the run
method, in a blocking manner, which we shall do here.
from aiida import engine
result = engine.run_get_node(builder)
result
Typically however, long running workflows are executed by using the submit
method.
This will store the initial state of the workflow in the profile storage, and notify the AiiDA daemon to run the workflow in the background.
The AiiDA daemon can be launched using the verdi daemon start n
command, with n
being the number of worker processes to launch.
Each worker can asynchronously handle 1000s of individual calculations, allowing for a high-throughput of workflow submissions.
{height=200px align=center}
Each workflow and node stored in the AiiDA profile is assigned a unique identifier (a.k.a Primary Key), which can be used to reference them.
The execution of the workflows can be monitored using the verdi process list
command, which will show the status of all running processes in the profile (or also finished ones with -a
).
%verdi process list -a
We can also monitor the progress of individual workflows using the verdi process status
command, which will show the status of the individual steps of the workflow.
%verdi process status {result.node.pk}
This work-chain demonstrates how we can build up a complex workflow from a series of individual calculations. In this case, the workflow is made up of the following steps:
PwRelaxWorkChain
will run multiple Quantum ESPRESSO vc-relax
calculations, to make sure that there are no Pulay stresses present in the material and that the requested k-points density is respected in case there is a significant volume change in the material.scf
) is run to calculate the charge density for the structure obtained from SeeK-path.We shall also discuss in subsequent sections, how the PwBaseWorkChain
can identify and recover from known failure modes, such as reaching the wall-time limit of the scheduler, or convergence failures.
Once we the workflow has finished, we can inspect the results using the verdi process show
command, which will show the results of the workflow, and its "attached" outputs.
%verdi process show {result.node.pk}
As well as storing the inputs and outputs of the workflow, and its composite calculations, AiiDA also stores the links between them, which can be used to reconstruct the provenance graph of the workflow.
This can be visualised using the verdi node graph generate
command, or using the Graph
Python API.
from aiida.tools.visualization import Graph
graph = Graph(graph_attr={"rankdir": "TB", "size": "8!,8!"})
graph.recurse_ancestors(result.node, annotate_links="both")
graph.recurse_descendants(result.node, annotate_links="both")
graph.graphviz
pym_structure = result.node.outputs.primitive_structure.get_pymatgen()
pym_structure
from ase.visualize.plot import plot_atoms
ase_atoms = result.node.outputs.primitive_structure.get_ase()
ax = plot_atoms(ase_atoms)
from ase.visualize.ngl import NGLDisplay
NGLDisplay(ase_atoms).gui
Finally, we get to our desired result, the band structure of silicon computed using Quantum ESPRESSO 🎉
from local_module.bandstructure import plot_bandstructure
bands = result.node.outputs.band_structure
fig, ax = plot_bandstructure(bands)