Source code for energy_methods.bess_merchant_finance
"""Transparent BESS arbitrage contribution and debt-cover screening.
All prices, degradation and loan terms are hypothetical user inputs.
This tool does not optimize dispatch or forecast electricity prices.
"""
from __future__ import annotations
import math
from dataclasses import dataclass
[docs]
@dataclass(frozen=True)
class BatteryTradingScenario:
"""Merchant operation assumptions, not measured performance.
``grid_charge_mwh_per_cycle`` is grid energy purchased for one full
equivalent charge. Delivered MWh include round-trip conversion losses.
``captured_margin_eur_per_mwh`` must be net of grid energy purchases and
market transaction fees; it is NOT an electricity sale price.
"""
grid_charge_mwh_per_cycle: float
equivalent_cycles_per_day: float
round_trip_efficiency: float
availability: float
annual_capacity_retention: float
captured_margin_eur_per_mwh: float
[docs]
@dataclass(frozen=True)
class BatteryFinanceScenario:
"""Illustrative debt and fixed O&M assumptions, all nominal EUR."""
senior_debt_eur: float
annual_interest_rate: float
debt_tenor_years: int
annual_fixed_opex_eur: float
[docs]
@dataclass(frozen=True)
class AnnualBatteryCashflow:
"""One projected year of physical output and simple merchant cashflow."""
year_index: int
discharged_mwh: float
contribution_eur: float
fixed_opex_eur: float
debt_service_eur: float
cash_available_for_debt_eur: float
cash_after_debt_eur: float
cash_cover_ratio: float | None
def _finite_nonnegative(value: float, label: str) -> None:
if not math.isfinite(value) or value < 0:
raise ValueError(f"{label} must be finite and nonnegative")
def _validate_trading(scenario: BatteryTradingScenario) -> None:
_finite_nonnegative(scenario.grid_charge_mwh_per_cycle, "grid_charge_mwh_per_cycle")
_finite_nonnegative(scenario.equivalent_cycles_per_day, "equivalent_cycles_per_day")
_finite_nonnegative(scenario.captured_margin_eur_per_mwh, "captured_margin_eur_per_mwh")
if not 0 < scenario.round_trip_efficiency <= 1 or not math.isfinite(
scenario.round_trip_efficiency
):
raise ValueError("round_trip_efficiency must be finite and in (0, 1]")
if not 0 <= scenario.availability <= 1 or not math.isfinite(scenario.availability):
raise ValueError("availability must be finite and in [0, 1]")
if not 0 < scenario.annual_capacity_retention <= 1 or not math.isfinite(
scenario.annual_capacity_retention
):
raise ValueError("annual_capacity_retention must be finite and in (0, 1]")
def _validate_finance(scenario: BatteryFinanceScenario) -> None:
_finite_nonnegative(scenario.senior_debt_eur, "senior_debt_eur")
_finite_nonnegative(scenario.annual_fixed_opex_eur, "annual_fixed_opex_eur")
if (
not math.isfinite(scenario.annual_interest_rate)
or not 0 <= scenario.annual_interest_rate < 1
):
raise ValueError("annual_interest_rate must be finite and in [0, 1)")
if not isinstance(scenario.debt_tenor_years, int) or not 1 <= scenario.debt_tenor_years <= 100:
raise ValueError("debt_tenor_years must be an integer in [1, 100]")
[docs]
def discharged_energy_mwh(scenario: BatteryTradingScenario, year_index: int) -> float:
"""Annual AC discharge, with 365 days/year (leap-day simplification).
No cycle-calendar, power, state-of-charge, degradation-mechanism, or
warranty feasibility has been independently validated here.
"""
_validate_trading(scenario)
if not isinstance(year_index, int) or year_index < 0:
raise ValueError("year_index must be a nonnegative integer")
return (
365.0
* scenario.grid_charge_mwh_per_cycle
* scenario.equivalent_cycles_per_day
* scenario.round_trip_efficiency
* scenario.availability
* scenario.annual_capacity_retention**year_index
)
[docs]
def required_captured_margin_eur_per_mwh(
target_contribution_eur: float,
trading: BatteryTradingScenario,
years: int,
) -> float:
"""Uniform net margin for a stipulated cumulative pre-O&M contribution.
A published *revenue* forecast need not equal this net margin because its
charging purchases, grid fees and revenue recognition may differ.
"""
_finite_nonnegative(target_contribution_eur, "target_contribution_eur")
if not isinstance(years, int) or years < 1:
raise ValueError("years must be a positive integer")
delivered = sum(discharged_energy_mwh(trading, y) for y in range(years))
if delivered <= 0:
raise ValueError("Positive annual discharge is required to infer a captured margin")
return target_contribution_eur / delivered
[docs]
def annual_level_debt_service_eur(finance: BatteryFinanceScenario) -> float:
"""12 times a level monthly repayment; not an actual bank loan schedule."""
_validate_finance(finance)
principal = finance.senior_debt_eur
if principal == 0:
return 0.0
months = finance.debt_tenor_years * 12
monthly_rate = finance.annual_interest_rate / 12
if monthly_rate == 0:
return principal / finance.debt_tenor_years
monthly_payment = principal * monthly_rate / (-math.expm1(-months * math.log1p(monthly_rate)))
return 12 * monthly_payment
[docs]
def merchant_cashflow_screen(
trading: BatteryTradingScenario,
finance: BatteryFinanceScenario,
years: int,
) -> tuple[AnnualBatteryCashflow, ...]:
"""Screen yearly cash before taxes/working capital and actual debt covenants.
``cash_cover_ratio`` is illustrative cash / assumed debt payment; it is
NOT an independently verified bank debt-service coverage ratio (DSCR).
"""
_validate_trading(trading)
_validate_finance(finance)
if not isinstance(years, int) or years < 1:
raise ValueError("years must be a positive integer")
annual_payment = annual_level_debt_service_eur(finance)
output: list[AnnualBatteryCashflow] = []
for year_index in range(years):
discharged = discharged_energy_mwh(trading, year_index)
contribution = discharged * trading.captured_margin_eur_per_mwh
cash_for_debt = contribution - finance.annual_fixed_opex_eur
debt_payment = annual_payment if year_index < finance.debt_tenor_years else 0.0
output.append(
AnnualBatteryCashflow(
year_index=year_index,
discharged_mwh=discharged,
contribution_eur=contribution,
fixed_opex_eur=finance.annual_fixed_opex_eur,
debt_service_eur=debt_payment,
cash_available_for_debt_eur=cash_for_debt,
cash_after_debt_eur=cash_for_debt - debt_payment,
cash_cover_ratio=(cash_for_debt / debt_payment if debt_payment > 0 else None),
)
)
return tuple(output)