Source code for energy_methods.margin_relief
"""Conditional BESS energy/power screen for forecast reserve-margin gaps.
A margin gap is NOT unserved electricity demand. The integral of forecast
margin-gap MW over time is only a hypothetical reserve-support requirement.
"""
from __future__ import annotations
import math
from collections.abc import Sequence
from dataclasses import dataclass
[docs]
@dataclass(frozen=True)
class MarginRelief:
"""Conditional capacity-margin screening outputs, not electricity shortages."""
margin_gap_mwh_equivalent: float
relief_mwh_equivalent: float
remaining_gap_mwh_equivalent: float
coverage_fraction: float
relief_mw: tuple[float, ...]
remaining_dc_energy_mwh: float
[docs]
def screen_margin_relief(
margin_gap_mw: Sequence[float],
*,
battery_power_mw: float,
available_dc_energy_mwh: float,
timestep_hours: float = 0.5,
discharge_efficiency: float = 0.95,
) -> MarginRelief:
"""Bound hypothetical storage relief using inverter power and finite energy.
Each input is a *scenario* MW gap averaged across an interval; reporting a
snapshot at one instant does not establish an observed interval series.
The battery starts with the specified usable DC energy above minimum SOC,
supplies only reserve support, and never recharges within this screen.
Calculated MWh are *margin-gap equivalents*, not lost-load measurements.
"""
for name, value in (
("battery_power_mw", battery_power_mw),
("available_dc_energy_mwh", available_dc_energy_mwh),
("timestep_hours", timestep_hours),
("discharge_efficiency", discharge_efficiency),
):
if isinstance(value, bool) or not math.isfinite(value):
raise ValueError(f"{name} must be a finite number")
if battery_power_mw < 0 or available_dc_energy_mwh < 0:
raise ValueError("Battery power and available energy must be nonnegative")
if timestep_hours <= 0 or not 0 < discharge_efficiency <= 1:
raise ValueError("Timestep must be positive; discharge efficiency in (0, 1]")
if not margin_gap_mw:
raise ValueError("Provide at least one interval")
if any(isinstance(mw, bool) or not math.isfinite(mw) or mw < 0 for mw in margin_gap_mw):
raise ValueError("Each margin gap must be finite and nonnegative")
dc_remaining = available_dc_energy_mwh
support: list[float] = []
for gap_mw in margin_gap_mw:
output_mw = min(
gap_mw,
battery_power_mw,
dc_remaining * discharge_efficiency / timestep_hours,
)
support.append(output_mw)
dc_remaining = max(0.0, dc_remaining - output_mw * timestep_hours / discharge_efficiency)
original = sum(margin_gap_mw) * timestep_hours
closed = sum(support) * timestep_hours
return MarginRelief(
margin_gap_mwh_equivalent=original,
relief_mwh_equivalent=closed,
remaining_gap_mwh_equivalent=max(0.0, original - closed),
coverage_fraction=closed / original if original > 0 else 1.0,
relief_mw=tuple(support),
remaining_dc_energy_mwh=dc_remaining,
)