Source code for energy_methods.pv_operation
"""Annual PV operation scenarios with independent, repairable component failures.
A Bernoulli event per component and year represents at most one replacement.
Failure timing is represented by a caller-supplied fractional annual outage.
These are explicit engineering scenarios, not calibrated field failure models.
"""
from dataclasses import dataclass
import numpy as np
import pandas as pd
from energy_methods.pv_reliability import ReliabilityCurve
[docs]
@dataclass(frozen=True)
class ComponentScenario:
"""Annual failure probability, outage fraction and constant-real replacement cost.
Replacements restore service but do not reset module degradation. Cost is
in the caller's declared currency. Failures are independent across years,
components and simulated plants. Multiple same-year failures are excluded.
"""
name: str
annual_failure_probability: float
outage_fraction: float
replacement_cost: float
def __post_init__(self) -> None:
values = [self.annual_failure_probability, self.outage_fraction, self.replacement_cost]
if not self.name.strip() or not np.isfinite(values).all():
raise ValueError("A component name and finite parameters are required")
if not 0 <= self.annual_failure_probability <= 1 or not 0 <= self.outage_fraction <= 1:
raise ValueError("Probability and outage fraction must be in [0, 1]")
if self.replacement_cost < 0:
raise ValueError("Replacement cost must be nonnegative")
[docs]
def simulate_operation(
*,
curve: ReliabilityCurve,
initial_annual_energy_mwh: float,
components: tuple[ComponentScenario, ...],
years: int = 50,
trials: int = 1000,
seed: int = 0,
) -> pd.DataFrame:
"""Return one row per trial/year, using midpoint annual power retention.
Concurrent component outages are conservatively added and capped at one
year. No repair queue, seasonality, weather variability or cost discounting
is modeled. ``original_components_survive`` concerns the original set,
while replacement permits subsequent operation. Cumulative quantities are
computed independently for each trial. Zero energy is valid.
"""
if any(isinstance(v, bool) or not isinstance(v, int) or v < 1 for v in (years, trials)):
raise ValueError("years and trials must be positive integers")
if not np.isfinite(initial_annual_energy_mwh) or initial_annual_energy_mwh < 0:
raise ValueError("initial_annual_energy_mwh must be finite and nonnegative")
if len({c.name for c in components}) != len(components):
raise ValueError("Component names must be unique")
retention = curve.power(np.arange(years) + 0.5)
if np.any((retention < 0) | (retention > 1)):
raise ValueError("Power retention must stay in [0, 1] throughout the horizon")
rng = np.random.default_rng(seed)
outages = np.zeros((trials, years))
costs = np.zeros_like(outages)
counts = np.zeros_like(outages, dtype=int)
for component in components:
events = rng.random((trials, years)) < component.annual_failure_probability
outages += events * component.outage_fraction
costs += events * component.replacement_cost
counts += events
availability = 1 - np.minimum(outages, 1)
energy = initial_annual_energy_mwh * retention * availability
cumulative_counts = np.cumsum(counts, axis=1)
return pd.DataFrame(
{
"trial": np.repeat(np.arange(trials), years),
"year": np.tile(np.arange(1, years + 1), trials),
"energy_mwh": energy.ravel(),
"availability": availability.ravel(),
"replacement_count": counts.ravel(),
"replacement_cost": costs.ravel(),
"cumulative_energy_mwh": np.cumsum(energy, axis=1).ravel(),
"cumulative_replacement_cost": np.cumsum(costs, axis=1).ravel(),
"original_components_survive": (cumulative_counts == 0).ravel(),
}
)