Workflows

The high-level WorkChains and their inputs/outputs. ForceConstantsWorkChain resolves a force-constants source into a ForceConstantsData: a CASTEP castep_file, a Phonopy file set under phonopy, or a pre-built node. It is also runnable standalone. The workflows that start from force constants – DispersionWorkChain, DosWorkChain and ToscaFromForceConstantsWorkChain – run it as a sub-workflow, grouping its inputs under a single force_constants namespace (e.g. force_constants={"castep_file": f}, force_constants={"phonopy": {"summary": s, "force_constants": fc, "born": b}} or force_constants={"node": fc}). ToscaFromModesWorkChain instead starts from precomputed phonon modes and offers no force-constants source at all – see the worked examples. To build a workflow of your own on top of ForceConstantsWorkChain, see Building your own workflow on ForceConstantsWorkChain below.

These pages are generated from the live process spec by AiiDA’s aiida-workchain directive, showing the inputs, outputs, and outline, with exit codes listed in each workflow’s description.

workchainaiida_alc_ins.workflows.force_constants.ForceConstantsWorkChain

Resolve a ForceConstantsData from castep_file, phonopy or node.

Exactly one source is accepted. Files are read in-process by a calcfunction, which links them to the output in provenance; a node passes through unchanged. No Code is needed: job-based sources are produced upstream and passed as node.

Exit Codes

  • 410 (ERROR_READ_FAILED): A CASTEP or Phonopy file could not be read.

Inputs:

  • castep_file, (SinglefileData, NoneType), optional – CASTEP .castep_bin/.check file, read in-process by the read_castep_force_constants calcfunction.
  • metadata, Namespace
    • call_link_label, str, optional, is_metadata – The label to use for the CALL link if the process is called by another process.
    • description, (str, NoneType), optional, is_metadata – Description to set on the process node.
    • disable_cache, (bool, NoneType), optional, is_metadata – Do not consider the cache for this process, ignoring all other caching configuration rules.
    • label, (str, NoneType), optional, is_metadata – Label to set on the process node.
    • store_provenance, bool, optional, is_metadata – If set to False provenance will not be stored in the database.
  • node, (ForceConstantsData, NoneType), optional – A prepared ForceConstantsData, built by any means; passed through unchanged.
  • phonopy, Namespace – Phonopy output files; read in-process by read_phonopy_force_constants.
    • born, (SinglefileData, NoneType), optional – Born-charges file (BORN). Ignored if the summary already holds Born data.
    • force_constants, (SinglefileData, NoneType), optional – Force-constants file: HDF5 if the file name ends in .hdf5/.hd5/.h5, otherwise Phonopy text format (FORCE_CONSTANTS). Omit if the summary already contains force constants.
    • summary, SinglefileData, required – Phonopy summary file (phonopy.yaml). Required when phonopy is used.

Outputs:

  • force_constants, ForceConstantsData, required – The resolved force constants (read from a file or passed through).

Outline:

if(has_castep_file)
    read_castep_file(Read the CASTEP file; fail with ``ERROR_READ_FAILED``.)
elif(has_phonopy)
    read_phonopy(Read the Phonopy files; fail with ``ERROR_READ_FAILED``.)
elif(<lambda>)
    use_node(Pass the supplied force-constants node through directly.)
finalize(Expose the resolved force constants as the workflow output.)

workchainaiida_alc_ins.workflows.dispersion.DispersionWorkChain

Compute phonon dispersion from a CASTEP file or a ForceConstantsData node.

The force-constants source is resolved by running ForceConstantsWorkChain as a sub-workflow (see the force_constants input namespace), then a band path is built, modes are interpolated on it, and a BandsData is composed.

Exit Codes

  • 400 (ERROR_SUB_PROCESS_FAILED): A PythonJob step of this workflow did not finish successfully.

  • 402 (ERROR_SUB_PROCESS_FAILED_FORCE_CONSTANTS): The ForceConstantsWorkChain sub-workflow did not finish successfully.

Inputs:

  • code, AbstractCode, required – Python code used to run the PythonJob steps.
  • force_constants, Namespace
    • castep_file, (SinglefileData, NoneType), optional – CASTEP .castep_bin/.check file, read in-process by the read_castep_force_constants calcfunction.
    • metadata, Namespace
      • call_link_label, str, optional, is_metadata – The label to use for the CALL link if the process is called by another process.
      • description, (str, NoneType), optional, is_metadata – Description to set on the process node.
      • disable_cache, (bool, NoneType), optional, is_metadata – Do not consider the cache for this process, ignoring all other caching configuration rules.
      • label, (str, NoneType), optional, is_metadata – Label to set on the process node.
      • store_provenance, bool, optional, is_metadata – If set to False provenance will not be stored in the database.
    • node, (ForceConstantsData, NoneType), optional – A prepared ForceConstantsData, built by any means; passed through unchanged.
    • phonopy, Namespace – Phonopy output files; read in-process by read_phonopy_force_constants.
      • born, (SinglefileData, NoneType), optional – Born-charges file (BORN). Ignored if the summary already holds Born data.
      • force_constants, (SinglefileData, NoneType), optional – Force-constants file: HDF5 if the file name ends in .hdf5/.hd5/.h5, otherwise Phonopy text format (FORCE_CONSTANTS). Omit if the summary already contains force constants.
      • summary, SinglefileData, required – Phonopy summary file (phonopy.yaml). Required when phonopy is used.
  • metadata, Namespace
    • call_link_label, str, optional, is_metadata – The label to use for the CALL link if the process is called by another process.
    • description, (str, NoneType), optional, is_metadata – Description to set on the process node.
    • disable_cache, (bool, NoneType), optional, is_metadata – Do not consider the cache for this process, ignoring all other caching configuration rules.
    • label, (str, NoneType), optional, is_metadata – Label to set on the process node.
    • store_provenance, bool, optional, is_metadata – If set to False provenance will not be stored in the database.
  • options, (Dict, NoneType), optional – Optional scheduler and execution options passed to child PythonJobs.
  • q_spacing, Float, optional – Target q-point spacing along the band path, in 1/Angstrom.

Outputs:

  • band_path, KpointsData, required – The high-symmetry q-point path (positions + labels).
  • band_structure, BandsData, required – Phonon band structure (frequencies as bands) for plotting.
  • phonon_modes, QpointPhononModesData, required – Frequencies + eigenvectors along the band path.
  • structure, StructureData, required – Crystal structure extracted from the force constants.

Outline:

run_force_constants(Submit the ``ForceConstantsWorkChain`` child with exposed inputs.)
inspect_force_constants(Store the child's output, or fail with 402 if it did not finish ok.)
generate_path(Extract the structure, then build the q-point path. Both are parent-side calcfunctions (cheap, and they build AiiDA nodes). seekpath needs only the structure, so we materialize a ``StructureData`` first -- reusable and idiomatic -- then derive the path from it.)
interpolate(Interpolate phonon modes on the q-point path.)
finalize(Expose the modes, path and a composed BandsData.)

workchainaiida_alc_ins.workflows.dos.DosWorkChain

Compute a phonon DOS from a CASTEP file or a ForceConstantsData node.

The force-constants source is resolved by running ForceConstantsWorkChain as a sub-workflow (see the force_constants input namespace), then a single PythonJob samples a Monkhorst-Pack grid and computes the DOS.

Exit Codes

  • 400 (ERROR_SUB_PROCESS_FAILED): A PythonJob step of this workflow did not finish successfully.

  • 402 (ERROR_SUB_PROCESS_FAILED_FORCE_CONSTANTS): The ForceConstantsWorkChain sub-workflow did not finish successfully.

Inputs:

  • code, AbstractCode, required – Python code used to run the PythonJob steps.
  • energy_spacing, Float, optional – DOS energy bin width, in meV.
  • force_constants, Namespace
    • castep_file, (SinglefileData, NoneType), optional – CASTEP .castep_bin/.check file, read in-process by the read_castep_force_constants calcfunction.
    • metadata, Namespace
      • call_link_label, str, optional, is_metadata – The label to use for the CALL link if the process is called by another process.
      • description, (str, NoneType), optional, is_metadata – Description to set on the process node.
      • disable_cache, (bool, NoneType), optional, is_metadata – Do not consider the cache for this process, ignoring all other caching configuration rules.
      • label, (str, NoneType), optional, is_metadata – Label to set on the process node.
      • store_provenance, bool, optional, is_metadata – If set to False provenance will not be stored in the database.
    • node, (ForceConstantsData, NoneType), optional – A prepared ForceConstantsData, built by any means; passed through unchanged.
    • phonopy, Namespace – Phonopy output files; read in-process by read_phonopy_force_constants.
      • born, (SinglefileData, NoneType), optional – Born-charges file (BORN). Ignored if the summary already holds Born data.
      • force_constants, (SinglefileData, NoneType), optional – Force-constants file: HDF5 if the file name ends in .hdf5/.hd5/.h5, otherwise Phonopy text format (FORCE_CONSTANTS). Omit if the summary already contains force constants.
      • summary, SinglefileData, required – Phonopy summary file (phonopy.yaml). Required when phonopy is used.
  • metadata, Namespace
    • call_link_label, str, optional, is_metadata – The label to use for the CALL link if the process is called by another process.
    • description, (str, NoneType), optional, is_metadata – Description to set on the process node.
    • disable_cache, (bool, NoneType), optional, is_metadata – Do not consider the cache for this process, ignoring all other caching configuration rules.
    • label, (str, NoneType), optional, is_metadata – Label to set on the process node.
    • store_provenance, bool, optional, is_metadata – If set to False provenance will not be stored in the database.
  • options, (Dict, NoneType), optional – Optional scheduler and execution options passed to child PythonJobs.
  • q_spacing, Float, optional – Target Monkhorst-Pack grid spacing, in 1/Angstrom.

Outputs:

  • dos, XyData, required – Phonon density of states (energy vs DOS).

Outline:

run_force_constants(Submit the ``ForceConstantsWorkChain`` child with exposed inputs.)
inspect_force_constants(Store the child's output, or fail with 402 if it did not finish ok.)
compute_dos(Sample a grid and compute the DOS.)
finalize(Expose the DOS XyData.)

workchainaiida_alc_ins.workflows.tosca.ToscaFromModesWorkChain

Compute a TOSCA spectrum from prepared phonon modes.

Takes a QpointPhononModesData node and nothing else as a source: no file-reading step is offered, so this chain carries no q-point sampling parameter (that belongs to ToscaFromForceConstantsWorkChain, which composes this one). The node-taking chain is the stable centre; any file-ingesting convenience composes around it rather than altering the core.

Exit Codes

  • 400 (ERROR_SUB_PROCESS_FAILED): The intensity PythonJob did not finish successfully.

Inputs:

  • code, AbstractCode, required – Python code used to run the PythonJob steps.
  • detector_angles, List, optional – Scattering angles in degrees, one per detector bank to evaluate.
  • energy_max, Float, optional – Instrument-range cutoff on the energy axis, in energy_unit. TOSCA results are conventionally examined up to 4000 cm-1, comfortably inside the ~8000 cm-1 the instrument can reach.
  • energy_spacing, Float, optional – Energy bin width, in energy_unit.
  • energy_unit, Str, optional – Unit for energy_spacing, energy_max and final_energy.
  • final_energy, Float, optional – Analyser-fixed final neutron energy, in energy_unit.
  • group_by, List, optional – Metadata keys to group and sum spectrum lines by (e.g. [‘atom_symbol’], [‘quantum_order’], or both). Empty (the default) yields a single total spectrum.
  • metadata, Namespace
    • call_link_label, str, optional, is_metadata – The label to use for the CALL link if the process is called by another process.
    • description, (str, NoneType), optional, is_metadata – Description to set on the process node.
    • disable_cache, (bool, NoneType), optional, is_metadata – Do not consider the cache for this process, ignoring all other caching configuration rules.
    • label, (str, NoneType), optional, is_metadata – Label to set on the process node.
    • store_provenance, bool, optional, is_metadata – If set to False provenance will not be stored in the database.
  • modes, QpointPhononModesData, required – Precomputed phonon modes to simulate a TOSCA spectrum from.
  • options, (Dict, NoneType), optional – Optional scheduler and execution options passed to child PythonJobs.
  • resolution_model, Str, optional – Name of the resins resolution model applied when broadening.
  • temperature, Float, optional – Sample temperature in kelvin (governs Debye-Waller attenuation).

Outputs:

  • components, XyData, required – The full, ungrouped line set: one line per contributing atom, quantum order and detector angle. Committed to the graph before grouping so that regrouping can reuse this calculation.
  • spectrum, XyData, required – The grouped and resolution-broadened TOSCA spectrum.

Outline:

compute_intensities(Compute the full, ungrouped line set as a PythonJob.)
group(Group the committed line set by the requested metadata keys.)
broaden(Apply resolution broadening to the grouped spectrum.)
finalize(Expose the ungrouped components and the grouped, broadened spectrum.)

workchainaiida_alc_ins.workflows.tosca.ToscaFromForceConstantsWorkChain

Compute a TOSCA spectrum from force constants, via interpolated modes.

Resolves force constants by running ForceConstantsWorkChain as a sub-workflow (a CASTEP file, read in-process by the read_castep_force_constants calcfunction, or a prepared node – exactly one, as usual), interpolates modes on a Monkhorst-Pack grid (a powder average, matching DosWorkChain rather than the symmetry-path sampling of DispersionWorkChain: the almost-isotropic incoherent approximation needs a representative density of modes, not specific q-point positions), and delegates the spectrum calculation to ToscaFromModesWorkChain rather than reimplementing it, so the intensity calculation stays reusable.

Exit Codes

  • 400 (ERROR_SUB_PROCESS_FAILED): A PythonJob step of this workflow’s own (the mode interpolation) did not finish successfully.

  • 401 (ERROR_SPECTRUM_WORKCHAIN_FAILED): The delegated ToscaFromModesWorkChain did not finish successfully.

  • 402 (ERROR_SUB_PROCESS_FAILED_FORCE_CONSTANTS): The ForceConstantsWorkChain sub-workflow did not finish successfully.

Inputs:

  • code, AbstractCode, required – Python code used to run the PythonJob steps.
  • force_constants, Namespace
    • castep_file, (SinglefileData, NoneType), optional – CASTEP .castep_bin/.check file, read in-process by the read_castep_force_constants calcfunction.
    • metadata, Namespace
      • call_link_label, str, optional, is_metadata – The label to use for the CALL link if the process is called by another process.
      • description, (str, NoneType), optional, is_metadata – Description to set on the process node.
      • disable_cache, (bool, NoneType), optional, is_metadata – Do not consider the cache for this process, ignoring all other caching configuration rules.
      • label, (str, NoneType), optional, is_metadata – Label to set on the process node.
      • store_provenance, bool, optional, is_metadata – If set to False provenance will not be stored in the database.
    • node, (ForceConstantsData, NoneType), optional – A prepared ForceConstantsData, built by any means; passed through unchanged.
    • phonopy, Namespace – Phonopy output files; read in-process by read_phonopy_force_constants.
      • born, (SinglefileData, NoneType), optional – Born-charges file (BORN). Ignored if the summary already holds Born data.
      • force_constants, (SinglefileData, NoneType), optional – Force-constants file: HDF5 if the file name ends in .hdf5/.hd5/.h5, otherwise Phonopy text format (FORCE_CONSTANTS). Omit if the summary already contains force constants.
      • summary, SinglefileData, required – Phonopy summary file (phonopy.yaml). Required when phonopy is used.
  • metadata, Namespace
    • call_link_label, str, optional, is_metadata – The label to use for the CALL link if the process is called by another process.
    • description, (str, NoneType), optional, is_metadata – Description to set on the process node.
    • disable_cache, (bool, NoneType), optional, is_metadata – Do not consider the cache for this process, ignoring all other caching configuration rules.
    • label, (str, NoneType), optional, is_metadata – Label to set on the process node.
    • store_provenance, bool, optional, is_metadata – If set to False provenance will not be stored in the database.
  • options, (Dict, NoneType), optional – Optional scheduler and execution options passed to child PythonJobs.
  • q_spacing, Float, optional – Target Monkhorst-Pack grid spacing for the mode sampling, in 1/Angstrom.
  • spectrum, Namespace – Scientific and instrument inputs forwarded to the composed ToscaFromModesWorkChain (modes and code excluded: modes is produced internally, and code is provided at the top level for this workflow’s own mode-interpolation step).
    • detector_angles, List, optional – Scattering angles in degrees, one per detector bank to evaluate.
    • energy_max, Float, optional – Instrument-range cutoff on the energy axis, in energy_unit. TOSCA results are conventionally examined up to 4000 cm-1, comfortably inside the ~8000 cm-1 the instrument can reach.
    • energy_spacing, Float, optional – Energy bin width, in energy_unit.
    • energy_unit, Str, optional – Unit for energy_spacing, energy_max and final_energy.
    • final_energy, Float, optional – Analyser-fixed final neutron energy, in energy_unit.
    • group_by, List, optional – Metadata keys to group and sum spectrum lines by (e.g. [‘atom_symbol’], [‘quantum_order’], or both). Empty (the default) yields a single total spectrum.
    • metadata, Namespace
      • call_link_label, str, optional, is_metadata – The label to use for the CALL link if the process is called by another process.
      • description, (str, NoneType), optional, is_metadata – Description to set on the process node.
      • disable_cache, (bool, NoneType), optional, is_metadata – Do not consider the cache for this process, ignoring all other caching configuration rules.
      • label, (str, NoneType), optional, is_metadata – Label to set on the process node.
      • store_provenance, bool, optional, is_metadata – If set to False provenance will not be stored in the database.
    • options, (Dict, NoneType), optional – Optional scheduler and execution options passed to child PythonJobs.
    • resolution_model, Str, optional – Name of the resins resolution model applied when broadening.
    • temperature, Float, optional – Sample temperature in kelvin (governs Debye-Waller attenuation).

Outputs:

  • components, XyData, required – The full, ungrouped line set: one line per contributing atom, quantum order and detector angle. Committed to the graph before grouping so that regrouping can reuse this calculation.
  • spectrum, XyData, required – The grouped and resolution-broadened TOSCA spectrum.

Outline:

run_force_constants(Submit the ``ForceConstantsWorkChain`` child with exposed inputs.)
inspect_force_constants(Store the child's output, or fail with 402 if it did not finish ok.)
interpolate_modes(Interpolate phonon modes on a Monkhorst-Pack grid, as a PythonJob.)
compute_spectrum(Delegate the spectrum calculation to ToscaFromModesWorkChain.)
finalize(Expose the delegated workchain's outputs as this chain's own.)

Building your own workflow on ForceConstantsWorkChain

ForceConstantsWorkChain is the building block for getting force constants onto the provenance graph. You can launch it on its own, or run it as a child of a workflow of your own. Whichever source the caller supplies, your workflow gets a ForceConstantsData back, and as more input formats are supported, your workflow picks them up without any changes.

The shortcut: FromForceConstantsWorkChain

The workflows in this package all use ForceConstantsWorkChain the same way, so that shared code lives in one helper base class, FromForceConstantsWorkChain (in aiida_alc_ins.workflows.base). Its name says what it is for: workflows that start from force constants. It does not inherit from ForceConstantsWorkChain. Instead, it runs ForceConstantsWorkChain for you. Inheriting it gives your workflow:

  • a force_constants input group, holding the same inputs as ForceConstantsWorkChain (castep_file, phonopy or node);

  • two outline steps, run_force_constants and inspect_force_constants, which run the child and collect its result. They are two steps because a WorkChain submits a child in one step and the engine resumes it in the next, once the child has finished; see AiiDA’s Submitting sub processes;

  • exit code 402 ERROR_SUB_PROCESS_FAILED_FORCE_CONSTANTS if the child fails;

  • the resolved ForceConstantsData in self.ctx.force_constants.

A minimal example:

from aiida_alc_ins.workflows.base import FromForceConstantsWorkChain


class MyWorkChain(FromForceConstantsWorkChain):
    @classmethod
    def define(cls, spec):
        super().define(spec)
        spec.outline(
            cls.run_force_constants,
            cls.inspect_force_constants,
            cls.analyse,
        )

    def analyse(self):
        force_constants = self.ctx.force_constants  # a ForceConstantsData
        ...

Callers then pass the source just as they would to DispersionWorkChain, for example force_constants={"castep_file": f}. If your workflow also dispatches PythonJobs, inherit JobDispatchWorkChain from the same module as well, as DispersionWorkChain does, to get the code and options inputs and exit code 400.

Composing it directly

The shortcut is a convenience, not a requirement. It suits workflows that need one source and resolve it first. If yours doesn’t, run ForceConstantsWorkChain yourself with AiiDA’s expose_inputs and exposed_inputs. For example:

  • your workflow needs several sources, such as two calculations to compare;

  • it resolves force constants later, or only under some condition;

  • it accepts only some sources, for example exposing just castep_file with include=["castep_file"];

  • it handles failure differently, for example falling back to another source.

Here is a workflow that compares two sources:

from aiida.engine import ToContext, WorkChain

from aiida_alc_ins.workflows import ForceConstantsWorkChain


class CompareWorkChain(WorkChain):
    @classmethod
    def define(cls, spec):
        super().define(spec)
        spec.expose_inputs(ForceConstantsWorkChain, namespace="first")
        spec.expose_inputs(ForceConstantsWorkChain, namespace="second")
        spec.outline(cls.resolve_both, cls.compare)
        spec.exit_code(
            402,
            "ERROR_SUB_PROCESS_FAILED_FORCE_CONSTANTS",
            message="A ForceConstantsWorkChain sub-workflow did not finish successfully.",
        )

    def resolve_both(self):
        return ToContext(
            first=self.submit(
                ForceConstantsWorkChain,
                **self.exposed_inputs(ForceConstantsWorkChain, namespace="first"),
            ),
            second=self.submit(
                ForceConstantsWorkChain,
                **self.exposed_inputs(ForceConstantsWorkChain, namespace="second"),
            ),
        )

    def compare(self):
        if not (self.ctx.first.is_finished_ok and self.ctx.second.is_finished_ok):
            return self.exit_codes.ERROR_SUB_PROCESS_FAILED_FORCE_CONSTANTS
        first = self.ctx.first.outputs.force_constants
        second = self.ctx.second.outputs.force_constants
        ...

Callers write first={"castep_file": f}, second={"node": fc}. Each group checks on its own that exactly one source was given.

The one rule

However you compose it, go through ForceConstantsWorkChain rather than reading force-constants files yourself. That keeps all the source handling in one place, so new formats and fixes reach every workflow, including yours.