Source code for energy_analysis.pvdeg_mechanisms

"""Canary hourly-weather mechanism atlas; no spatial interpolation."""

from __future__ import annotations

import hashlib
import json
from pathlib import Path
from typing import Any

import numpy as np
import pandas as pd

from energy_data_retrieval.pvdeg import to_pvdeg_weather
from energy_methods.pvdeg_mechanisms import relative_arrhenius_exposure

REFERENCE_IDS = ("pvdeg_software", "pvgis_5_api")
METRICS = {
    "thermal": ("Thermal exposure", "Relative exposure", "magma"),
    "damp_heat": ("Damp-heat / hydrolysis stress", "Relative exposure (n=1)", "YlGnBu"),
    "photothermal": ("Broadband light + heat stress", "Relative exposure (p=1); not UV", "inferno"),
    "combined": ("Light + moisture + heat stress", "Relative exposure (n=p=1)", "plasma"),
    "surface_rh": ("Module surface moisture", "Mean RH (%)", "Blues"),
    "front_rh": ("Front encapsulant moisture", "Mean RH (%), EVA W001", "Blues"),
    "back_rh": ("Back encapsulant moisture", "Mean RH (%), EVA / PET", "Blues"),
    "backsheet_rh": ("Backsheet moisture", "Mean RH (%), PET W017", "Blues"),
    "solder_fatigue": ("Solder fatigue", "PVDeg damage metric (kPa)", "cividis"),
}


[docs] def analyze_weather(weather: pd.DataFrame, location: dict[str, Any]) -> dict[str, float]: """Run nine PVDeg stress/material metrics for a complete 8760-hour TMY. Fixed 28-degree south-facing, open-rack glass/polymer module; SAPM temperature with 10 m wind. Surface RH is capped at saturation for the stress calculation; moisture-model RH is retained as returned. PVDeg's EVA/PET defaults and initial moisture state are scenarios, not fitted Canary module properties. """ from pvdeg import fatigue, humidity, spectral from pvlib import solarposition, temperature weather = to_pvdeg_weather(weather) expected = pd.date_range("2023-01-01", periods=8760, freq="h", tz="UTC") if not weather.index.equals(expected): raise ValueError("Expected complete 2023 calendar axis for the modeled TMY") lat, lon = float(location["latitude"]), float(location["longitude"]) altitude = float(location["elevation"]) offset = float(location["irradiance_time_offset"]) if not np.isfinite([lat, lon, altitude, offset]).all() or not -1 <= offset <= 1: raise ValueError("Invalid location or irradiance time offset") if not -90 <= lat <= 90 or not -180 <= lon <= 180: raise ValueError("Invalid coordinates") # PVGIS irradiance applies at an offset from each hourly weather timestamp. sun = solarposition.get_solarposition( weather.index + pd.Timedelta(hours=offset), lat, lon, altitude=altitude ) sun.index = weather.index meta = {"latitude": lat, "longitude": lon, "altitude": altitude, "tz": "UTC"} poa = spectral.poa_irradiance( weather, meta, sol_position=sun, surface_tilt=28, surface_azimuth=180, albedo=0.25, sky_model="isotropic", ) irradiance = poa["poa_global"] parameters = temperature.TEMPERATURE_MODEL_PARAMETERS["sapm"]["open_rack_glass_polymer"] module = temperature.sapm_module( irradiance, weather.temp_air, weather.wind_speed, a=parameters["a"], b=parameters["b"], ) cell = temperature.sapm_cell_from_module(module, irradiance, parameters["deltaT"]) moisture = humidity.module( weather, meta, poa=poa, temp_module=module, backsheet_thickness=0.3, back_encap_thickness=0.46, ) if not np.isfinite(moisture.to_numpy()).all(): raise ValueError("PVDeg returned nonfinite moisture results") surface = moisture.RH_surface_outside.clip(upper=100) results = {} for name, n, p in [ ("thermal", 0, 0), ("damp_heat", 1, 0), ("photothermal", 0, 1), ("combined", 1, 1), ]: results[name] = relative_arrhenius_exposure( module, surface, irradiance, humidity_exponent=n, irradiance_exponent=p, ) for name, column in [ ("surface_rh", "RH_surface_outside"), ("front_rh", "RH_front_encap"), ("back_rh", "RH_back_encap"), ("backsheet_rh", "RH_backsheet"), ]: results[name] = float(moisture[column].mean()) # Fixed UTC days for a reproducible TMY comparison; no DST shifts. results["solder_fatigue"] = float(fatigue.solder_fatigue(weather, meta, temp_cell=cell)) if not np.isfinite(list(results.values())).all(): raise ValueError("PVDeg returned nonfinite mechanism metrics") return results
[docs] def analyze_manifest(directory: Path) -> pd.DataFrame: """Verify fixture hashes and recompute each site's metrics offline.""" manifest = json.loads((directory / "manifest.json").read_text()) rows = [] for site in manifest["sites"]: path = directory / site["file"] if hashlib.sha256(path.read_bytes()).hexdigest() != site["sha256"]: raise ValueError(f"Weather fixture differs from provenance: {path.name}") frame = pd.read_csv(path, index_col="time") frame.index = pd.to_datetime(frame.index, utc=True) location = site["inputs"]["location"] rows.append( { "name": site["name"], "longitude": location["longitude"], "latitude": location["latitude"], **analyze_weather(frame, location), } ) return pd.DataFrame(rows)