Metadata-Version: 2.4
Name: globalsplinefit
Version: 2.0.1
Summary: Global Spline Fit model for cosmic ray flux and composition
Author-email: Anatoli Fedynitch <afedynitch@gmail.com>, Hans Dembinski <hans.dembinski@gmail.com>
Maintainer-email: Anatoli Fedynitch <afedynitch@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/gsf-project/globalsplinefit
Project-URL: Bug Reports, https://github.com/gsf-project/globalsplinefit/issues
Project-URL: Source, https://github.com/gsf-project/globalsplinefit
Project-URL: Documentation, https://gsf-project.github.io/globalsplinefit/
Keywords: cosmic rays,astrophysics,particle physics,spline fitting,solar modulation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.0
Requires-Dist: scipy>=1.10
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0; extra == "test"
Requires-Dist: pytest-benchmark>=4.0; extra == "test"
Requires-Dist: psutil>=4.0; extra == "test"
Provides-Extra: examples
Requires-Dist: matplotlib>=3.5.0; extra == "examples"
Requires-Dist: marimo>=0.14; extra == "examples"
Requires-Dist: nbformat>=5.0; extra == "examples"
Requires-Dist: crflux>=2.0; extra == "examples"
Provides-Extra: docs
Requires-Dist: globalsplinefit[examples]; extra == "docs"
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: globalsplinefit[docs,examples,test]; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: all
Requires-Dist: globalsplinefit[dev,docs,examples,test]; extra == "all"
Dynamic: license-file

# GlobalSplineFit

[![PyPI version](https://badge.fury.io/py/globalsplinefit.svg)](https://badge.fury.io/py/globalsplinefit)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Tests](https://github.com/gsf-project/globalsplinefit/actions/workflows/test.yml/badge.svg)](https://github.com/gsf-project/globalsplinefit/actions/workflows/test.yml)

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

```bash
pip install globalsplinefit
```

## Quick Start

```python
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](https://gsf-project.github.io/globalsplinefit/explorer/) and the
[tutorial gallery](https://gsf-project.github.io/globalsplinefit/gallery/)
run in the browser.

The tutorials in `examples/` are [marimo](https://marimo.io) notebooks — plain
Python files you can open interactively or run as scripts:

```bash
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](https://arxiv.org/abs/2609.32649) (2026) — and the software
version you used. Machine-readable
metadata is in [CITATION.cff](CITATION.cff) (GitHub's "Cite this repository"
button); the [documentation](https://gsf-project.github.io/globalsplinefit/#citation)
lists the reference for every parameter set and solar-modulation potential.

## Development

Development uses [uv](https://docs.astral.sh/uv/):

```bash
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](CONTRIBUTING.md) (it also
serves as the orientation guide for AI coding agents).

## Links

- [Documentation](https://gsf-project.github.io/globalsplinefit/)
- [Issues](https://github.com/gsf-project/globalsplinefit/issues)
- [CHANGELOG](CHANGELOG.md)

## License

BSD 3-Clause. See [LICENSE](LICENSE).
