"""PV-specific reliability evidence and reproducible, explicitly scoped cases."""
from __future__ import annotations
import argparse
import json
from pathlib import Path
from typing import Any, cast
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from energy_data_retrieval.pv_reliability_database import (
load_pv_reliability_evidence,
pv_reliability_sources,
)
from energy_methods.pv_device_reliability import assembly_event_scenario
from energy_methods.reliability_algorithms import repairable_availability
REFERENCE_IDS = (
"baschel_2018_reliability",
"lillo_2018_failures",
"bucher_2022_inverter_survival",
"martins_2026_tracker_availability",
"brown_2026_weather_station_longevity",
"deline_2026_pv_fleet",
)
[docs]
def published_rate_scenarios() -> pd.DataFrame:
"""Recalculate constant-rate scenarios, excluding internally conflicting rows.
Each row is a separate benchmark; alternative sources are never pooled.
Per-year values use the source's 4015 operating hours. Probabilities are
model-derived, not observed annual failure fractions or warranty estimates.
"""
data = load_pv_reliability_evidence(metric="failure_rate")
data = data.loc[data.quality_flags.map(len) == 0].copy()
data["model_events_per_year"] = data.value * data.operating_hours_per_year
data["model_probability_one_year"] = -np.expm1(-data.model_events_per_year)
data["model_mtbf_operating_years"] = 1 / data.model_events_per_year
return data.reset_index(drop=True)
[docs]
def combiner_box_case(*, boxes: int = 500) -> tuple[pd.DataFrame, dict[str, float]]:
"""Illustrative CBX bill of materials using disjoint, attributed part rates.
Twenty-four string fuses, 48 lugs, one SMU and one DC switch per box.
Not a reproduction of a particular OEM design, nor whole-box outage risk.
No tracker/WST proxy rates or assumed repair costs are inserted.
"""
if isinstance(boxes, bool) or not isinstance(boxes, int) or boxes <= 0:
raise ValueError("boxes must be a positive integer")
data = published_rate_scenarios().set_index("record_id")
keys = ["baschel_2018:t1-20", "baschel_2018:t1-10", "baschel_2018:t1-22", "baschel_2018:t1-23"]
parts = data.loc[keys, ["device", "value", "evidence_origin"]].reset_index()
parts["parts_per_box"] = [24, 48, 1, 1]
parts["events_per_box_year"] = parts.value * parts.parts_per_box * 4015
scenario = assembly_event_scenario(
parts.value.to_numpy(), parts.parts_per_box.to_numpy(), operating_hours_per_year=4015
)
scenario["boxes"] = boxes
scenario["fleet_expected_component_events_per_year"] = (
boxes * scenario["expected_events_per_year"]
)
return parts, scenario
[docs]
def repair_time_sensitivity() -> pd.DataFrame:
"""Synthetic 10 MW fleet: restoration sensitivity, not a site forecast.
Assumed constant calendar-up-time failure rate 0.04 per unit-year, with
exponential restoration. Counterfactual fleet output follows an artificial
12-hour sinusoidal day, repeated for 365 days. Identical unit availability
multiplies total fleet output in expectation; no shared crews/common cause.
Neither the rate, repair durations nor production profile is field evidence.
"""
hour = np.arange(8760) + 0.5
power = 10000 * np.maximum(0, np.sin((hour % 24 - 6) * np.pi / 12))
rows = []
for restore in [8, 24, 72, 168]:
model = repairable_availability(0.04 / 8760, restore, np.ones(8760), power)
rows.append(
dict(
mean_restore_hours=restore,
assumed_rate_per_unit_year=0.04,
mean_availability=float(model.mean_availability.mean()),
baseline_energy_mwh=float(model.baseline_energy_kwh.sum() / 1000),
expected_energy_loss_mwh=float(model.expected_energy_loss_kwh.sum() / 1000),
input_kind="synthetic_scenario",
)
)
return pd.DataFrame(rows)
[docs]
def plot_pv_reliability_evidence() -> plt.Figure:
"""Four panels with source-specific units; no universal device ranking."""
data = load_pv_reliability_evidence()
fig, axes = plt.subplots(2, 2, figsize=(14, 10), layout="constrained")
fig.suptitle("PV reliability: four different evidence types", fontsize=18, weight="bold")
ax = axes[0, 0]
rates = published_rate_scenarios()
names = [
"PV module",
"PV connector",
"String fuse",
"String monitoring unit",
"String inverter",
"Central inverter",
"DC capacitor",
"IGBT module",
"Central control board",
"Transformer",
]
rates = rates[rates.device.isin(names) & rates.selected_in_source.eq(True)].copy()
rates = rates.sort_values("value")
colors = rates.evidence_origin.map({"juwi_field": "#117b88", "cited_literature": "#bd6b2e"})
ax.barh(rates.device, rates.value * 1e6, color=colors)
ax.set_xscale("log")
ax.set_xlabel("Events per million operating hours (log scale)")
ax.set_title(
"Component rates • Baschel 2018\nTeal: field; orange: cited literature", fontsize=11
)
ax.grid(axis="x", alpha=0.2)
ax = axes[0, 1]
medians = data[(data.source_id == "martins_2026") & (data.statistic == "median")]
for i, mode in enumerate(["ALL", "CORE"]):
subset = medians[medians.method == mode].set_index("missing_data_assumption")
low = float(cast(float, subset.at["unavailable", "value"]))
high = float(cast(float, subset.at["available", "value"]))
ax.barh(i, low * 100, color="#117b88")
ax.barh(i, (high - low) * 100, left=low * 100, color="#c9dfe1", hatch="///")
ax.text(high * 100 + 1, i, f"{low:.0%}-{high:.0%}", va="center")
ax.set_yticks([0, 1], ["All tracking", "Core tracking"])
ax.set_xlim(0, 108)
ax.set_xlabel("Published median availability (%)")
ax.set_title(
"Tracker angle KPI • Martins 2026\nHatched span: missing-data assumptions, not a CI",
fontsize=11,
)
ax = axes[1, 0]
inv = data[data.source_id == "bucher_2022"].sort_values("age_years")
ax.scatter(inv.age_years, inv.value * 100, s=90, color="#117b88", zorder=3)
row = inv[inv.age_years == 18].iloc[0]
ax.errorbar(
[18],
[row.value * 100],
yerr=[[100 * (row.value - row.lower)], [100 * (row.upper - row.value)]],
fmt="none",
color="#117b88",
capsize=7,
)
for _, row in inv.iterrows():
ax.annotate(
f"{row.value:.1%}",
(row.age_years, row.value * 100),
xytext=(8, 8),
textcoords="offset points",
)
ax.set(xlim=(13, 20), ylim=(45, 80), xlabel="Age (years)", ylabel="First-event survival (%)")
ax.set_title(
"Inverter survival • Bucher 2022\n2,121 units; only 15 at risk at year 18", fontsize=11
)
ax.grid(alpha=0.2)
ax = axes[1, 1]
stations = data[data.metric == "individual_observed_age"].sort_values("value")
for i, (_, row) in enumerate(stations.iterrows()):
marker = {"event": "x", "right_censored": ">", "event_age_lower_bound": ">"}[
row.observation_status
]
color = "#bd6b2e" if row.observation_status == "event" else "#117b88"
ax.scatter(row.value, i, marker=marker, s=65, color=color)
ax.set_yticks(range(len(stations)), stations.device + " / " + stations.unit_id)
ax.set(xlim=(0, 15), xlabel="Observed years; x stopped, > follow-up / lower bound")
ax.set_title(
"Unmaintained WSTs • Brown 2026\nIndividual cases; unit-count inconsistency flagged",
fontsize=11,
)
ax.grid(axis="x", alpha=0.2)
return fig
[docs]
def run_study(output: Path) -> dict[str, Any]:
"""Export typed source evidence and the CBX case, without network calls."""
output.mkdir(parents=True, exist_ok=True)
evidence = load_pv_reliability_evidence()
sources = pv_reliability_sources()
rates = published_rate_scenarios()
parts, scenario = combiner_box_case()
repair = repair_time_sensitivity()
evidence.to_parquet(output / "pv_reliability_evidence.parquet", index=False)
evidence.to_json(output / "pv_reliability_evidence.json", orient="records", indent=2)
sources.to_json(output / "sources.json", orient="records", indent=2)
rates.to_csv(output / "component_rate_scenarios.csv", index=False)
evidence[evidence.quality_flags.map(len) > 0].to_json(
output / "quality_audit.json", orient="records", indent=2
)
parts.to_csv(output / "combiner_parts.csv", index=False)
repair.to_csv(output / "synthetic_repair_sensitivity.csv", index=False)
summary = {
"sources_reviewed": len(sources),
"evidence_records": len(evidence),
"metric_counts": evidence.metric.value_counts().to_dict(),
"unflagged_rate_alternatives": len(rates),
"combiner_case": scenario,
"synthetic_repair_sensitivity": repair.to_dict(orient="records"),
"interpretation": "Historical benchmarks and explicit assumptions; not OEM predictions.",
}
(output / "summary.json").write_text(json.dumps(summary, indent=2) + "\n")
figure = plot_pv_reliability_evidence()
figure.savefig(output / "pv_reliability_evidence.png", dpi=160)
plt.close(figure)
return summary
[docs]
def main() -> None:
"""Run with ``python -m energy_analysis.pv_device_reliability``."""
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--output", type=Path, default=Path("artifacts/pv-device-reliability"))
print(json.dumps(run_study(parser.parse_args().output), indent=2))
if __name__ == "__main__":
main()