Skip to content

Solar Calibration Tutorial

This tutorial walks through the workflow for running solar calibration locally using SolarCalibrator. It covers the required input layout, the calibration run itself, and the output files generated for downstream simulation and forecasting.

Before running:

  • Use Python 3.12.
  • Install project dependencies (including notebook extras):
    Terminal window
    uv sync --group notebook
  • Ensure ERA5 NetCDF support is available (xarray + netCDF4), because the calibrator loads hourly solar irradiance and temperature files from the local era5/ directory.

SolarCalibrator expects a base data_path with these subdirectories:

data/
plant/plant_data.csv
generation/generation_data.parquet
era5/*.nc

The required ERA5 variables are the same irradiation and temperature fields used by the standard RenCal solar workflow:

  • surface_solar_radiation_downwards (ssrd in NetCDF)
  • 2m_temperature (t2m in NetCDF)
from pathlib import Path
from rencal.calibration.solar.solar_calibrator import SolarCalibrator
sc = SolarCalibrator(
data_path="data",
output_path=Path("outputs/solar_calibration"),
visual_output=True,
stream_npy_output=True,
)

Key constructor arguments:

Argument Type Description
data_path str Base folder containing plant/, generation/, and era5/
output_path Path | str Directory where calibration outputs are written
visual_output bool Save per-plant PV curve fit PNGs when True
stream_npy_output bool Also save solar_streams.npy when True
sc.calibrate()

The calibration executes these steps in sequence:

  1. Resource extraction — loads solar irradiance and temperature data for each plant from the nearest ERA5 grid cell.
  2. Historical load-factor generation — merges plant generation with capacity and resource data to calculate historical solar output ratios.
  3. Distribution fitting — fits an empirical irradiance histogram for each plant to understand the distribution of observed conditions.
  4. NOCT fitting — estimates the solar curve parameters gamma and NOCT using the observed temperature and irradiance relationship.
  5. Stream generation — applies the fitted PV curve to the full historical resource record to create long-term solar load-factor streams.

Note: If a plant cannot be fit reliably, the module falls back to a generic solar curve derived from median fitted parameters.

After calibration, the following files are written to output_path:

File Description
solar_resource.csv Plant-wise irradiance and temperature time series
solar_distribution_params.csv Empirical irradiance histogram metadata per plant
solar_calibration_summary.csv Fitted Gamma, NOCT, and estimated load-factor summaries
solar_streams.parquet Hourly solar load-factor streams per plant
pv_curve_fit_*.png Per-plant PV curve fit plots (if visual_output=True)
solar_streams.npy Binary solar stream array (if stream_npy_output=True)

Output filenames use lowercase snake_case prefixes; plot filenames retain the original plant identifier (for example, pv_curve_fit_AR4-BSP-700.png). Existing outputs are not renamed automatically: rerun calibration or rename the old files, and update any downstream paths to use the new names. Data column names are unchanged.

import pandas as pd
summary = pd.read_csv("outputs/solar_calibration/solar_calibration_summary.csv")
streams = pd.read_parquet("outputs/solar_calibration/solar_streams.parquet")
resource = pd.read_csv("outputs/solar_calibration/solar_resource.csv")

The fitted relationship follows a NOCT-style PV model:

T_cell = T + (NOCT - 20) * G / 800
load_factor = (1 - gamma * (T_cell - 25)) * G / 1000

Where:

  • T is the plant temperature time series,
  • G is irradiance in W/m²,
  • gamma is the temperature coefficient,
  • NOCT is the nominal operating cell temperature.

This structure lets RenCal estimate expected solar output for each plant using observed resource conditions rather than assuming a fixed capacity factor.

If the fit fails or the resource table is empty, check that the local NetCDF files include the expected variables:

import xarray as xr
ds = xr.open_dataset("data/era5/example.nc")
print(sorted(ds.data_vars))

For solar calibration, the loader expects ssrd and t2m (or the equivalent mapped names in your local NetCDF files).

If a plant shows no valid calibration summary row, the most common causes are:

  • too little generation history for that plant,
  • missing temperature or irradiance rows in the aligned resource frame,
  • unrealistic or noisy historical load factors.

In those cases, RenCal automatically falls back to a generic solar curve for the missing plant.