Source code for energy_methods.storage_peak_shift
"""Auditable renewable-surplus-to-evening-peak battery dispatch.
This energy-balance screening method does not optimize prices, guarantee firm
capacity, or calculate storage obligations under any country's regulation.
"""
from __future__ import annotations
import math
from collections.abc import Sequence
from dataclasses import dataclass
[docs]
@dataclass(frozen=True)
class StorageStep:
"""Energy accounting for one timestep (all energy fields in MWh)."""
charged_input_mwh: float
delivered_mwh: float
curtailed_mwh: float
unmet_peak_mwh: float
soc_mwh: float
[docs]
@dataclass(frozen=True)
class StorageShiftResult:
"""Storage shift output with an audit-ready energy-balance trace."""
steps: tuple[StorageStep, ...]
peak_shortfall_mwh: float
peak_delivered_mwh: float
peak_coverage: float
curtailed_mwh: float
final_soc_mwh: float
[docs]
def simulate_storage_peak_shift(
surplus_mw: Sequence[float],
peak_shortfall_mw: Sequence[float],
*,
battery_power_mw: float,
battery_energy_mwh: float,
round_trip_efficiency: float = 0.9,
timestep_hours: float = 1.0,
initial_soc_mwh: float = 0.0,
) -> StorageShiftResult:
"""Charge only from renewable surplus and discharge only into peak shortfall.
``surplus_mw`` is renewable generation *remaining after serving contemporaneous
load*, not total PV generation. ``peak_shortfall_mw`` is the remaining
evening/peak demand to be covered by storage. Both must be nonnegative, and
cannot simultaneously be positive. The battery never charges from the grid.
A greedy sequential schedule is calculated without look-ahead. A single
symmetric charge/discharge efficiency sqrt(round_trip_efficiency) is used.
Storage energy capacity represents usable SOC range. Self-discharge,
degradation, grid export limits, operating reserves and costs are omitted.
"""
if len(surplus_mw) != len(peak_shortfall_mw) or not surplus_mw:
raise ValueError("Profiles must be nonempty and have identical lengths")
params = (battery_power_mw, battery_energy_mwh, initial_soc_mwh)
if any(not math.isfinite(x) or x < 0 for x in params):
raise ValueError("Power, energy and initial SOC must be finite and nonnegative")
if initial_soc_mwh > battery_energy_mwh:
raise ValueError("Initial SOC cannot exceed storage capacity")
if not math.isfinite(timestep_hours) or timestep_hours <= 0:
raise ValueError("Timestep must be finite and positive")
if not math.isfinite(round_trip_efficiency) or not 0 < round_trip_efficiency <= 1:
raise ValueError("Round-trip efficiency must be in (0, 1]")
for surplus, shortfall in zip(surplus_mw, peak_shortfall_mw, strict=True):
if (
not math.isfinite(surplus)
or not math.isfinite(shortfall)
or surplus < 0
or shortfall < 0
or (surplus > 0 and shortfall > 0)
):
raise ValueError("Profiles must be finite, nonnegative and mutually exclusive")
eta = math.sqrt(round_trip_efficiency)
soc = initial_soc_mwh
steps: list[StorageStep] = []
for surplus, shortfall in zip(surplus_mw, peak_shortfall_mw, strict=True):
incoming = surplus * timestep_hours
required = shortfall * timestep_hours
input_charge = min(
incoming,
battery_power_mw * timestep_hours,
(battery_energy_mwh - soc) / eta,
)
soc += input_charge * eta
delivered = min(required, battery_power_mw * timestep_hours, soc * eta)
soc -= delivered / eta
# Remove harmless floating point roundoff near zero and the SOC ceiling.
soc = min(battery_energy_mwh, max(0.0, soc))
steps.append(
StorageStep(
charged_input_mwh=input_charge,
delivered_mwh=delivered,
curtailed_mwh=incoming - input_charge,
unmet_peak_mwh=required - delivered,
soc_mwh=soc,
)
)
total_peak = sum(peak_shortfall_mw) * timestep_hours
total_delivered = sum(step.delivered_mwh for step in steps)
return StorageShiftResult(
steps=tuple(steps),
peak_shortfall_mwh=total_peak,
peak_delivered_mwh=total_delivered,
peak_coverage=total_delivered / total_peak if total_peak else 1.0,
curtailed_mwh=sum(step.curtailed_mwh for step in steps),
final_soc_mwh=soc,
)