Protocol-driven workflow builders

Protocol-driven workflow builders#

aiida-abacus ships protocol-driven input generators that pre-populate AiiDA builders with recommended defaults. They are useful when you want to launch a workchain without filling every input port by hand.

The generators live in aiida_abacus.protocols and wrap the standard AiiDA WorkflowFactory(...).get_builder_from_protocol(...) pattern with a lighter, user-facing interface.

Available generators#

The current public generators are:

  • AbacusBaseInputGenerator for AbacusBaseWorkChain

  • AbacusRelaxInputGenerator for AbacusRelaxWorkChain

  • AbacusBandInputGenerator for AbacusBandWorkChain

Each generator starts from a named preset and protocol, then applies any runtime overrides on top.

Protocols and presets#

Protocol data is stored as YAML files under src/aiida_abacus/protocols/. The default preset is src/aiida_abacus/protocols/presets/default.yaml, which defines the default code, options, and workflow-specific defaults such as relax and band settings.

The generator looks for presets in three places:

  • the package data shipped with aiida-abacus

  • user-defined files under ~/.aiida-abacus/presets/

  • legacy user-defined files under ~/.aiida-abacus/protocol_presets/

This makes it possible to keep site-specific settings outside the source tree while still using the same public Python API.

Basic usage#

from aiida import orm
from aiida_abacus.protocols import AbacusRelaxInputGenerator

structure = orm.StructureData(...)  # supply your structure here

generator = AbacusRelaxInputGenerator(preset_name="default", protocol="balanced")
builder = generator.build(
    structure=structure,
    code="abacus@localhost",
)

generator.set_label("silicon-relax")
generator.set_resources(num_machines=1, tot_num_mpiprocs=4)
generator.set_options(max_wallclock_seconds=3600)

After build(...) returns, the generator keeps a reference to the builder and can update common ports through helper methods such as:

  • set_options(...)

  • set_resources(...)

  • set_settings(...)

  • set_input(...)

  • set_kpoints_distance(...)

  • set_kpoints_mesh(...)

  • set_pseudo_family(...)

  • set_code(...)

Use submit() to launch the workflow on the daemon, or run_get_node() for local execution during development.

Relax and band helpers#

The specialized generators expose a small number of workflow-specific ports:

  • AbacusRelaxInputGenerator.set_relax_settings(...) updates the relaxation settings namespace.

  • AbacusBandInputGenerator.set_band_settings(...) updates the band-structure settings namespace.

Both classes also apply their workflow defaults from the active preset when those defaults are defined in the YAML file.

Practical notes#

The generators are intended to reduce boilerplate, not to hide the underlying builder. You can always inspect or further modify the returned builder before submission if a calculation needs manual adjustments.

For ABACUS-specific input details, see the calculations how-to and pseudopotential guide.