aiida_pythonjob_ins.workflows.tosca
===================================

.. py:module:: aiida_pythonjob_ins.workflows.tosca

.. autoapi-nested-parse::

   WorkChains composing the TOSCA scattering-intensity operations.

   Two chains, split by input rather than combined into one with an either/or port
   (see `proposal.md` and Decision 1 in `design.md`): a required parameter for one
   input (`q_spacing`) would be meaningless for the other, which a flat process spec
   cannot express honestly.

   * :class:`ToscaFromModesWorkChain` -- the stable core. Takes prepared phonon
     modes and nothing else as a source; independently runnable.
   * :class:`ToscaFromForceConstantsWorkChain` -- **inherits**
     :class:`~aiida_pythonjob_ins.workflows.base.ForceConstantsWorkChain` (it
     genuinely is a force-constants-sourced chain) while **composing**
     :class:`ToscaFromModesWorkChain` through AiiDA's exposed-input/output
     machinery, mirroring `PwBandsWorkChain` exposing `PwBaseWorkChain`
     (https://github.com/aiidateam/aiida-quantumespresso/blob/main/src/aiida_quantumespresso/workflows/pw/bands.py).

   `ToscaFromModesWorkChain` runs three provenance steps, split so that a change to
   one input does not invalidate the others under caching (Decision 5):

   1. ``compute_intensities`` -- a PythonJob computing the full, ungrouped line set
      (every atom x quantum-order x detector-angle component). Expensive; the step
      this design exists to make reusable.
   2. ``group_spectra`` -- a cheap ``calcfunction`` grouping/summing that line set by
      caller-supplied metadata keys (Decision 6).
   3. ``broaden_spectra`` -- a cheap ``calcfunction`` applying TOSCA's resolution
      broadening to the grouped result (Decision 9). Broadening after grouping is
      exact, not approximate: the resolution operator is linear, so
      ``broaden(sum(y)) == sum(broaden(y))``.



Functions
---------

.. autoapisummary::

   aiida_pythonjob_ins.workflows.tosca.group_spectra
   aiida_pythonjob_ins.workflows.tosca.broaden_spectra


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

.. py:function:: group_spectra(components: aiida.orm.XyData, group_by: aiida.orm.List) -> aiida.orm.XyData

   Group/sum the full TOSCA line set by the requested metadata keys.

   Empty keys yield a single total line: Euphonic's ``group_by()`` with no keys
   already returns a one-line ``Spectrum1DCollection`` (unlike ``sum()``, which
   returns a bare ``Spectrum1D``), so routing both cases through ``group_by``
   keeps this function's return type -- and therefore the conversion back to
   ``XyData`` -- uniform (Decision 6).


.. py:function:: broaden_spectra(grouped: aiida.orm.XyData, resolution_model: aiida.orm.Str) -> aiida.orm.XyData

   Apply TOSCA resolution broadening to an already-grouped line set.