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.
1. Environment and setup
Section titled “1. Environment and setup”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 localera5/directory.
2. Required input folder structure
Section titled “2. Required input folder structure”SolarCalibrator expects a base data_path with these subdirectories:
data/ plant/plant_data.csv generation/generation_data.parquet era5/*.ncThe required ERA5 variables are the same irradiation and temperature fields used by the standard RenCal solar workflow:
surface_solar_radiation_downwards(ssrdin NetCDF)2m_temperature(t2min NetCDF)
3. Configure SolarCalibrator
Section titled “3. Configure SolarCalibrator”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 |
4. Run calibration
Section titled “4. Run calibration”sc.calibrate()The calibration executes these steps in sequence:
- Resource extraction — loads solar irradiance and temperature data for each plant from the nearest ERA5 grid cell.
- Historical load-factor generation — merges plant generation with capacity and resource data to calculate historical solar output ratios.
- Distribution fitting — fits an empirical irradiance histogram for each plant to understand the distribution of observed conditions.
- NOCT fitting — estimates the solar curve parameters
gammaandNOCTusing the observed temperature and irradiance relationship. - 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.
5. Inspect outputs
Section titled “5. Inspect outputs”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")6. How the solar curve is modeled
Section titled “6. How the solar curve is modeled”The fitted relationship follows a NOCT-style PV model:
T_cell = T + (NOCT - 20) * G / 800load_factor = (1 - gamma * (T_cell - 25)) * G / 1000Where:
Tis the plant temperature time series,Gis irradiance inW/m²,gammais the temperature coefficient,NOCTis 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.
7. Troubleshooting
Section titled “7. Troubleshooting”Missing or invalid ERA5 fields
Section titled “Missing or invalid ERA5 fields”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).
Calibration fit failures
Section titled “Calibration fit failures”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.

