"""Annual wind procurement and hourly-matching screens for electricity buyers.
Annual energy matching is *not* evidence of 24/7 hourly clean supply.
The hourly method consumes explicit profiles and reuses hybrid_dispatch.
"""
from __future__ import annotations
import math
from collections.abc import Sequence
from dataclasses import dataclass
from energy_methods.hybrid_dispatch import simulate_hybrid
HOURS_PER_YEAR = 8760
[docs]
@dataclass(frozen=True, slots=True)
class AnnualWindScreen:
"""Required GW and annual delivered TWh for an annual energy target."""
target_twh: float
required_wind_gw: float
annual_delivered_twh: float
[docs]
@dataclass(frozen=True, slots=True)
class HourlyWindScreen:
"""Finite sample-window energy and temporal coverage, not grid availability."""
energy_matched_fraction: float
hourly_served_fraction: float
delivered_wind_mwh: float
demand_mwh: float
curtailed_mwh: float
unmet_mwh: float
[docs]
def screen_annual_wind(
demand_twh: float,
target_fraction: float,
capacity_factor: float,
delivery_loss_fraction: float = 0.0,
*,
hours_per_year: int = HOURS_PER_YEAR,
) -> AnnualWindScreen:
"""Size nameplate GW to equal a fraction of demand on an **annual MWh** basis.
Assumes constant net capacity factor and constant delivery losses; excludes
congestion, interconnection queues, profile correlation, PPA settlement,
construction lead times and additionality. A target fraction of zero gives
zero capacity. Does not make a firm-power or hourly-matching claim.
"""
values = (demand_twh, target_fraction, capacity_factor, delivery_loss_fraction)
if not all(math.isfinite(v) for v in values):
raise ValueError("All annual scenario inputs must be finite")
if demand_twh <= 0 or not 0 <= target_fraction <= 1:
raise ValueError("Demand must be positive and target fraction in [0, 1]")
if not 0 < capacity_factor <= 1 or not 0 <= delivery_loss_fraction < 1:
raise ValueError("Capacity factor and delivery losses outside physical bounds")
if type(hours_per_year) is not int or hours_per_year <= 0:
raise ValueError("hours_per_year must be a positive integer")
target_twh = demand_twh * target_fraction
nameplate_gw = (
target_twh * 1000 / (hours_per_year * capacity_factor * (1 - delivery_loss_fraction))
)
return AnnualWindScreen(
target_twh=target_twh,
required_wind_gw=nameplate_gw,
annual_delivered_twh=nameplate_gw
* hours_per_year
* capacity_factor
* (1 - delivery_loss_fraction)
/ 1000,
)
[docs]
def screen_hourly_wind(
wind_cf: Sequence[float],
demand_mw: Sequence[float],
*,
wind_capacity_mw: float,
delivery_loss_fraction: float = 0.0,
battery_power_mw: float = 0.0,
battery_energy_mwh: float = 0.0,
battery_round_trip_efficiency: float = 0.9,
timestep_hours: float = 1.0,
) -> HourlyWindScreen:
"""Contrast total-window MWh matching with physical hourly served share.
wind_cf is an explicit site/profile-level fraction in [0, 1].
Storage starts empty, may charge only from excess wind, and does not import
grid electricity. Greedy dispatch does not optimize economics. Energy
matching assumes all generated MWh can be credited over the same window,
**even if** it is spilled at the load site; it is a deliberately permissive
contract accounting ceiling, not a certified procurement or dispatch claim.
"""
if not wind_cf or len(wind_cf) != len(demand_mw):
raise ValueError("Equal nonempty capacity-factor and demand arrays required")
if not math.isfinite(wind_capacity_mw) or wind_capacity_mw < 0:
raise ValueError("Wind nameplate MW must be finite and nonnegative")
if not math.isfinite(delivery_loss_fraction) or not 0 <= delivery_loss_fraction < 1:
raise ValueError("Delivery losses must be in [0, 1)")
if any(not math.isfinite(cf) or not 0 <= cf <= 1 for cf in wind_cf):
raise ValueError("Wind capacity factors must be finite and in [0, 1]")
if any(not math.isfinite(load) or load < 0 for load in demand_mw):
raise ValueError("Demand MW must be finite and nonnegative")
generation = [wind_capacity_mw * cf * (1 - delivery_loss_fraction) for cf in wind_cf]
demand_mwh = sum(demand_mw) * timestep_hours
delivered_mwh = sum(generation) * timestep_hours
balance = simulate_hybrid(
generation,
[0.0] * len(generation),
demand_mw,
battery_mwh=battery_energy_mwh,
battery_mw=battery_power_mw,
efficiency=battery_round_trip_efficiency,
timestep_hours=timestep_hours,
)
return HourlyWindScreen(
energy_matched_fraction=min(delivered_mwh / demand_mwh, 1.0) if demand_mwh > 0 else 1.0,
hourly_served_fraction=balance.coverage,
delivered_wind_mwh=delivered_mwh,
demand_mwh=demand_mwh,
curtailed_mwh=balance.curtailed_mwh,
unmet_mwh=balance.unserved_mwh,
)