Source code for energy_methods.data_center_wind

"""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, )