fluxopt.stats

Derived statistics from optimization results.

Computes post-processing quantities that require ModelData (dt, weights) — energy totals, effect contributions, solver metadata.

Classes:

Name	Description
StatsAccessor	Post-processing statistics for a solved optimization result.

StatsAccessor

StatsAccessor(result: Result)

Post-processing statistics for a solved optimization result.

Accessed via result.stats.

Parameters:

Name	Type	Description	Default
result	Result	Solved Result.	required

Attributes:

Name	Type	Description
flow_hours	DataArray	Energy per flow per timestep: P_{f,t} * dt_t.
total_flow_hours	DataArray	Total energy per flow over the horizon, weighted.
carrier_balance	DataArray	Signed balance per carrier: coeff * P. (carrier, flow, time).
effect_contributions_direct	Dataset	Per-contributor effect breakdown without cross-effect propagation.
effect_contributions	Dataset	Per-contributor effect breakdown with cross-effects propagated.

Source code in src/fluxopt/stats.py

def __init__(self, result: Result) -> None:
    self._result = result

flow_hours cached property

flow_hours: DataArray

Energy per flow per timestep: P_{f,t} * dt_t.

Returns:

Type	Description
DataArray	DataArray (flow, time) in energy units (e.g. MWh).

total_flow_hours cached property

total_flow_hours: DataArray

Total energy per flow over the horizon, weighted.

Returns:

Type	Description
DataArray	DataArray (flow,) — weighted sum of flow_hours over time.

carrier_balance cached property

carrier_balance: DataArray

Signed balance per carrier: coeff * P. (carrier, flow, time).

effect_contributions_direct cached property

effect_contributions_direct: Dataset

Per-contributor effect breakdown without cross-effect propagation.

Each contributor only carries effects it directly emits — contribution_from chains are ignored. Useful for attributing physical quantities (e.g. raw CO₂ emissions) without conflating them with priced-in monetary effects.

Returns:

Type	Description
Dataset	Dataset with temporal, lump, and total DataArrays.

effect_contributions cached property

effect_contributions: Dataset

Per-contributor effect breakdown with cross-effects propagated.

Decomposes effect totals into per-contributor parts on a unified contributor dimension (flow IDs + storage IDs)::

contrib = result.stats.effect_contributions
contrib['temporal']  # (contributor, effect, time)
contrib['lump']  # (contributor, effect)
contrib['total']  # (contributor, effect) — temporal sum + lump

Cross-effects (e.g. CO₂ → cost via Effect.contribution_from) are propagated through the Leontief inverse, so each contributor is charged the full priced-in cost. The contributions are validated against solver totals; a ValueError is raised if they don't match.

Built on top of :attr:effect_contributions_direct — when both views are accessed, the heavy direct computation runs only once.

Returns:

Type	Description
Dataset	Dataset with temporal, lump, and total DataArrays.