fluxopt.contributions

Per-contributor effect breakdown, read off the program.

Every contribution the ledger sums is a named expression in math/program/, declared with the entity it came from and reduced only where effect_accounting adds it up. So the breakdown is not a second implementation of the effect math that has to be checked against the first — it is the same declaration, read one step before the sum.

Two views:

• direct: each contributor shows only what it directly emits. This is what the expressions give: the coefficients are bound as declared, and the ledger adds the cross-effects on top of what each effect is charged.
• with cross-effects (default): each contributor is charged the full priced-in cost, CO2 through to cost. reporting.yaml states each contribution once more with the ledger's own chained share applied, as priced_*, so the breakdown and the ledger read one table.

The contributor axis is a presentation choice rather than model math: flows and storages share one dimension, and a component-level cost is attributed to the first flow its status governs, having no single natural flow of its own.

Functions:

Name	Description
priced	The reported expression that is name with its cross-effects charged too.
contributions_from	The breakdown, assembled from the program's own contribution expressions.
validate_against_solver	The breakdown must add up to the totals the solver reported.

priced

priced(name: str) -> str

The reported expression that is name with its cross-effects charged too.

Source code in src/fluxopt/contributions.py

def priced(name: str) -> str:
    """The reported expression that is *name* with its cross-effects charged too."""
    return name.replace('contribution_', 'priced_', 1)

contributions_from

contributions_from(
    read: Any, data: ModelData, *, cross_effects: bool = True
) -> Dataset

The breakdown, assembled from the program's own contribution expressions.

Parameters:

Name	Type	Description	Default
read	Any	Reads one named expression as a labelled array, or None where the program declares it but this system has no rows for it.	required
data	ModelData	The model data that was bound.	required
cross_effects	bool	Charge each contributor the full priced-in cost (default), or show only what it directly emits.	True

Returns:

Type	Description
Dataset	Dataset with temporal (contributor, effect, time), lump
Dataset	(contributor, effect) and total (contributor, effect).

Source code in src/fluxopt/contributions.py

def contributions_from(read: Any, data: ModelData, *, cross_effects: bool = True) -> xr.Dataset:
    """The breakdown, assembled from the program's own contribution expressions.

    Args:
        read: Reads one named expression as a labelled array, or None where
            the program declares it but this system has no rows for it.
        data: The model data that was bound.
        cross_effects: Charge each contributor the full priced-in cost
            (default), or show only what it directly emits.

    Returns:
        Dataset with ``temporal`` (contributor, effect, time), ``lump``
        (contributor, effect) and ``total`` (contributor, effect).
    """
    flow_ids = data.flows.ids
    stor_ids = data.storages.ids if data.storages is not None else []
    all_ids = flow_ids + stor_ids

    lookup = (lambda name: read(priced(name))) if cross_effects else read
    temporal = _gather(lookup, TEMPORAL, data, all_ids, None)
    lump = _gather(lookup, LUMP, data, all_ids, 'build_period')
    return _finalize(temporal, lump, all_ids, data)

validate_against_solver

validate_against_solver(total: DataArray, solution: Dataset) -> None

The breakdown must add up to the totals the solver reported.

Kept although the breakdown and the ledger are now one declaration: what it guards is no longer a second implementation of the math, but the assembly above it — the contributor mapping, the reindexing, and the coordinate order the comparison is positional in.

Source code in src/fluxopt/contributions.py

def validate_against_solver(total: xr.DataArray, solution: xr.Dataset) -> None:
    """The breakdown must add up to the totals the solver reported.

    Kept although the breakdown and the ledger are now one declaration: what
    it guards is no longer a second implementation of the math, but the
    assembly above it — the contributor mapping, the reindexing, and the
    coordinate order the comparison is positional in.
    """
    solver = solution[Var.EFFECT_TOTAL]
    # Aligned by dim *name* — which axis comes first is arbitrary and differs
    # between the solution and an expression's own declaration order. What
    # stays positional is the coordinate order *within* each dim, because a
    # misordering there is a real pipeline bug rather than a presentation one.
    computed = total.sum('contributor').transpose(*solver.dims)
    if not np.allclose(computed.values, solver.values, atol=1e-6):
        diff = abs(computed - solver)
        raise ValueError(
            f'Effect contributions do not sum to solver totals. Max deviation: {float(diff.max().values):.6g}'
        )