"""Annual wind-project pipeline flow with explicit stage-capacity bottlenecks.
Flows and queues are in GW of onshore nameplate power, not GWh. This is a
conditional accounting scenario, not a calibrated German construction forecast.
"""
from __future__ import annotations
import math
from collections.abc import Sequence
from dataclasses import dataclass
[docs]
@dataclass(frozen=True)
class WindPipelineYear:
"""Year-end stage inventory and flows, all in GW unless explicitly noted."""
year: int
newly_approved_gw: float
newly_awarded_gw: float
transported_gw: float
erected_gw: float
commissioned_gw: float
waiting_for_award_gw: float
waiting_for_transport_gw: float
waiting_for_erection_gw: float
waiting_for_grid_gw: float
cumulative_commissioned_gw: float
@property
def remaining_gw(self) -> float:
"""All approved-but-uncommissioned capacity, regardless of stage."""
return (
self.waiting_for_award_gw
+ self.waiting_for_transport_gw
+ self.waiting_for_erection_gw
+ self.waiting_for_grid_gw
)
def _check_nonnegative(name: str, value: float) -> None:
if (
isinstance(value, bool)
or not isinstance(value, (int, float))
or not math.isfinite(value)
or value < 0
):
raise ValueError(f"{name} must be finite and nonnegative (GW)")
[docs]
def simulate_wind_pipeline(
*,
first_year: int,
initial_unawarded_gw: float,
initial_awarded_gw: float,
new_approvals_gw: Sequence[float],
awards_per_year_gw: float,
transport_per_year_gw: float,
erection_per_year_gw: float,
grid_per_year_gw: float,
) -> tuple[WindPipelineYear, ...]:
"""Advance annual wind approvals through four finite-throughput stages.
Newly approved capacity first receives an auction award (or other eligibility),
then passes transport, turbine erection and final grid connection. Each stage
can process up to its annual GW limit; unprocessed GW waits in its stage.
All four stages may process the same project within a single model year,
an **optimistic zero-lag assumption**. No capacity is silently discarded.
``initial_awarded_gw`` is assumed ready for transport, **not yet shipped**.
This distinguishes the stock of already-awarded projects from the cohort
still awaiting an award. No equipment losses, cancellations, repowering or
stage-specific lead-time distributions are represented.
"""
if isinstance(first_year, bool) or not isinstance(first_year, int) or first_year < 1900:
raise ValueError("first_year must be an integer calendar year >= 1900")
if not new_approvals_gw:
raise ValueError("new_approvals_gw must contain at least one year")
for name, value in (
("initial_unawarded_gw", initial_unawarded_gw),
("initial_awarded_gw", initial_awarded_gw),
("awards_per_year_gw", awards_per_year_gw),
("transport_per_year_gw", transport_per_year_gw),
("erection_per_year_gw", erection_per_year_gw),
("grid_per_year_gw", grid_per_year_gw),
):
_check_nonnegative(name, value)
for idx, approved in enumerate(new_approvals_gw):
_check_nonnegative(f"new_approvals_gw[{idx}]", approved)
unawarded, transport, erection, grid = initial_unawarded_gw, initial_awarded_gw, 0.0, 0.0
cumulative = 0.0
rows = []
for offset, approval in enumerate(new_approvals_gw):
unawarded += approval
awarded = min(unawarded, awards_per_year_gw)
unawarded -= awarded
transport += awarded
transported = min(transport, transport_per_year_gw)
transport -= transported
erection += transported
erected = min(erection, erection_per_year_gw)
erection -= erected
grid += erected
commissioned = min(grid, grid_per_year_gw)
grid -= commissioned
cumulative += commissioned
rows.append(
WindPipelineYear(
year=first_year + offset,
newly_approved_gw=approval,
newly_awarded_gw=awarded,
transported_gw=transported,
erected_gw=erected,
commissioned_gw=commissioned,
waiting_for_award_gw=unawarded,
waiting_for_transport_gw=transport,
waiting_for_erection_gw=erection,
waiting_for_grid_gw=grid,
cumulative_commissioned_gw=cumulative,
)
)
return tuple(rows)