Source code for energy_methods.bess_service_envelope
"""Constant-power BESS service screening with explicit energy and AC limits.
This screening method is not a dispatch optimizer or grid service certification.
"""
from __future__ import annotations
import math
from dataclasses import dataclass
[docs]
@dataclass(frozen=True)
class ServiceEnvelope:
"""Constant-power limits over a specified service window, in MW and MWh."""
available_ac_energy_mwh: float
power_limit_mw: float
energy_limited_power_mw: float
sustainable_power_mw: float
delivered_at_target_mwh: float
target_power_mw: float
meets_target: bool
limiting_constraint: str
[docs]
def screen_bess_service(
power_mw: float,
declared_energy_mwh: float,
service_hours: float,
*,
target_power_mw: float = 0.0,
initial_soc_fraction: float = 1.0,
reserve_soc_fraction: float = 0.0,
usable_capacity_fraction: float = 1.0,
discharge_efficiency: float = 1.0,
) -> ServiceEnvelope:
"""Screen constant AC power deliverable without recharging the battery.
``declared_energy_mwh`` is a caller-defined energy basis. Apply
``discharge_efficiency`` only if that energy is upstream of AC export;
if the declared MWh is already AC deliverable, set efficiency to 1.
SOC fractions refer to the ``usable_capacity_fraction`` energy basis.
The final reserve is intentionally unavailable for the service.
This is a deterministic physical upper bound: no auxiliary consumption,
dynamic inverter derating, degradation within the event or grid constraints.
"""
inputs = (
power_mw,
declared_energy_mwh,
service_hours,
target_power_mw,
initial_soc_fraction,
reserve_soc_fraction,
usable_capacity_fraction,
discharge_efficiency,
)
if any(not math.isfinite(value) for value in inputs):
raise ValueError("All inputs must be finite")
if power_mw < 0 or declared_energy_mwh < 0 or target_power_mw < 0:
raise ValueError("Power and energy values must be nonnegative")
if service_hours <= 0:
raise ValueError("Service hours must be positive")
if not (0 <= reserve_soc_fraction <= initial_soc_fraction <= 1):
raise ValueError("SOC fractions must satisfy 0 <= reserve <= initial <= 1")
if not (0 <= usable_capacity_fraction <= 1):
raise ValueError("Usable capacity fraction must be in [0, 1]")
if not (0 < discharge_efficiency <= 1):
raise ValueError("Discharge efficiency must be in (0, 1]")
energy = (
declared_energy_mwh
* usable_capacity_fraction
* (initial_soc_fraction - reserve_soc_fraction)
* discharge_efficiency
)
energy_power = energy / service_hours
sustainable = min(power_mw, energy_power)
delivered = min(target_power_mw, sustainable) * service_hours
tolerance = 1e-12 * max(1.0, target_power_mw, sustainable)
limiting = "energy" if energy_power < power_mw else "power"
return ServiceEnvelope(
available_ac_energy_mwh=energy,
power_limit_mw=power_mw,
energy_limited_power_mw=energy_power,
sustainable_power_mw=sustainable,
delivered_at_target_mwh=delivered,
target_power_mw=target_power_mw,
meets_target=target_power_mw <= sustainable + tolerance,
limiting_constraint=limiting,
)
[docs]
def maximum_households(envelope: ServiceEnvelope, mean_household_kw: float) -> int:
"""Household *energy equivalence* for a hypothetical constant average load.
This is NOT households served during a coincident peak, firm grid supply,
or a claim that a physical connection to these households exists.
"""
if not math.isfinite(mean_household_kw) or mean_household_kw <= 0:
raise ValueError("Mean household load must be finite and positive")
return math.floor(1000.0 * envelope.sustainable_power_mw / mean_household_kw)