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