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)