GlobalSplineFit

Parametric model of cosmic ray flux and composition based on cubic B-spline fits to observational data. Covers all elements Z=1--28, with full covariance propagation and solar modulation.

Installation

pip install globalsplinefit

Quick Start

from globalsplinefit import GSFEnergy
import numpy as np

model = GSFEnergy()          # default 2026 fit
model_uso = GSFEnergy(version="2026-USO")  # Usoskin 2017 modulation
model_s23e = GSFEnergy(version="2026-SIB23e")  # SIBYLL-2.3e-only interpretation
model_epos = GSFEnergy(version="2026-EPOSLHCR")  # EPOS-LHC-R only (other half of the mixture)
model_2025 = GSFEnergy(version="2025")   # historical release
energy = np.logspace(0, 3, 100)  # 1 GeV to 1 TeV total energy

proton_flux = model.flux(energy, "p")
proton_error = model.error(energy, "p")
total_flux = model.total_flux(energy)

# Flux at Earth averaged over a time period (end month EXCLUSIVE):
# (200901, 201001) = calendar year 2009
flux_earth = model.flux(energy, "p", time_interval=(200901, 201001))

Examples

Try the model without installing anything: the GSF Explorer and the tutorial gallery run in the browser.

The tutorials in examples/ are marimo notebooks — plain Python files you can open interactively or run as scripts:

uv run marimo edit examples/reduced_model.py   # interactive
uv run python examples/reduced_model.py        # run top to bottom

Need a Jupyter notebook? uvx marimo export ipynb examples/<name>.py -o <name>.ipynb.

How to cite

Please cite the GSF 2026 paper — A. Fedynitch, K. Fujisue, H. Dembinski, and R. Engel, Global Spline Fit: A unified data-driven view of the cosmic-ray spectrum and mass composition from GeV to the highest energies, arXiv:2609.32649 (2026) — and the software version you used. Machine-readable metadata is in CITATION.cff (GitHub's "Cite this repository" button); the documentation lists the reference for every parameter set and solar-modulation potential.

Development

Development uses uv:

git clone https://github.com/gsf-project/globalsplinefit.git
cd globalsplinefit
uv sync --all-extras     # creates .venv with all optional dependencies
uv run pytest tests/
uv run pre-commit install

Contributions are welcome — see CONTRIBUTING.md (it also serves as the orientation guide for AI coding agents).

Links

• Documentation
• Issues
• CHANGELOG

License

BSD 3-Clause. See LICENSE.