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)