Skip to main content

☀️ SolarCast

Compare forecasting models on a shared energy-data backtest, starting with day-ahead Belgian aggregated solar PV.

Same data. Same horizon. Same backtest. Let the results decide.

Install and run the offline quickstart · Public API guide

import pandas as pd
from solarcast import BenchmarkConfig, benchmark

# Synthetic installation check, not Belgian PV or accuracy evidence.
pv = pd.DataFrame(
    {
        "target_time": pd.date_range("2025-01-01", "2025-01-12", freq="15min", tz="UTC"),
        "pv_generation_mw": 100.0,
    }
)
config = BenchmarkConfig(
    issue_times=pd.date_range("2025-01-09 11:00", periods=2, freq="D", tz="Europe/Brussels"),
    observation_safety_lag="30min",  # explicit availability approximation
)
results = benchmark(data=pv, config=config, models=["seasonal_persistence_48h"])
results.leaderboard()  # pandas DataFrame, including common support and availability

Why SolarCast?

New forecasting models arrive frequently. Energy teams need to know whether they improve their own problem, but rankings are hard to interpret when data, horizons, information availability and metrics differ. SolarCast provides a common framework:

  • Sequential rolling-origin backtests with explicit issue times and bounded history.
  • Historical NWP vintage selection, distinguishing assumed and observed availability.
  • Common-support MAE, RMSE, bias and explicit-reference skill, with failure accounting.
  • DST-safe Belgian target days: 92, 96 or 100 quarter-hour intervals.
  • Persistence, classical ML and pretrained TSFM adapters with inspectable configuration.

Quick start

The distribution name is solarcast-belgium; the Python import is solarcast. Python 3.11–3.13. Clone the repository, then create an environment:

git clone https://github.com/Junaid-Bashir/solarcast-belgium.git
cd solarcast-belgium
python -m venv .venv
# Windows PowerShell: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
python -m pip install -e .
python examples/quickstart.py

The canonical quickstart is offline, uses base dependencies and prints a synthetic leaderboard. No credentials, weights or GFS preparation are needed. If activation is unavailable, use .venv/Scripts/python.exe (Windows) or .venv/bin/python. PyPI: not published. Install from this repository or a local source distribution. See installation and examples.

For real data, supply aware quarter-hour target_time interval starts and nullable numeric pv_generation_mw, with enough history and scoring actuals. The issue schedule and observation safety lag are explicit. benchmark() never fetches PV/NWP.

Supported models

Public identifier Type Training Forecast weather Extra
last_value_persistence Baseline None None Core
seasonal_persistence_48h Baseline None None Core
seasonal_persistence_7d Baseline None None Core
lightgbm ML Pre-test fit None lightgbm
lightgbm_history_radiation_cloud ML + NWP Pre-test fit Historical GFS lightgbm
t0 t0-gamma TSFM Zero-shot None t0
chronos Chronos-2 TSFM Zero-shot None chronos

available_models() reports dependency availability without loading ML runtimes. TSFM weights are local-only by default in the public API; downloads require opt-in. Weather LightGBM requires a prepared local WeatherStore, with no history-only fallback. See public API for explicit training and weather prerequisites.

Development benchmark

These are known-period development results, not an untouched confirmatory evaluation or evidence of operational readiness. Earlier development decisions used this population. A fresh confirmatory period is needed before generalizing.

Elia national Belgian PV, day-ahead at 15-minute resolution, March–October 2025: 245 origins at 11:00 Europe/Brussels, 23,520 common quarters per model, including night.

Model RMSE (MW), lower is better
Weather-LightGBM 624.19
t0-gamma 866.33
Chronos-2 938.13
History-LightGBM 1,026.88
48h persistence 1,027.03

Belgian PV development benchmark: RMSE in MW, lower is better, March–October 2025

All five models have 100% forecast availability and zero failed test origins. Outputs are raw: no clipping or nighttime removal. Weather-LightGBM receives forecast radiation/cloud; the other models are history-only. Shared scoring does not imply identical information sets. PV completion plus 30 minutes and GFS initialization plus six hours are availability assumptions, not certified historical as-of evidence. Revisions and TSFM pretraining overlap remain unresolved.

Values come from the hash-authenticated frozen extended leaderboard, with no new fitting or inference. See the full experiment report, public aggregate snapshot, and reproducibility limits. Exact replay currently requires local immutable artifacts that are not distributed with this repository.

Methodology and data

Issue T -> select history/NWP eligible under the declared policy -> model
        -> future targets -> evaluator joins actuals -> common-support scoring

LightGBM reconstructs historical training features/vintages before joining fit-time-eligible labels. Failed origins remain visible. Seasonal lags use exact elapsed UTC durations; next-day targets follow Brussels calendar boundaries. Read backtesting and evaluation.

Large datasets, GFS caches, trained models, weights and prediction caches are not redistributed. Small documented fixtures and aggregate metrics are intentional exceptions, with separate third-party terms.

Documentation and extras

Start at the documentation index, public API or example catalog. The research notebook is clean source requiring separate local artifacts, not the beginner quickstart.

Install only what you need, for example python -m pip install -e ".[lightgbm]".

Extra Adds
lightgbm CPU LightGBM training/inference
t0 Independent t0/PyTorch adapter support
chronos Independent Chronos adapter support
weather Optional GRIB/Parquet and spatial preparation tools
experiments LightGBM and matplotlib research tooling
dev Tests, linting, typing and package builds

Notebook tools have separate development requirements. Installing an extra does not download checkpoints.

Project status and contributing

Active development / research software: 0.1.0, unreleased. The API may evolve before 1.0; PyPI publication comes later. Operational forecast(), automatic best-model selection, ensembles and probabilistic evaluation are not implemented.

See CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, roadmap and the release process. No production or operational accuracy guarantee is made.

Citation and license

CITATION.cff contains minimal project-entity attribution; individual authorship is intentionally not invented. No DOI is claimed. Software is Apache-2.0; external data, weights and fixtures retain their own provenance and terms.

Metadata

Release files for solarcast-belgium 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for solarcast-belgium 0.1.0
File Size Uploaded Provenance Actions
solarcast_belgium-0.1.0.tar.gz 317.2 kB With provenance Details for solarcast_belgium-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for solarcast-belgium 0.1.0
File Interpreter ABI Platform Actions
solarcast_belgium-0.1.0-py3-none-any.whl Python 3 none any Details for solarcast_belgium-0.1.0-py3-none-any.whl

Total release size: 412.6 kB

Release files / solarcast_belgium-0.1.0.tar.gz

Download URL solarcast_belgium-0.1.0.tar.gz
Size 317.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ed3d348a7eee33ef78a9209025e1a81c45cc7c74316e32b1ebcc72e44b806563
BLAKE2b-256 checksum
How to use checksums
bde305adef6a5c60f370cb7f7df89650a17f4fdb40e8a383fcbfd4769e022a19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / solarcast_belgium-0.1.0-py3-none-any.whl

Download URL solarcast_belgium-0.1.0-py3-none-any.whl
Size 95.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88164c0c46fa0e821b297105ff1b40c6ccee326d9fbf2af0d07a0e40fa661159
BLAKE2b-256 checksum
How to use checksums
6e92fe95da444d6a09bd1f58bf15d783255d066cd5abf4d7ac19b4eda84f4387
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for solarcast-belgium 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for solarcast_belgium-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page