aiida_pythonjob_ins.workflows.dispersion
========================================

.. py:module:: aiida_pythonjob_ins.workflows.dispersion

.. autoapi-nested-parse::

   A WorkChain composing Euphonic steps into a dispersion workflow.

   Steps (after force constants are resolved by :class:`ForceConstantsWorkChain` --
   read from a CASTEP file via a PythonJob, or taken from a supplied node):

   1. extract the crystal structure            -> StructureData       (calcfunction)
   2. generate a seekpath q-point path          -> KpointsData         (calcfunction)
   3. interpolate phonon modes on that path    -> QpointPhononModesData (PythonJob)
   4. compose a band structure                 -> BandsData           (calcfunction)

   The ``calcfunction`` steps run in-process (they need a loaded AiiDA profile to
   build nodes and are cheap), while the compute-heavy interpolate step runs as a
   ``PythonJob`` that could target a remote machine. Building the band path
   parent-side lets it return a native ``KpointsData`` directly -- no custom carrier
   type needed. ``BandsData`` plugs into AiiDA's plotting, e.g.
   ``results['band_structure'].show_mpl()``.

   WorkChain reference:
   https://aiida.readthedocs.io/projects/aiida-core/en/stable/topics/workflows/write.html



Functions
---------

.. autoapisummary::

   aiida_pythonjob_ins.workflows.dispersion.extract_structure
   aiida_pythonjob_ins.workflows.dispersion.generate_band_path
   aiida_pythonjob_ins.workflows.dispersion.assemble_bands


Module Contents
---------------

.. py:function:: extract_structure(data: aiida_pythonjob_ins.data.mixins.SupportsToStructure) -> aiida.orm.StructureData

   Extract a ``StructureData`` from any node implementing ``to_structure()``.

   Generic on purpose: it works for ``ForceConstantsData``,
   ``QpointPhononModesData``, or any future node exposing ``to_structure()`` (the
   ``SupportsToStructure`` protocol). It is just a calcfunction wrapper so the
   method call becomes a provenance link between the input node and the
   ``StructureData`` on the workflow graph. AiiDA infers ``valid_type=(Data,)``
   from the protocol annotation; the ``to_structure()`` call does the rest.


.. py:function:: generate_band_path(structure: aiida.orm.StructureData, q_spacing: aiida.orm.Float) -> aiida.orm.KpointsData

   Build a seekpath high-symmetry q-point path as a native ``KpointsData``.

   Depends only on the crystal *structure* (seekpath needs nothing else). A
   parent-side ``calcfunction`` (not a PythonJob): path-building is cheap and
   needs a loaded profile to construct the ``KpointsData`` node, which a remote
   PythonJob subprocess could not do.


.. py:function:: assemble_bands(modes: aiida_pythonjob_ins.data.QpointPhononModesData, qpoints: aiida.orm.KpointsData) -> aiida.orm.BandsData

   Compose a BandsData from phonon modes + the labelled q-point path.

   A ``calcfunction`` (so the BandsData is provenance-linked) that just delegates
   to the Data node's own converter; ``qpoints`` supplies the high-symmetry labels
   that Euphonic modes do not carry.