Source code for energy_methods.mix_rounding
"""Reconcile rounded energy-consumption shares across nested reporting periods.
Shares are percentages of consumption, not of domestic generation.
Reported-precision envelopes are not probabilistic confidence intervals.
"""
from __future__ import annotations
import itertools
import math
from dataclasses import dataclass
[docs]
@dataclass(frozen=True)
class MonthlyShareInterval:
"""Incremental-month percentage and conservative rounding envelope."""
central_pct: float
minimum_pct: float
maximum_pct: float
[docs]
def contains_reported(self, reported_pct: float, *, rounding_pp: float = 0.5) -> bool:
"""Check compatibility with a separately rounded monthly percentage."""
if not math.isfinite(reported_pct) or not math.isfinite(rounding_pp) or rounding_pp < 0:
raise ValueError("Reported share and rounding width must be finite and valid")
return self.minimum_pct <= reported_pct + rounding_pp and (
self.maximum_pct >= reported_pct - rounding_pp
)
[docs]
def infer_incremental_month_share(
*,
preceding_demand_twh: float,
new_month_demand_twh: float,
preceding_share_pct: float,
cumulative_share_pct: float,
share_rounding_pp: float = 0.5,
preceding_demand_rounding_twh: float = 0.0,
) -> MonthlyShareInterval:
"""Infer monthly share from preceding and updated cumulative shares.
For preceding demand P, month demand M, preceding share p and cumulative
share c, the incremental month's percentage is c + (P/M) * (c-p).
All corner combinations of reported rounding intervals are evaluated.
Results are marginal bounds, not jointly attainable category balances.
"""
values = (
preceding_demand_twh,
new_month_demand_twh,
preceding_share_pct,
cumulative_share_pct,
share_rounding_pp,
preceding_demand_rounding_twh,
)
if any(not math.isfinite(value) for value in values):
raise ValueError("Every input must be finite")
if preceding_demand_twh <= 0 or new_month_demand_twh <= 0:
raise ValueError("Demand must be positive")
if preceding_demand_rounding_twh < 0 or preceding_demand_rounding_twh >= preceding_demand_twh:
raise ValueError("Invalid preceding demand uncertainty")
if share_rounding_pp < 0:
raise ValueError("Rounding width cannot be negative")
for share in (preceding_share_pct, cumulative_share_pct):
if (
not 0 <= share <= 100
or share - share_rounding_pp < 0
or share + share_rounding_pp > 100
):
raise ValueError("Shares and rounding intervals must remain inside 0-100%")
def estimate(demand: float, prior: float, cumulative: float) -> float:
return cumulative + (demand / new_month_demand_twh) * (cumulative - prior)
central = estimate(preceding_demand_twh, preceding_share_pct, cumulative_share_pct)
endpoints = [
estimate(demand, prior, cumulative)
for demand, prior, cumulative in itertools.product(
(
preceding_demand_twh - preceding_demand_rounding_twh,
preceding_demand_twh + preceding_demand_rounding_twh,
),
(
preceding_share_pct - share_rounding_pp,
preceding_share_pct + share_rounding_pp,
),
(
cumulative_share_pct - share_rounding_pp,
cumulative_share_pct + share_rounding_pp,
),
)
]
low, high = min(endpoints), max(endpoints)
if high < 0 or low > 100:
raise ValueError("Reported cumulative shares are incompatible with a valid month")
return MonthlyShareInterval(central, max(0.0, low), min(100.0, high))