Source code for pycif.plugins.transforms.basic.families

"""
``families`` transform: aggregate multiple tracers into one by summation.

Sums a list of input tracers (``parameters_in``) to produce a single output
tracer (``parameter_out``):

.. math::

    y_{out} = \\sum_{i} x_{in,i}

A typical use case is grouping isotopologue species (e.g. ¹²CH₄ and ¹³CH₄)
into a total CH₄ field, or combining sectoral emission fluxes into a single
total flux field.

The adjoint broadcasts the output sensitivity back equally to every input
tracer (since :math:`\\partial y_{out} / \\partial x_{in,i} = 1`).

Both gridded (xarray) and sparse (observation-indexed DataFrame) data are
supported.  Ensemble (batch sampling) runs with ``__sample#N`` tracer
names are handled by routing each sample's inputs to the corresponding
output.
"""


from .forward import forward
from .adjoint import adjoint

_name = "families"
_fullname = "Tracer families or addition"

input_arguments = {
    "component": {
        "doc": "Component of the input tracers to be aggregated",
        "default": None,
        "accepted": str
    },
    "component_out": {
        "doc": "Component of the output tracer, if different from the input component.",
        "default": None,
        "optional": True,
        "accepted": str
    },
    "parameters_in": {
        "doc": "List of tracers to be aggregated.",
        "default": None,
        "accepted": list
    },
    "parameter_out": {
        "doc": "Name of the output tracer.",
        "default": None,
        "optional": True,
        "accepted": str
    }
}




def ini_mapper(transform, general_mapper={}, **kwargs):
    """Build the mapper for families.

    Declares one input entry per input tracer and one output entry for the
    aggregated tracer.  Populates ``outputs2inputs`` for routing.
    An optional ``component_out`` overrides the output component name.

    Args:
        transform: families plugin instance (carries ``parameters_in``,
            ``parameter_out``, ``component``, and optionally
            ``component_out``).
        general_mapper (dict): unused.
        **kwargs: unused.

    Returns:
        dict: mapper with ``inputs``, ``outputs``, and ``outputs2inputs``.
    """
    parameters_in = transform.parameters_in
    parameter_out = transform.parameter_out
    component = transform.component
    component_out = getattr(transform, "component_out", component)

    trid_out = (component_out, parameter_out)

    loc_outputs = {
        trid_out:
            {"force_loadin": True, "force_dump": False,
             "tracer_from_previous": True,
             #  "sparse_data_from_previous": True,
             #  "dates_from_previous": True
             }
    }
    loc_inputs = {
        (component, param):
            {"force_loadin": True, "force_dump": False}
        for param in parameters_in
    }

    mapper = {"inputs": loc_inputs, "outputs": loc_outputs}

    mapper["outputs2inputs"] = {
        trid_out: [(component, param) for param in parameters_in]
    }

    return mapper