Source code for energy_analysis.degradation.config

"""Explicit, bounded degradation study settings; TOML paths are relative to the file."""

from __future__ import annotations

import json
import tomllib
from dataclasses import dataclass
from pathlib import Path

import numpy as np
from numpy.typing import NDArray

from energy_methods.degradation import DegradationParameters


[docs] @dataclass(frozen=True, slots=True) class StudyConfig: name: str start_year: int end_year: int latitude_min: float latitude_max: float longitude_min: float longitude_max: float step_degrees: float parameters_path: Path cycles_per_day: float aggregation: str = "mean_stress" u0: float = 26.9 u1: float = 6.2 module_height_m: float = 2.0 def __post_init__(self) -> None: if not isinstance(self.name, str) or not self.name.strip(): raise ValueError("Study name is required") if ( type(self.start_year) is not int or type(self.end_year) is not int or not 1940 <= self.start_year <= self.end_year <= 2025 ): raise ValueError("Study years must be ordered integers within 1940..2025") bounds = [ self.latitude_min, self.latitude_max, self.longitude_min, self.longitude_max, self.step_degrees, self.cycles_per_day, self.u0, self.u1, self.module_height_m, ] if not np.isfinite(bounds).all(): raise ValueError("Study settings must be finite") if not ( -90 < self.latitude_min < self.latitude_max < 90 and -180 <= self.longitude_min < self.longitude_max < 180 ): raise ValueError("Ordered geographic cell centres are required; omit duplicate seams") if not 0.25 <= self.step_degrees <= 30 or self.cycles_per_day < 0: raise ValueError("Grid step must be 0.25..30 degrees and cycles/day nonnegative") if self.aggregation not in {"mean_stress", "mean_rate"}: raise ValueError("Unknown aggregation") if self.u0 <= 0 or self.u1 < 0 or self.module_height_m <= 0: raise ValueError("Invalid Faiman parameters") for low, high in ( (self.latitude_min, self.latitude_max), (self.longitude_min, self.longitude_max), ): if not np.isclose( (high - low) / self.step_degrees, round((high - low) / self.step_degrees) ): raise ValueError("Grid span must be an exact multiple of step_degrees") if len(self.latitudes) * len(self.longitudes) > 10_000: raise ValueError("Study exceeds 10,000 grid cells; use regional configurations") @property def latitudes(self) -> NDArray[np.float64]: return np.linspace( self.latitude_min, self.latitude_max, round((self.latitude_max - self.latitude_min) / self.step_degrees) + 1, ) @property def longitudes(self) -> NDArray[np.float64]: return np.linspace( self.longitude_min, self.longitude_max, round((self.longitude_max - self.longitude_min) / self.step_degrees) + 1, )
[docs] def parameters(self) -> DegradationParameters: return DegradationParameters(**json.loads(self.parameters_path.read_text(encoding="utf-8")))
[docs] def load_config(path: Path) -> StudyConfig: """Read the study section and reject unknown/missing settings via the dataclass.""" record = tomllib.loads(path.read_text(encoding="utf-8"))["study"] record["parameters_path"] = (path.parent / record["parameters_path"]).resolve() return StudyConfig(**record)