This section describes the different base workchains and utilities for workchain development.


Utilities for WorkChain implementations.

class aiida_quantumespresso.common.workchain.utils.ErrorHandler(priority, method)

A namedtuple to define an error handler for a WorkChain.

The priority determines in which order the error handling methods are executed, with the higher priority being executed first. The method defines an unbound WorkChain method that takes an instance of a CalcJobNode as its sole argument. If the condition of the error handler is met, it should return an ErrorHandlerReport.

  • priority – integer denoting the error handlers priority
  • method – the workchain class method

Alias for field number 1


Alias for field number 0

class aiida_quantumespresso.common.workchain.utils.ErrorHandlerReport(is_handled, do_break, exit_code)

Alias for field number 1


Alias for field number 2


Alias for field number 0

aiida_quantumespresso.common.workchain.utils.register_error_handler(cls, priority=None)[source]

Decorator that will turn any function in an error handler for workchain that inherits from the BaseRestartWorkChain. The function expects two arguments, a workchain class and a priortity. The decorator will add the function as a class method to the workchain class and add an ErrorHandler tuple to the BaseRestartWorkChain._error_handlers attribute of the workchain. During failed calculation handling the inspect_calculation() outline method will call the _handle_calculation_failure which will loop over all error handler in the BaseRestartWorkChain._error_handlers, sorted with respect to the priority in reverse. If the workchain class defines a BaseRestartWorkChain._verbose attribute and is set to True, a report message will be fired when the error handler is executed.

Requirements on the function signature of error handling functions. The function to which the decorator is applied needs to take two arguments:

  • self: This is the instance of the workchain itself
  • calculation: This is the calculation that failed and needs to be investigated

The function body should usually consist of a single conditional that checks the calculation if the error that it is designed to handle is applicable. Although not required, it is advised that the function return an ErrorHandlerReport tuple when its conditional was met. If an error was handled it should set is_handled to True. If no other error handlers should be considered set do_break to True.

  • cls – the workchain class to register the error handler with
  • priority – optional integer that defines the order in which registered handlers will be called during the handling of a failed calculation. Higher priorities will be handled first. If the priority is None the handler will not be automatically called during calculation failure handling. This is useful to define handlers that one only wants to call manually, for example in the _handle_sanity_checks and still profit from the other features of this decorator.

Base workchains

class aiida_quantumespresso.common.workchain.base.restart.BaseRestartWorkChain(*args, **kwargs)[source]

Base restart work chain

This work chain serves as the starting point for more complex work chains that will be designed to run a calculation that might need multiple restarts to come to a successful end. These restarts may be necessary because a single calculation run is not sufficient to achieve a fully converged result, or certain errors maybe encountered which are recoverable.

This work chain implements the most basic functionality to achieve this goal. It will launch calculations, restarting until it is completed successfully or the maximum number of iterations is reached. It can recover from errors through error handlers that can be attached dynamically through the register_error_handler decorator.

The idea is to sub class this work chain and leverage the generic error handling that is implemented in the few outline methods. The minimally required outline would look something like the following:


Each of these methods can of course be overriden but they should be general enough to fit most calculation cycles. The run_calculation method will take the inputs for the calculation process from the context under the key inputs. The user should therefore make sure that before the run_calculation method is called, that the to be used inputs are stored under self.ctx.inputs. One can update the inputs based on the results from a prior calculation by calling an outline method just before the run_calculation step, for example:


Where in the prepare_calculation method, the inputs dictionary at self.ctx.inputs is updated before the next calculation will be run with those inputs.

The _calculation_class attribute should be set to the CalcJob class that should be run in the loop.

_verbose = False
_calculation_class = None
_error_handler_entry_point = None

Analyse the results of the previous calculation and call the error handlers when necessary.

load_instance_state(saved_state, load_context)[source]

Load instance state.

  • saved_state – saved instance state
  • load_context (plumpy.persistence.LoadSaveContext) –

Clean the working directories of all child calculations if clean_workdir=True in the inputs.


Attach the outputs specified in the output specification from the last completed calculation.


Run the next calculation, taking the input dictionary from the context at self.ctx.inputs.


Initialize context variables that are used during the logical flow of the BaseRestartWorkChain.


Return whether a new calculation should be run.

This is the case as long as the last calculation has not finished successfully and the maximum number of restarts has not yet been exceeded.

Full workchains

class*args, **kwargs)[source]

Workchain to run a Quantum ESPRESSO ph.x calculation with automated error handling and restarts.

class*args, **kwargs)[source]

Workchain to run a Quantum ESPRESSO pw.x calculation with automated error handling and restarts.

class, logger=None, runner=None, enable_persistence=True)[source]

Workchain to relax a structure using Quantum ESPRESSO pw.x

class, logger=None, runner=None, enable_persistence=True)[source]

Workchain to compute a band structure for a given structure using Quantum ESPRESSO pw.x