Source code for energy_analysis.ccya_case.config

"""Explicit inputs and study settings; scenario names are never probabilities."""

from __future__ import annotations

import math
import re
import tomllib
from dataclasses import dataclass
from pathlib import Path
from typing import Literal


[docs] @dataclass(frozen=True, slots=True) class Scenario: id: str label: str historical_path: Path projection_path: Path source: str def __post_init__(self) -> None: if not re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,63}", self.id): raise ValueError("Scenario id requires 1..64 lowercase letters, digits, _ or -") if not self.label.strip() or not self.source.strip(): raise ValueError("Scenario label and model/member/dataset source must be explicit")
[docs] @dataclass(frozen=True, slots=True) class CaseConfig: title: str data_kind: Literal["synthetic", "observed_and_projected"] measured_path: Path measured_source: str output_path: Path scenarios: tuple[Scenario, ...] degradation_rates: tuple[float, ...] = (0.0, 0.0025, 0.005, 0.01) report_years: tuple[int, ...] = (25, 50) plot_degradation_rate: float = 0.005 def __post_init__(self) -> None: if self.data_kind not in {"synthetic", "observed_and_projected"}: raise ValueError("data_kind must be synthetic or observed_and_projected") if not self.title.strip() or not self.measured_source.strip(): raise ValueError("Study title and measured_source are required") if not 1 <= len(self.scenarios) <= 16: raise ValueError("Use 1..16 explicit scenario/member cases") if len({s.id for s in self.scenarios}) != len(self.scenarios): raise ValueError("Scenario identifiers must be unique") rates = self.degradation_rates if not 1 <= len(rates) <= 8 or len(set(rates)) != len(rates): raise ValueError("Use 1..8 unique degradation rates") if any(not math.isfinite(r) or not 0 <= r <= 1 for r in rates): raise ValueError("Degradation rates must be finite fractions in [0, 1]") if self.plot_degradation_rate not in rates: raise ValueError("plot_degradation_rate must be one of degradation_rates") if not self.report_years or len(set(self.report_years)) != len(self.report_years): raise ValueError("report_years must contain unique operating years") if any(isinstance(y, bool) or not isinstance(y, int) or y < 1 for y in self.report_years): raise ValueError("report_years must contain positive integer operating years")
[docs] def load_config(path: Path) -> CaseConfig: """Load strict TOML; resolve local CSV and output paths beside the config.""" document = tomllib.loads(path.read_text(encoding="utf-8")) if set(document) != {"ccya", "scenarios"}: raise ValueError("Configuration must contain [ccya] and [[scenarios]] only") values, scenarios = document["ccya"], document["scenarios"] if not isinstance(values, dict) or not isinstance(scenarios, list): raise ValueError("Invalid CCYA configuration structure") if set(values) - (set(CaseConfig.__dataclass_fields__) - {"scenarios"}): raise ValueError("Unknown [ccya] configuration key") base = path.resolve().parent def string(row: dict, key: str) -> str: value = row.get(key) if not isinstance(value, str) or not value.strip(): raise ValueError(f"{key} must be a nonempty string") return value parsed = [] for row in scenarios: if not isinstance(row, dict) or set(row) != set(Scenario.__dataclass_fields__): raise ValueError("Each scenario must provide id, label, paths and source") parsed.append( Scenario( string(row, "id"), string(row, "label"), (base / string(row, "historical_path")).resolve(), (base / string(row, "projection_path")).resolve(), string(row, "source"), ) ) kind = string(values, "data_kind") if kind not in {"synthetic", "observed_and_projected"}: raise ValueError("data_kind must be synthetic or observed_and_projected") rates = values.get("degradation_rates", [0.0, 0.0025, 0.005, 0.01]) if not isinstance(rates, list) or any(type(v) not in (int, float) for v in rates): raise ValueError("degradation_rates must be a numeric array") years = values.get("report_years", [25, 50]) if not isinstance(years, list): raise ValueError("report_years must be an integer array") plot_rate = values.get("plot_degradation_rate", 0.005) if type(plot_rate) not in (int, float): raise ValueError("plot_degradation_rate must be numeric") return CaseConfig( title=string(values, "title"), data_kind="synthetic" if kind == "synthetic" else "observed_and_projected", measured_path=(base / string(values, "measured_path")).resolve(), measured_source=string(values, "measured_source"), output_path=(base / string(values, "output_path")).resolve(), scenarios=tuple(parsed), degradation_rates=tuple(float(v) for v in rates), report_years=tuple(years), plot_degradation_rate=float(plot_rate), )