Source code for energy_methods.degradation_mapping

"""Annual stress processing and geographic degradation maps with explicit assumptions."""

from __future__ import annotations

import json
from itertools import pairwise
from typing import Literal

import numpy as np
import pandas as pd
import xarray as xr

from energy_methods.degradation import REFERENCE_IDS, DegradationParameters, degradation_rates
from energy_methods.kgpv import ZONE_CODES
from energy_methods.mapping import cell_areas_km2, normalize_grid

STRESS_UNITS = {
    "module_temperature_mean_c": "degC",
    "module_temperature_upper_c": "degC",
    "module_temperature_lower_c": "degC",
    "relative_humidity_percent": "%",
    "uv_dose_kwh_m2": "kWh m-2 year-1",
    "cycles_per_year": "year-1",
}
RATE_VARIABLES = ("hydrolysis_rate", "photodegradation_rate", "thermomechanical_rate", "total_rate")
RATE_UNITS = "% year-1"
DAILY_EXTREMA_CONVENTION = (
    "UTC hourly interval means; annual mean module temperature and ambient RH; "
    "upper/lower are annual means of daily maxima/minima; integrated 280-400 nm UV; "
    "explicit cycles/year. Repository aggregation, not an exact published raster reproduction."
)


[docs] def annual_stresses(weather: xr.Dataset, *, year: int, cycles_per_year: float) -> xr.Dataset: """Process ONE complete UTC calendar year of hourly regional weather. Inputs: module_temperature_c [degC], relative_humidity_percent [%], and uv_irradiance_w_m2 [W m-2], each (time, lat, lon). Time labels are timezone-naive datetime64 UTC interval starts; dataset time_zone must be 'UTC'. UV means 280-400 nm; native ERA5 UV to 440 nm is not interchangeable. Arithmetic RH and mean daily extrema are explicit implementation choices; use prepared annual stresses when a calibration uses other conventions. Any missing hourly input masks the whole cell-year; valid_hour_count remains. No annualization of partial coverage, interpolation, or inferred cycle count. Call on spatial tiles rather than loading a global hourly year into memory. """ if isinstance(year, bool) or not isinstance(year, int) or not 1678 <= year <= 2261: raise ValueError("year must be an integer within datetime64[ns] range") if not np.isfinite(cycles_per_year) or cycles_per_year < 0: raise ValueError("cycles_per_year must be finite and nonnegative") if weather.attrs.get("time_zone") != "UTC": raise ValueError("Hourly weather must declare time_zone='UTC'") if "time" not in weather.coords or weather.time.dims != ("time",): raise ValueError("Hourly weather requires a one-dimensional time coordinate") expected = pd.date_range(f"{year}-01-01", f"{year + 1}-01-01", freq="h", inclusive="left") if not np.issubdtype(weather.time.dtype, np.datetime64) or not np.array_equal( weather.time.values, expected.values ): raise ValueError("Weather must contain exactly one complete UTC year of hourly starts") variables = { "module_temperature_c": "degC", "relative_humidity_percent": "%", "uv_irradiance_w_m2": "W m-2", } grids = {} for name, units in variables.items(): value = weather[name] if set(value.dims) != {"time", "lat", "lon"} or value.attrs.get("units") != units: raise ValueError(f"{name} requires (time, lat, lon) and units={units!r}") value = normalize_grid(value).transpose("time", "lat", "lon") if np.isinf(value).any(): raise ValueError(f"{name} cannot contain infinity") grids[name] = value temperature, rh, uv = (grids[name] for name in variables) if (temperature <= -273.15).any() or ((rh < 0) | (rh > 100)).any() or (uv < 0).any(): raise ValueError("Invalid hourly temperature, humidity or UV irradiance") valid = np.isfinite(temperature) & np.isfinite(rh) & np.isfinite(uv) count = valid.sum("time") complete = count == len(expected) daily = temperature.resample(time="1D") result = xr.Dataset( { "module_temperature_mean_c": temperature.mean("time", skipna=False), "module_temperature_upper_c": daily.max(skipna=False).mean("time", skipna=False), "module_temperature_lower_c": daily.min(skipna=False).mean("time", skipna=False), "relative_humidity_percent": rh.mean("time", skipna=False), "uv_dose_kwh_m2": uv.sum("time", skipna=False) / 1000, "cycles_per_year": xr.full_like(count, cycles_per_year, dtype=float), } ).where(complete) for name, units in STRESS_UNITS.items(): result[name].attrs = {"units": units} result["valid_hour_count"] = count.astype("int32") result.valid_hour_count.attrs["units"] = "1" result.attrs = { "stress_convention": DAILY_EXTREMA_CONVENTION, "source": str(weather.attrs.get("source", "caller-provided hourly weather")), "reference_ids": " ".join(REFERENCE_IDS), } return result.expand_dims(year=[year])
[docs] def degradation_classes(rate: xr.DataArray, *, region: Literal["global", "europe"]) -> xr.DataArray: """Thesis Section 6.4 bins: 0.2%/year, overflow above 1.4 globally or 0.8 in Europe. Upper edges are inclusive, an explicit implementation convention. ID 0 is missing, ID 1 includes a true zero; no clipping of high degradation rates. """ if region not in {"global", "europe"}: raise ValueError("region must be global or europe") if rate.attrs.get("units") != RATE_UNITS: raise ValueError(f"Degradation rates require units={RATE_UNITS!r}") values = np.asarray(rate.values, dtype=float) if np.isinf(values).any() or np.any(values < 0): raise ValueError("Rates must be nonnegative or NaN") edges = np.array([0.2, 0.4, 0.6, 0.8, 1.0, 1.2, 1.4][: 7 if region == "global" else 4]) classes = np.where(np.isnan(values), 0, np.searchsorted(edges, values, side="left") + 1) labels = {0: "No data", 1: "[0, 0.2]"} labels.update({i + 2: f"({low:g}, {high:g}]" for i, (low, high) in enumerate(pairwise(edges))}) labels[len(edges) + 1] = f">{edges[-1]:g}" result = xr.DataArray( classes.astype("int8"), coords=rate.coords, dims=rate.dims, name="rate_class" ) result.attrs = { "units": "1", "bin_units": RATE_UNITS, "bin_region": region, "upper_edges": edges, "class_labels": json.dumps(labels), "nodata": 0, "edge_ownership": "upper-inclusive", } return result
[docs] def map_degradation( stresses: xr.Dataset, parameters: DegradationParameters, *, aggregation: Literal["mean_stress", "mean_rate"], region: Literal["global", "europe"] = "global", ) -> xr.Dataset: """Map consecutive annual (year, lat, lon) stresses on their exact grid. mean_stress evaluates once on equal-year mean stresses (the mapping workflow). mean_rate evaluates each year, then averages rates (a different, explicit sensitivity scenario). Cells need every stress in every year. Input dataset must describe stress_convention; no implicit regridding or ocean filling. """ if aggregation not in {"mean_stress", "mean_rate"}: raise ValueError("aggregation must be mean_stress or mean_rate") if not str(stresses.attrs.get("stress_convention", "")).strip(): raise ValueError("Annual stresses must describe stress_convention") if "year" not in stresses.coords or stresses.year.dims != ("year",): raise ValueError("Annual stresses require a one-dimensional year coordinate") years = np.asarray(stresses.year.values) if ( not np.issubdtype(years.dtype, np.integer) or not len(years) or np.any(np.diff(years) != 1) or np.any((years < 1) | (years > 9999)) ): raise ValueError("Years must be increasing, unique, consecutive integers") grids = {} for name, units in STRESS_UNITS.items(): value = stresses[name] if set(value.dims) != {"year", "lat", "lon"} or value.attrs.get("units") != units: raise ValueError(f"{name} requires (year, lat, lon) and units={units!r}") if not value.sizes["lat"] or not value.sizes["lon"]: raise ValueError("Stress grids must not be empty") grids[name] = normalize_grid(value).transpose("year", "lat", "lon") annual = xr.Dataset(grids) # Validate original annual values even when a mean could conceal bad inputs. yearly_rates = degradation_rates( **{k: v.values for k, v in grids.items()}, parameters=parameters ) valid_year = np.isfinite(yearly_rates.total) count = valid_year.sum(axis=0) template = annual.module_temperature_mean_c.isel(year=0, drop=True) if aggregation == "mean_stress": rates = degradation_rates( **{k: v.mean("year", skipna=False).values for k, v in grids.items()}, parameters=parameters, ) values = (rates.hydrolysis, rates.photodegradation, rates.thermomechanical, rates.total) else: values = tuple( value.mean(axis=0) for value in ( yearly_rates.hydrolysis, yearly_rates.photodegradation, yearly_rates.thermomechanical, yearly_rates.total, ) ) result = xr.Dataset() for name, value in zip(RATE_VARIABLES, values, strict=True): result[name] = xr.DataArray( np.where(count == len(years), value, np.nan), dims=template.dims, coords=template.coords, attrs={"units": RATE_UNITS, "long_name": name.replace("_", " ")}, ) result["valid_year_count"] = xr.DataArray( count.astype("int32"), dims=template.dims, coords=template.coords, attrs={"units": "1"} ) result["rate_class"] = degradation_classes(result.total_rate, region=region) result.attrs = { "method": "Kaaya climate degradation; thesis Eqs. 3.14-3.17 and Section 6.4", "reference_ids": " ".join(REFERENCE_IDS), "baseline_start_year": int(years[0]), "baseline_end_year": int(years[-1]), "aggregation": aggregation, "coverage_policy": "all stresses in every year", "stress_convention": str(stresses.attrs["stress_convention"]), "source": str(stresses.attrs.get("source", "caller-provided annual stresses")), "calibration": json.dumps(parameters.to_dict(), sort_keys=True), "scope": ( "Module-specific climate indicators; excludes LID, LeTID, PID, soiling and snow losses" ), } return result
[docs] def kgpv_degradation_summary(rates: xr.Dataset, kgpv: xr.DataArray) -> xr.Dataset: """Area-weighted mechanism means per KGPV zone on exactly matching regular grids. Only cells with all four rates and a known KGPV class contribute. KGPV may use a different climate baseline; its supplied metadata is recorded. Regrid class maps explicitly with nearest-neighbour before calling this function. """ zones = normalize_grid(kgpv).transpose("lat", "lon") if ( np.isinf(zones).any() or ((zones < 0) | (zones >= len(ZONE_CODES)) | (zones != np.floor(zones))) .where(zones.notnull(), False) .any() ): raise ValueError("KGPV class IDs must be 0..12 or NaN") layers = [] for name in RATE_VARIABLES: layer = normalize_grid(rates[name]).transpose("lat", "lon") if layer.attrs.get("units") != RATE_UNITS or np.isinf(layer).any() or (layer < 0).any(): raise ValueError(f"{name} must be nonnegative rates in {RATE_UNITS}") layer, _ = xr.align(layer, zones, join="exact") layers.append(layer) valid = xr.concat([layer.notnull() for layer in layers], dim="mechanism").all("mechanism") areas = cell_areas_km2(zones) rows = [] for identifier in range(1, len(ZONE_CODES)): selected = valid & (zones == identifier) weights = areas.where(selected, 0) area = float(weights.sum()) row = {"valid_area_km2": area, "valid_cell_count": int(selected.sum())} for name, layer in zip(RATE_VARIABLES, layers, strict=True): row[name] = float((layer.where(selected, 0) * weights).sum()) / area if area else np.nan rows.append(row) result = xr.Dataset( {name: ("kgpv_zone", [row[name] for row in rows]) for name in rows[0]}, coords={"kgpv_zone": list(ZONE_CODES[1:])}, ) for name in RATE_VARIABLES: result[name].attrs["units"] = RATE_UNITS result.valid_area_km2.attrs["units"] = "km2" result.valid_cell_count.attrs["units"] = "1" result.attrs = { "weighting": "spherical grid-cell area; valid intersection only", "kgpv_metadata": json.dumps(dict(kgpv.attrs), default=str, sort_keys=True), "degradation_metadata": json.dumps(dict(rates.attrs), default=str, sort_keys=True), "reference_ids": " ".join((*REFERENCE_IDS, "ascencio_vasquez_2019_kgpv")), } return result