Source code for energy_analysis.timestral_solar_case

"""An audited search and chronological solar-generation forecasting case.

June selected the plant; June/July selected the Timestral size and inputs.
August is the final evaluation period. Saved neural forecasts are real inference,
bound to the exact context; other models are fitted again on every replay.
"""

from __future__ import annotations

from pathlib import Path

import numpy as np
import pandas as pd

from energy_analysis.forecast_benchmark import (
    MODELS,
    benchmark_scores,
    run_forecast_benchmark,
)
from energy_methods.timestral import TimestralConnector

REFERENCE_IDS = (
    "ascencio_vasquez_2020_modelling",
    "ons_pv_curtailment",
    "mistralai_2026_timestral",
)
CASE_MODELS = (*MODELS, "Daily mean", "Daily median")
MODEL_ID = "mistralai/Timestral-28M"
MODEL_REVISION = "49b26409ac87b5935539a5d8ffe7f397b720db47"
PLANT_ID = "RNMB06"
HOLDOUT_START = pd.Timestamp("2024-08-01 03:00:00", tz="UTC")


[docs] def run_solar_case( directory: str | Path, *, connector: TimestralConnector | None = None ) -> pd.DataFrame: """Reproduce the frozen case; do not search or optimize on the final holdout. Generation context and calibration span 14 days. If a same-clock resource reading is absent throughout that window, weather-dependent models may use older, pre-issue measurements. If accepted calibration power has zero Q95, retain the last informative calibration for all three fitted comparators. These safeguards keep every holdout label, including the sensor-data gap. """ predictions = run_forecast_benchmark( directory, connector=connector, technologies=("solar",), seasonal_baselines=True, timestral_covariates="target_only", extend_resource_history=True, retain_informative_fit=True, ) if set(predictions["plant_id"]) != {PLANT_ID}: raise ValueError("The frozen case is Mendubim VI (RNMB06)") predictions["period"] = np.where( predictions["timestamp"] < HOLDOUT_START, "Development", "August holdout" ) expected = pd.date_range("2024-06-15 03:00", periods=78 * 48, freq="30min", tz="UTC") if set(predictions["timestamp"]) != set(expected): raise ValueError("The case must retain every June 15-August 31 forecast label") return predictions
[docs] def solar_case_scores(predictions: pd.DataFrame) -> pd.DataFrame: """Separate selection dates from the final month; score identical model keys.""" if set(predictions["period"]) != {"Development", "August holdout"}: raise ValueError("Both development and holdout periods are required") return pd.concat( [ benchmark_scores(frame, models=CASE_MODELS).assign(period=period) for period, frame in predictions.groupby("period", sort=True) ], ignore_index=True, )
[docs] def daily_errors(predictions: pd.DataFrame) -> pd.DataFrame: """Daily MAE for every model, after checking common and complete coverage.""" solar_case_scores(predictions) frame = predictions.assign(error_mw=np.abs(predictions.prediction_mw - predictions.actual_mw)) sizes = frame.groupby(["model", "issue_time"]).size() if not sizes.eq(48).all(): raise ValueError("Every daily issue must include all 48 forecast leads") return frame.groupby(["period", "issue_time", "model"], as_index=False)[["error_mw"]].mean()