AiiDA common workflows (ACWF)#

aiida-common-workflows version: 0.1.0

The AiiDA common workflows (ACWF) project

The AiiDA common workflows (ACWF) project provides computational workflows, implemented in AiiDA, to compute various material properties using any of the quantum engines that implement it. The distinguishing feature is that the interfaces of the AiiDA common workflows are uniform, independent of the quantum engine that is used underneath to perform the material property simulations. These common interfaces make it trivial to switch from quantum engine. In addition to the common interface, the workflows provide input generators that automatically define the required inputs for a given task and desired computational precision.

The common workflows can be subdivided into two categories:

Base common workflows

Workflows for basic material properties that define a common interface and are implemented for various quantum engines.

To the base workflows

Composite common workflows

Higher-level workflows that reuse base common workflows in order to maintain the common interface.

To the composite workflows

Installation#

The Python package can be installed from the Python Package index (PyPI) or directly from the source: The recommended method of installation is to use the Python package manager pip:

$ pip install aiida-common-workflows

This will install the latest stable version that was released to PyPI. Note that this will not install any of the plugin packages that are required to run any of the common workflow implementations. To install all plugin packages that implement a common workflow, run the install with the all_plugins extra:

$ pip install aiida-common-workflows[all_plugins]

Alternatively, you can choose a specific plugin to prevent having to install all plugin packages, for example:

$ pip install aiida-common-workflows[quantum_espresso]

will install the package plus the dependencies that are required to run the implementation for Quantum ESPRESSO. The available extras are abinit, bigdft, castep, cp2k, fleur, gaussian, gpaw, nwchem, orca, quantum_espresso, siesta, vasp and wien2k.

To install the package from source, first clone the repository and then install using pip:

$ git clone https://github.com/aiidateam/aiida-common-workflows
$ pip install -e aiida-common-workflows

The -e flag will install the package in editable mode, meaning that changes to the source code will be automatically picked up.

To work with aiida-common-workflows, a configured AiiDA profile is required. Please refer to AiiDA’s documentation for detailed instructions.

How to use the common workflows#

To launch a common workflow, there are two main methods:

  • Use the built-in command line interface (CLI) utility

  • Write a custom launch script

The first option is the simplest option to get started, however, it is not necessarily available for all common workflows and it does not expose the full functionality. For example, if you want to optimize the geometry of a crystal structure using the CLI, you can run the following command:

acwf launch relax -S <STRUCTURE> -X <CODE>  -- <ENGINE>

Here, the <STRUCTURE> should be replaced with the AiiDA identifier of the StructureData that needs to be optimized, <CODE> with the identifier of the Code that should be used and <ENGINE> the entry point name of the quantum engine whose workflow implementation should be employed. To determine what engine implementations are available, run the command with the --help flag:

acwf launch relax --help

This will also provide information of all other available options. Although this command already provides quite a number of options in order to facilitate various use cases, it can never expose the full functionality. If more flexibility is required, it is advised to write a custom launch script, for example:

from aiida.engine import submit
from aiida_common_workflows.plugins import WorkflowFactory

RelaxWorkChain = WorkflowFactory('common_workflows.relax.quantum_espresso')  # Load the relax workflow implementation of choice.

structure = <STRUCTURE>  # A `StructureData` node representing the structure to be optimized.
engines = {
    'relax': {
        'code': <CODE>,  # An identifier of a `Code` configured for the `quantumespresso.pw` plugin
        'options': {
            'resources': {
                'num_machines': 1,  # Number of machines/nodes to use
            },
            'max_wallclock_seconds': 3600,  # Number of wallclock seconds to request from the scheduler for each job
        }
    }
}

builder = RelaxWorkChain.get_input_generator().get_builder(structure, engines)
submit(builder)

The script essentially consists of four steps:

  1. Load the workflow implementation for the desired quantum engine based on its entry point name. To determine the available implementations, you can run the command verdi plugin list aiida.workflows. Any entry point that starts with common_workflows.relax. can be used to run the common relax workflow. The suffix denotes the quantum engine that underlies the implementation.

  2. Define the required structure and engines inputs.

  3. Retrieve the workflow builder instance for the given inputs. This get_builder method will return a process builder instance that has all the necessary inputs defined based on the protocol (see next section) of the input generator. At this point, a user is free to change any of these default inputs.

  4. All that remains is to submit the builder to the daemon and the workflow will start to run (if the daemon is running).

Input protocols#

Each base common workflow provides an input generator that implements the common interface. The generator provides the get_builder method, which for a minimum set of required inputs, returns a process builder with all the required inputs defined and therefore is ready for submission. The inputs are determined by a “protocol” which represents the desired precision. For example, the common relax workflow provides at least the three protocols fast, moderate and precise. The precise protocol will select inputs that will yield calculations of a higher precision, at a higher computational cost. The fast protocol will be computationally cheaper but will also have reduced precision.

To determine what protocols are available for a given workflow, you can call the get_protocol_names method in the input generator, for example:

RelaxWorkChain = WorkflowFactory('common_workflows.relax.quantum_espresso')
RelaxWorkChain.get_input_generator().get_protocol_names()

The default protocol can be determined as follows:

RelaxWorkChain.get_input_generator().get_default_protocol_name()

To use a different protocol for the generation of the inputs, simply pass it as an argument to the get_builder method:

RelaxWorkChain = WorkflowFactory('common_workflows.relax.quantum_espresso')
builder = RelaxWorkChain.get_input_generator().get_builder(structure=..., engines=..., protocol='precise')

Note

The inputs determined by the protocols are set on the builder and therefore can be modified before submission. These inputs are code dependent and their modification requires knowledge of the underlying quantum engine implementation of the base common workflow.

How to cite#

If you use the workflow of this package, please cite the paper in which the work is presented: S. P. Huber et al., npj Comput. Mater. 7, 136 (2021).

In addition, if you run the common workflows, please also cite the AiiDA engine that manages the simulations and stores the provenance:

You should also cite the quantum engines whose implementations are used; you can check the README of the project for a summary table of references for each quantum engine.