Source code for energy_methods.portugal_storage_auction

"""First-pass MVA-to-MW and four-hour BESS screens for Portugal's 2026 auctions.

This is an illustrative engineering calculator, NOT a legal qualification,
grid feasibility study, financing model, or prediction of auction outcomes.
"""

from __future__ import annotations

import math
from dataclasses import dataclass
from typing import Literal

AuctionType = Literal["standalone", "colocated"]
# DGEG's 22 October 2026 orders 12924-C and 12924-B, respectively.
AUCTION_CAPACITY_MVA: dict[AuctionType, float] = {
    "standalone": 750.0,
    "colocated": 300.0,
}
MINIMUM_BID_MVA = 50.0
MINIMUM_DURATION_HOURS = 4.0


[docs] @dataclass(frozen=True, slots=True) class StorageAuctionScenario: """Engineering assumptions; none represents an awarded or measured project. MVA is awarded apparent injection access, not installed active power. Efficiencies and usable fraction are independently assumed design values. """ auction: AuctionType awarded_capacity_mva: float active_power_factor: float = 1.0 ac_discharge_efficiency: float = 0.94 end_of_life_usable_fraction: float = 0.80
[docs] @dataclass(frozen=True, slots=True) class StorageAuctionScreen: """Power and energy envelopes, not final tender eligibility.""" auction: AuctionType awarded_capacity_mva: float export_active_mw: float minimum_bess_ac_mw: float minimum_delivered_mwh: float minimum_nameplate_mwh: float full_export_four_hour_delivered_mwh: float full_export_four_hour_nameplate_mwh: float within_aggregate_auction_pool: bool
[docs] def screen_portugal_storage_auction(scenario: StorageAuctionScenario) -> StorageAuctionScreen: """Evaluate a conditional four-hour battery power and energy envelope. Standalone power fraction: 100% of injection MW. Co-located: 20% as preliminary power screening. DGEG's co-located notice says four hours at MAXIMUM INJECTION power; a separate full-export four-hour stress is therefore required. Neither interpretation independently proves legal compliance; read the binding tender programme and specifications. Assumes P_export(MW) = S_awarded(MVA) * assumed power factor. Battery nameplate energy = delivered AC energy / (discharge efficiency * assumed usable nameplate fraction at end of life). """ if scenario.auction not in AUCTION_CAPACITY_MVA: raise ValueError("auction must be 'standalone' or 'colocated'") fields = ( "awarded_capacity_mva", "active_power_factor", "ac_discharge_efficiency", "end_of_life_usable_fraction", ) for name in fields: value = getattr(scenario, name) if isinstance(value, bool) or not isinstance(value, (int, float)): raise ValueError(f"{name} must be numeric") if not math.isfinite(value): raise ValueError(f"{name} must be finite") if scenario.awarded_capacity_mva < MINIMUM_BID_MVA: raise ValueError(f"Candidate bid must be at least {MINIMUM_BID_MVA:g} MVA") for name in fields[1:]: value = getattr(scenario, name) if not 0 < value <= 1: raise ValueError(f"{name} must lie in (0, 1]") export_mw = scenario.awarded_capacity_mva * scenario.active_power_factor bess_mw = export_mw * (1.0 if scenario.auction == "standalone" else 0.2) minimum_delivered = MINIMUM_DURATION_HOURS * bess_mw full_export_delivered = MINIMUM_DURATION_HOURS * export_mw available_fraction = scenario.ac_discharge_efficiency * scenario.end_of_life_usable_fraction return StorageAuctionScreen( auction=scenario.auction, awarded_capacity_mva=scenario.awarded_capacity_mva, export_active_mw=export_mw, minimum_bess_ac_mw=bess_mw, minimum_delivered_mwh=minimum_delivered, minimum_nameplate_mwh=minimum_delivered / available_fraction, full_export_four_hour_delivered_mwh=full_export_delivered, full_export_four_hour_nameplate_mwh=full_export_delivered / available_fraction, within_aggregate_auction_pool=( scenario.awarded_capacity_mva <= AUCTION_CAPACITY_MVA[scenario.auction] ), )