Source code for energy_analysis.chile_fleet.config

"""Explicit time, input and scientific settings for a reproducible fleet run."""

from __future__ import annotations

import math
import tomllib
from dataclasses import dataclass
from datetime import UTC, datetime, timedelta
from pathlib import Path
from typing import Literal


[docs] def utc_datetime(value: str | datetime) -> datetime: """Parse an explicitly offset timestamp; never guess a civil-clock timezone.""" result = ( datetime.fromisoformat(value.replace("Z", "+00:00")) if isinstance(value, str) else value ) if result.tzinfo is None or result.utcoffset() is None: raise ValueError( "Timestamps require an explicit UTC offset, for example 2026-10-26T03:00:00Z" ) return result.astimezone(UTC)
[docs] @dataclass(frozen=True, slots=True) class FleetConfig: """Half-open UTC periods; the event boundary never belongs to training.""" hourly_path: Path sites_path: Path output_path: Path event_start: datetime report_start: datetime report_end: datetime baseline_days: int = 90 holdout_days: int = 14 algorithm: Literal["physics", "lightgbm"] = "physics" reference: Literal["final", "heldout"] = "final" minimum_training_hours: int = 48 minimum_reference_coverage: float = 0.8 relative_tolerance: float = 0.2 fit_geometry: bool = True lag_hours: tuple[int, ...] = (-2, -1, 0, 1, 2) model_threads: int = 1 tdp: bool = True tdp_minimum_useful_days: int = 15 tdp_minimum_hours_per_day: int = 24 tdp_minimum_bin_observations: int = 10 hash_inputs: bool = True data_kind: Literal["unspecified", "synthetic", "observational"] = "unspecified" def __post_init__(self) -> None: for name in ("event_start", "report_start", "report_end"): object.__setattr__(self, name, utc_datetime(getattr(self, name))) if any( value.minute or value.second or value.microsecond for value in ( self.event_start, self.report_start, self.report_end, ) ): raise ValueError("Time boundaries must fall exactly on elapsed-hour boundaries") if self.report_start >= self.report_end: raise ValueError("report_start must precede the exclusive report_end") if not 0 < self.holdout_days < self.baseline_days: raise ValueError("Require 0 < holdout_days < baseline_days") if ( not math.isfinite(self.minimum_reference_coverage) or not 0 <= self.minimum_reference_coverage <= 1 ): raise ValueError("minimum_reference_coverage must be in [0, 1]") if not math.isfinite(self.relative_tolerance) or not 0 <= self.relative_tolerance < 1: raise ValueError("relative_tolerance must be in [0, 1)") if self.algorithm not in {"physics", "lightgbm"} or self.reference not in { "final", "heldout", }: raise ValueError("Unsupported model algorithm or reference") if self.minimum_training_hours < 8 or not 1 <= self.model_threads <= 32: raise ValueError("Use at least eight training hours and 1..32 model threads") if not self.lag_hours or any(abs(lag) > 6 for lag in self.lag_hours): raise ValueError("lag_hours must contain integer shifts between -6 and 6") if any(not isinstance(lag, int) or isinstance(lag, bool) for lag in self.lag_hours): raise ValueError("lag_hours must contain integer shifts") if self.report_start < self.training_start: raise ValueError("The report cannot precede the configured baseline window") if self.data_kind not in {"unspecified", "synthetic", "observational"}: raise ValueError("data_kind must be unspecified, synthetic or observational") @property def training_start(self) -> datetime: return self.event_start - timedelta(days=self.baseline_days) @property def holdout_start(self) -> datetime: return self.event_start - timedelta(days=self.holdout_days)
[docs] def load_config(path: Path) -> FleetConfig: """Read a TOML ``[chile_fleet]`` table, resolving file paths beside it.""" with path.open("rb") as stream: document = tomllib.load(stream) values = document.get("chile_fleet", {}) if not isinstance(values, dict): raise ValueError("Expected a [chile_fleet] table") valid = set(FleetConfig.__dataclass_fields__) unknown = set(values) - valid if unknown: raise ValueError(f"Unknown configuration keys: {', '.join(sorted(unknown))}") base = path.resolve().parent for name in ("hourly_path", "sites_path", "output_path"): value = values.get(name) if not isinstance(value, str): raise ValueError(f"{name} must be a path string") values[name] = (base / value).resolve() for name in ("event_start", "report_start", "report_end"): value = values.get(name) if not isinstance(value, (str, datetime)): raise ValueError(f"{name} requires an offset-aware ISO timestamp") values[name] = utc_datetime(value) if "lag_hours" in values: values["lag_hours"] = tuple(values["lag_hours"]) def integer(name: str, default: int) -> int: value = values.get(name, default) if not isinstance(value, int) or isinstance(value, bool): raise ValueError(f"{name} must be an integer") return value def number(name: str, default: float) -> float: value = values.get(name, default) if not isinstance(value, (int, float)) or isinstance(value, bool): raise ValueError(f"{name} must be numeric") return float(value) def boolean(name: str, default: bool) -> bool: value = values.get(name, default) if not isinstance(value, bool): raise ValueError(f"{name} must be true or false") return value algorithm = values.get("algorithm", "physics") reference = values.get("reference", "final") data_kind = values.get("data_kind", "unspecified") if data_kind not in {"unspecified", "synthetic", "observational"}: raise ValueError("data_kind must be unspecified, synthetic or observational") if algorithm not in {"physics", "lightgbm"} or reference not in {"final", "heldout"}: raise ValueError("Invalid algorithm or reference") lags = values.get("lag_hours", (-2, -1, 0, 1, 2)) if not isinstance(lags, tuple) or not all(isinstance(v, int) for v in lags): raise ValueError("lag_hours must contain integers") return FleetConfig( hourly_path=values["hourly_path"], sites_path=values["sites_path"], output_path=values["output_path"], event_start=values["event_start"], report_start=values["report_start"], report_end=values["report_end"], baseline_days=integer("baseline_days", 90), holdout_days=integer("holdout_days", 14), algorithm="lightgbm" if algorithm == "lightgbm" else "physics", reference="heldout" if reference == "heldout" else "final", minimum_training_hours=integer("minimum_training_hours", 48), minimum_reference_coverage=number("minimum_reference_coverage", 0.8), relative_tolerance=number("relative_tolerance", 0.2), fit_geometry=boolean("fit_geometry", True), lag_hours=lags, model_threads=integer("model_threads", 1), tdp=boolean("tdp", True), tdp_minimum_useful_days=integer("tdp_minimum_useful_days", 15), tdp_minimum_hours_per_day=integer("tdp_minimum_hours_per_day", 24), tdp_minimum_bin_observations=integer("tdp_minimum_bin_observations", 10), hash_inputs=boolean("hash_inputs", True), data_kind=( "synthetic" if data_kind == "synthetic" else "observational" if data_kind == "observational" else "unspecified" ), )