sparta-solar: A clear-sky solar radiation model, batteries included

sparta-solar is a Python library for computing clear-sky solar irradiance at the surface using the Solar Parameterization of the Radiative Transfer of the Atmosphere (SPARTA) model. It integrates seamlessly with multiple atmospheric databases to supply the aerosol, water vapour, ozone, and pressure inputs that the radiative transfer model requires.

Key features

Physics-based clear-sky irradiance

SPARTA is a high-accuracy 2-band broadband clear-sky model that computes direct normal (DNI), global horizontal (GHI), diffuse horizontal (DIF) and, unique in its class, circumsolar irradiance (CSI). It is fully vectorized and handles nighttime masking, surface albedo feedback and aerosol–Rayleigh coupling.

A legacy clear-sky model (Bird & Hulstrom, 1981) is also included for comparison and backward-compatibility studies.

Multiple atmospheric databases

sparta-solar ships out-of-the-box with ready-to-use connectors for several atmospheric datasets, covering different temporal resolutions, geographic extents, and access methods:

CF-compliant xarray outputs

All outputs are returned as xarray.Dataset objects following Climate and Forecast (CF-1.11) metadata conventions — ready for analysis, visualization, or export to NetCDF/Zarr.

Flexible configuration

A TOML-based configuration system lets you set data directories, API credentials, and algorithm preferences once, globally, without cluttering your scripts.

Quick examples

Example 1 — Site time series with CAMS radiation service data from SODA

import pandas as pd
from spartasolar.atmosphere import crs_soda

times = pd.date_range("2020-06-15", periods=24, freq="h")
lat, lon, location = 36.72, -4.42, "Málaga"

# The first time that a calculation for this location and
# time period is requested, sparta-solar fetches the data
# from the SODA service and archive it locally for future
# calculations, if needed

atmos = crs_soda.at_site(
    times=times,
    latitude=lat,
    longitude=lon,
    site_names=location)

result = atmos.compute(model="SPARTA")

print(result)  # xarray.Dataset with ghi, dni, dif, csi, …

Example 2 — Gridded irradiance map from MERRA-2 daily data

import numpy as np
import pandas as pd
from spartasolar.atmosphere import merra2_daily

lats = np.arange(36.0, 41.5, 0.5)
lons = np.arange(-9.0, -3.5, 0.5)
times = pd.date_range("2020-06-21 12:00", periods=1, freq="h")

# The first time that a calculation for this time period
# is requested, sparta-solar downloads the yearly dataset
# that covers this time period from hugging face hub and
# archive it locally for future calculations, if needed

atmos = merra2_daily.on_regular_grid(
  times=times,
  latitude=lats,
  longitude=lons)

result = atmos.compute(model="SPARTA")

result.ghi.isel(time=0).plot()  # solar noon GHI map over Iberian Peninsula

Example 3 — Direct use of the SPARTA model

from spartasolar.modlib import SPARTA

out = SPARTA(
    cosz=0.866,       # cos(30°), ~30° solar zenith
    pressure=1013.25, # hPa
    pwater=2.0,       # cm
    ozone=0.3,        # atm-cm
    beta=0.05,        # low turbidity
    alpha=1.3,
    albedo=0.2,
)

print(f"GHI = {out['ghi']:.1f} W/m²,  DNI = {out['dni']:.1f} W/m²")

Getting started

Ready to use sparta-solar? Start with the Installation guide, then follow the User Guide for a detailed walkthrough of every atmospheric data source.

References

• SPARTA model: Ruiz-Arias, J. A. (2023). SPARTA: Solar parameterization for the radiative transfer of the cloudless atmosphere. Renewable and Sustainable Energy Reviews, 188, 113833. https://doi.org/10.1016/j.rser.2023.113833
• MERRA-2 Reanalysis: Gelaro, R., et al. (2017). The Modern-Era Retrospective Analysis for Research and Applications, Version 2 (MERRA-2). J. Climate, 30, 5419–5454. https://doi.org/10.1175/JCLI-D-16-0758.1
• CRS/SODA: CAMS solar radiation time-series data documentation url
• Bird model: Bird, R. E. and Hulstrom, R. L. (1981). A Simplified Clear Atmosphere Radiative Transmittance Model. SERI/TR-642-1156.

License

sparta-solar is licensed under CC BY-NC-SA 4.0 — free for non-commercial use with attribution.

Contact

For any comment write me to jararias at uma dot es.

Citation

If you use sparta-solar in your research, please cite:

@article{ruizarias2023sparta,
  author  = {Ruiz-Arias, Jose A.},
  title   = {{SPARTA}: Solar parameterization for the radiative transfer of the cloudless atmosphere},
  journal = {Renewable and Sustainable Energy Reviews},
  volume  = {188},
  pages   = {113833},
  year    = {2023},
  doi     = {10.1016/j.rser.2023.113833}
}