pglis 1.0.1

PGLIS solar-modulated galactic cosmic-ray flux model

The PgLis model

PgLis is a model developed to forecast the flux of solar-modulated galactic cosmic-rays near Earth.

We modelled the different transport parameters that cosmic rays experience as they traverse the heliosphere to arrive at Earth (article link available soon), parametrised them as functions of solar activity, using the widely available sunspot number as a proxy (see NOAA), which we delay according to Tomassetti et al. (2022) to account for transport time.

This allows us to estimate the fluxes of cosmic nuclei near Earth, from Hydrogen to Nickel, as they evolve with solar activity.

This package is a Python implementation that interpolated between the pre-computed tables available in Zenodo. It downloads the data from Zenodo and the sunspot numbers from NOAA.

Flux model for both solar magnetic polarities, for cosmic hydrogen.

Scientific background

The modulation of galactic cosmic rays, driven by the evolution of the heliospheric magnetic field, strongly influences the intensity of cosmic rays reaching near-Earth space. Characterizing this process is crucial both for advancing our understanding of cosmic ray transport and for assessing radiation exposure and related hazards in space environments.

Here we present the PgLis model, a newly developed forecasting framework built upon our previous work, designed for the long-term forecasting of galactic cosmic-ray fluxes.

The model is the result of a collaboration between the Università degli Studi di Perugia (Pg) and the Laboratório de Instrumentação e Física Experimental de Partículas in Lisbon (Lis), and is based on a numerical description of charged-particle transport in the heliosphere and its dependence on solar activity.

The PgLis model has been validated using multi-species flux measurements from space-based instruments such as PAMELA, AMS-02, and ACE. Its strategy is based upon Hilbert-Huang transform filtering and cross-correlation between delayed solar proxies and effective model parameters.

It demonstrates a demonstrably good performance across a broad multichannel and multi-species testing dataset, spanning different energy ranges and solar phases. These advancements enhance its applicability to space radiation monitoring and forecasting. Furthermore, when coupled with solar-proxy forecasting models, PgLis enables decadal-scale predictions of galactic cosmic-ray fluxes, thereby supporting long-term planning and radiation-risk assessment for future space missions.

Usage examples

More examples can be found in tutorial.ipynb.

Getting the flux for a given time

# setup model
model = pglis.solar_mod()

# defining the time - 2001/06/01
t = datetime.datetime(2001, 6, 1).timestamp()

# getting the flux as a dataframe
df = model.get_dataframe_flux_vs_energy(Z=1, time=t)

Installation

From GitHub

To install this package you can run the following commands:

# download the repository
git clone [e-mail]:davidpelosi21/PgLis.git

# install the package
python3 -m pip install .

From PyPi

python3 -m pip install pglis

Uninstalling the package

To remove the package you must first remove the data, this can be done by running a command that comes bundled with the package:

pglis-cleanup

To uninstall the package, regardless of the data, you can simply run the following command:

python3 -m pip uninstall pglis

Authors

David Pelosi^1,2, Fernando Barão^3,4, Bruna Bertucci^1,2, Emanuele Fiandrini^1,2, Miguel Orcinha² and Nicola Tomassetti^1,2

¹ Università degli Studi di Perugia, Perugia 06100, Italy
² INFN - Perugia, Perugia 06100, Italy
³ Laboratório de Instrumentação e Física Experimental de Partículas, Lisboa 1000, Portugal
⁴ Instituto Superior Técnico, Lisboa 1049, Portugal

Maintainers

David Pelosi^1,2 E-mail
Miguel Orcinha² E-mail

How to cite

This package was created to simplify and systematise the access to the flux model presented in the article Pelosi et al. (2026) The PgLis Model: A Tool for Long-Term Galactic Cosmic Ray Forecasting, Phys. Rev. D, (under review).

The heatmaps with the discretised model used in this package can be found in Zenodo.

Acknowledgements

This work as been developped with support from Agenzia Spaziale Italiana (ASI), under ASI-UniPG 2019-2-HH.0, ASI-INFN 2019-19 HH.0, its amendment 2021-43 HH.0, the Italian Ministry of University and Research (MUR) through the program "Dipartimenti di Eccellenza 2023-2027" and Fundação para a Ciência e Tecnologia (FCT) under grant 2024.00992.CERN, Portugal.