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
ForceConstantsDatafromcastep_file,phonopyornode.Exactly one source is accepted. Files are read in-process by a calcfunction, which links them to the output in provenance; a
nodepasses through unchanged. NoCodeis needed: job-based sources are produced upstream and passed asnode.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_constantscalcfunction. - 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
ForceConstantsWorkChainas a sub-workflow (see theforce_constantsinput namespace), then a band path is built, modes are interpolated on it, and aBandsDatais 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
ForceConstantsWorkChainsub-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_constantscalcfunction. - 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.
- castep_file, (SinglefileData, NoneType), optional – CASTEP .castep_bin/.check file, read in-process by the
- 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
ForceConstantsWorkChainas a sub-workflow (see theforce_constantsinput 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
ForceConstantsWorkChainsub-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_constantscalcfunction. - 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.
- castep_file, (SinglefileData, NoneType), optional – CASTEP .castep_bin/.check file, read in-process by the
- 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
QpointPhononModesDatanode and nothing else as a source: no file-reading step is offered, so this chain carries no q-point sampling parameter (that belongs toToscaFromForceConstantsWorkChain, 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
ForceConstantsWorkChainas a sub-workflow (a CASTEP file, read in-process by theread_castep_force_constantscalcfunction, or a prepared node – exactly one, as usual), interpolates modes on a Monkhorst-Pack grid (a powder average, matchingDosWorkChainrather than the symmetry-path sampling ofDispersionWorkChain: the almost-isotropic incoherent approximation needs a representative density of modes, not specific q-point positions), and delegates the spectrum calculation toToscaFromModesWorkChainrather 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
ToscaFromModesWorkChaindid not finish successfully.402 (ERROR_SUB_PROCESS_FAILED_FORCE_CONSTANTS): The
ForceConstantsWorkChainsub-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_constantscalcfunction. - 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.
- castep_file, (SinglefileData, NoneType), optional – CASTEP .castep_bin/.check file, read in-process by the
- 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_constantsinput group, holding the same inputs asForceConstantsWorkChain(castep_file,phonopyornode);two outline steps,
run_force_constantsandinspect_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_CONSTANTSif the child fails;the resolved
ForceConstantsDatainself.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_filewithinclude=["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.