Source code for energy_methods.curtailment_storage

"""Curtailment ratios, price screens and equivalent storage (Acosta et al., 2027).

Implements Table 1 and Eqs. (1)-(5), DOI 10.1016/j.est.2026.125203.
EESC is the paper's effective-power indicator, not a nameplate BESS design.
Price separation is an observational proxy, not proof of physical congestion.
"""

from __future__ import annotations

import math
from collections.abc import Sequence
from dataclasses import dataclass

import numpy as np
import pandas as pd


def _nonnegative(value: float, name: str) -> None:
    if isinstance(value, bool) or not math.isfinite(value) or value < 0:
        raise ValueError(f"{name} must be finite and nonnegative")


[docs] def curtailment_ratios(curtailed_mwh: float, generated_mwh: float) -> dict[str, float | None]: """Return both denominators; undefined ratios are None, never infinity. The paper's Table 3 divides curtailed energy by reported generation. The potential-energy share divides by generation PLUS curtailment. Inputs must cover the same technology, geography and time period. """ _nonnegative(curtailed_mwh, "curtailed_mwh") _nonnegative(generated_mwh, "generated_mwh") potential = curtailed_mwh + generated_mwh return { "curtailed_over_generated_pct": ( 100 * curtailed_mwh / generated_mwh if generated_mwh else None ), "curtailed_over_potential_pct": 100 * curtailed_mwh / potential if potential else None, }
[docs] @dataclass(frozen=True) class EquivalentStorage: """Scenario A/B effective MW and the uncovered indicator relative to installed MW.""" scenario_a_mw: float scenario_b_mw: float outside_block_mwh: float block_fraction: float | None reduction_relative_to_a_pct: float | None excess_relative_to_b_pct: float | None uncovered_a_mw: float uncovered_b_mw: float
[docs] def equivalent_storage( curtailed_mwh: float, *, duration_hours: float = 4.0, days: float = 365.0, depth_of_discharge: float = 0.90, round_trip_efficiency: float = 0.95, block_mwh: float | None = None, installed_mw: float = 0.0, ) -> EquivalentStorage: """Evaluate EESC = UEC * DoD * efficiency / (days * discharge_hours). Matches the published numerator convention exactly. Lower DoD/efficiency therefore lowers this *effective* indicator; it must not be interpreted as the nominal capacity required to capture all curtailment. The uniform daily cycling assumption does not establish a feasible dispatch or an upper bound. Scenario B retains only curtailed energy in [08:00, 18:00) local time. """ for name, value in (("curtailed_mwh", curtailed_mwh), ("installed_mw", installed_mw)): _nonnegative(value, name) for name, value in (("duration_hours", duration_hours), ("days", days)): _nonnegative(value, name) if value == 0: raise ValueError(f"{name} must be positive") for value in (depth_of_discharge, round_trip_efficiency): if isinstance(value, bool) or not math.isfinite(value) or not 0 < value <= 1: raise ValueError("DoD and efficiency must lie in (0, 1]") block = curtailed_mwh if block_mwh is None else block_mwh _nonnegative(block, "block_mwh") if block > curtailed_mwh: raise ValueError("block_mwh cannot exceed total curtailment") factor = depth_of_discharge * round_trip_efficiency / (days * duration_hours) a, b = curtailed_mwh * factor, block * factor fraction = block / curtailed_mwh if curtailed_mwh else None return EquivalentStorage( a, b, curtailed_mwh - block, fraction, 100 * (1 - fraction) if fraction is not None else None, 100 * (a / b - 1) if b else None, max(a - installed_mw, 0.0), max(b - installed_mw, 0.0), )
[docs] def storage_sensitivity( curtailed_mwh: float, *, durations: Sequence[float] = (2, 3, 4, 5), depths: Sequence[float] = (0.80, 0.85, 0.90, 0.92, 0.95), efficiencies: Sequence[float] = (0.90, 0.93, 0.95, 0.97), days: float = 365, ) -> pd.DataFrame: """Paper section 4.4.1: 20 DoD/efficiency cases per duration.""" if not durations or not depths or not efficiencies: raise ValueError("Sensitivity axes must be nonempty") rows = [] for duration in durations: base = equivalent_storage(curtailed_mwh, duration_hours=duration, days=days).scenario_a_mw for depth in depths: for efficiency in efficiencies: value = equivalent_storage( curtailed_mwh, duration_hours=duration, days=days, depth_of_discharge=depth, round_trip_efficiency=efficiency, ).scenario_a_mw rows.append( { "duration_hours": duration, "depth_of_discharge": depth, "round_trip_efficiency": efficiency, "eesc_mw": value, "deviation_from_baseline_pct": 100 * (value / base - 1) if base else 0.0, } ) return pd.DataFrame(rows)
def _hourly_series(series: pd.Series, name: str, *, nonnegative: bool = True) -> None: if series.empty or not isinstance(series.index, pd.DatetimeIndex): raise ValueError(f"{name} needs a nonempty DatetimeIndex") if series.index.tz is None or series.index.hasnans or not series.index.is_unique: raise ValueError(f"{name} needs unique, timezone-aware timestamps") if not series.index.is_monotonic_increasing: raise ValueError(f"{name} timestamps must be sorted") if not np.isfinite(series.to_numpy(dtype=float)).all(): raise ValueError(f"{name} contains missing or non-finite observations") if nonnegative and (series < 0).any(): raise ValueError(f"{name} cannot contain negative energy") stamps = series.index.tz_convert("UTC") if ((stamps.minute != 0) | (stamps.second != 0) | (stamps.microsecond != 0)).any(): raise ValueError(f"{name} requires hourly interval starts")
[docs] def classify_curtailment( pv_mwh: pd.Series, wind_mwh: pd.Series, *, timezone: str = "America/Santiago" ) -> pd.DataFrame: """Table 1 P50 quadrants on paired observed hours, including zero observations. Ties are high (>= P50), including zero when the median is zero. Quantiles use linear interpolation. Missing or unpaired hours fail instead of being filled with zero. Gaps are allowed and remain gaps; coverage is not inferred. Southern-hemisphere seasons and A/B/C blocks use local interval STARTS. """ _hourly_series(pv_mwh, "pv_mwh") _hourly_series(wind_mwh, "wind_mwh") if not pv_mwh.index.equals(wind_mwh.index): raise ValueError("PV and wind require exactly paired hourly indexes") pv_p50, wind_p50 = float(pv_mwh.median()), float(wind_mwh.median()) pv_high, wind_high = pv_mwh >= pv_p50, wind_mwh >= wind_p50 local = pd.DatetimeIndex(pv_mwh.index).tz_convert(timezone) result = pd.DataFrame({"pv_mwh": pv_mwh, "wind_mwh": wind_mwh}) result["quadrant"] = np.select( [pv_high & wind_high, pv_high, wind_high], ["IV", "III", "II"], default="I" ) result["block"] = np.select([local.hour < 8, local.hour < 18], ["A", "B"], default="C") result["season"] = np.select( [local.month.isin([12, 1, 2]), local.month.isin([3, 4, 5]), local.month.isin([6, 7, 8])], ["summer", "fall", "winter"], default="spring", ) result.attrs.update(pv_p50_mwh=pv_p50, wind_p50_mwh=wind_p50, timezone=timezone) return result
[docs] def nodal_price_screen( first: pd.Series, second: pd.Series, *, threshold_usd_mwh: float = 10.0 ) -> pd.DataFrame: """Eq. (1): absolute price separation >= threshold, on exactly paired hours. Negative nodal prices are valid. This proxy cannot identify a causal line constraint or distinguish every driver of price separation. """ _hourly_series(first, "first price", nonnegative=False) _hourly_series(second, "second price", nonnegative=False) if not first.index.equals(second.index): raise ValueError("Nodal prices require exactly paired hourly indexes") _nonnegative(threshold_usd_mwh, "threshold_usd_mwh") if threshold_usd_mwh == 0: raise ValueError("threshold_usd_mwh must be positive") delta = (first - second).abs() return pd.DataFrame( { "absolute_spread_usd_mwh": delta, "price_separation_flag": delta >= threshold_usd_mwh, } )