"""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,
}
)