Skip to content

README.md

Latest commit

 

History

History
277 lines (200 loc) · 8.64 KB

README.md

File metadata and controls

277 lines (200 loc) · 8.64 KB

Black circle with PyIRI logo of two snakes marking the EIA

PyIRI

PyPI Package latest release Build Status Documentation Status DOI Coverage Status

PyIRI is a modern Python implementation of the International Reference Ionosphere (IRI) model.
It provides fast, global, and altitude‑dependent evaluation of ionospheric parameters using a new spherical harmonics (SH) architecture.
The model supports multiple coordinate systems and efficiently evaluates all grid points and time frames simultaneously.

Highlights

  • Spherical harmonics framework for: foF2, hmF2, B0, B1 and foEs
  • Supports GEO, QD, and MLT coordinate systems
  • Compatible with both the new SH‑based and legacy URSI/CCIR coefficient models
  • Modular and fully in Python — no external dependencies or Fortran libraries

Installation

Install from PyPI:

pip install PyIRI

Or clone and install from the GitHub repository:

git clone https://github.com/victoriyaforsythe/PyIRI.git
cd PyIRI
pip install .

For more details and usage examples, see the Jupyter tutorials.

Example: Monthly Mean Ionospheric Parameters

PyIRI computes monthly mean ionospheric parameters for a user‑defined grid. The evaluation occurs simultaneously across all grid points and for all desired Universal Time (UT) frames.

import numpy as np
import PyIRI
import PyIRI.edp_update as ml
import PyIRI.sh_library as sh

Define year and month of interest:

year = 2020
month = 4

Create any horizontal grid (regular or irregular, global or regional). Grid arrays must be flattened into 1‑D NumPy arrays:

dlon = 5
dlat = 5
alon_2d, alat_2d = np.mgrid[-180:180 + dlon:dlon, -90:90 + dlat:dlat]
alon = alon_2d.ravel()
alat = alat_2d.ravel()

Create a time array in decimal hours:

hr_res = 1
aUT = np.arange(0, 24, hr_res)

Compute F2, F1, and E‑region parameters using the new spherical harmonics coefficients:

hmF2_model = 'SHU2015'   # Also available: 'AMTB2013', 'BSE1979'
foF2_coeff = 'URSI'      # Also available: 'CCIR'
coord = 'GEO'            # Also available: 'QD' for Quasi-Dipole Lon and Quasi-Dipole Lat inputs
                         #                 'MLT' for MLT and Quasi-Dipole Lat inputs

f2, f1, e_peak, sun, mag = sh.IRI_monthly_mean_par(
    year, month, aUT, alon, alat,
    coeff_dir=None,
    foF2_coeff=foF2_coeff,
    hmF2_model=hmF2_model,
    coord=coord)

Alternatively, the original URSI or CCIR climatological coefficients can be used:

ccir_or_ursi = 0  # 0 = CCIR, 1 = URSI
f2, f1, e_peak, es_peak, sun, mag = ml.IRI_monthly_mean_par(
    year, month, aUT, alon, alat,
    PyIRI.coeff_dir, ccir_or_ursi)

Example: Daily Ionospheric Parameters (F10.7 Driven)

PyIRI also computes daily ionospheric parameters, interpolated in both time and solar activity. The user provides the F10.7 index for the day of interest.

Define the F10.7 index in solar flux units (sfu):

F107 = 100

Create altitude array in km:

aalt = np.arange(90, 1000, 1)

Define day of interest:

day = 1

Run PyIRI (with spherical harmonic coefficients):

F2, F1, E, sun, mag, EDP = sh.IRI_density_1day(
    year, month, day, aUT, alon, alat, aalt, F107,
    coeff_dir=None,
    foF2_coeff=foF2_coeff,
    hmF2_model=hmF2_model,
    coord=coord)

Or, use the original CCIR/URSI version for compatibility:

f2, f1, e_peak, es_peak, sun, mag, edp = ml.IRI_density_1day(
    year, month, day, aUT, alon, alat, aalt, F107,
    PyIRI.coeff_dir, ccir_or_ursi)

Total Electron Content (TEC)

PyIRI does not calculate the Total Electron Content (TEC) automatically because altitude spacing affects accuracy. The TEC can be derived from the electron density profile (EDP) using:

TEC = PyIRI.main_library.edp_to_vtec(edp, aalt, min_alt=0.0, max_alt=202000.0)

Example: Single‑Location Diurnal Variation

To evaluate parameters at a single location, provide scalar longitude and latitude values:

alon = 10.
alat = 20.

Run PyIRI (with spherical harmonic coefficients):

F2, F1, E, sun, mag, EDP = sh.IRI_density_1day(
    year, month, day, aUT, alon, alat, aalt, F107,
    coeff_dir=None,
    foF2_coeff=foF2_coeff,
    hmF2_model=hmF2_model,
    coord=coord)

Example: Sporadic E

Sporadic E fields require more spherical harmonic coefficients and were therefore decoupled from the main call:

Run PyIRI Es (with spherical harmonic coefficients) for solar min and solar max:

Es = sh.sporadic_E_monthly_mean(year,
                                month,
                                aUT,
                                alon,
                                alat,
                                coeff_dir=None,
                                coord='GEO')

Run PyIRI Es (with spherical harmonic coefficients) for a given day and F10.7 input:

Es = sh.sporadic_E_1day(year,
                        month,
                        day,
                        aUT,
                        alon,
                        alat,
                        F107,
                        coeff_dir=None,
                        coord='GEO')

Tutorials

Comprehensive Jupyter notebooks are available in docs/tutorials:

  • Mean_monthly_parameters.ipynb
  • Daily_parameters.ipynb
  • Single_location.ipynb
  • Coordinate_Transformation.ipynb
  • PyIRI_year_run.ipynb
  • Generate_Apex_Coefficients.ipynb

Routine Package Maintenance: IGRF Updates

The PyIRI model relies on an accurate representation of the Earth's magnetic field for the spherical harmonics library. PyIRI uses the quasi-dipole (QD) magnetic coordinate system. These coordinates, which ultimately derive from the International Geomagnetic Reference Field (IGRF) coefficients, are computed by apexpy and then fit via Spherical Harmonics (SH) for easy reference. When a new IGRF definition is released, the previous set of IGRF coefficient files (especially the last five years, which are an extrapolation) become obsolete. To maintain PyIRI when a new IGRF definition comes out, maintainers must first ensure that apexpy has been updated to incorporate the latest IGRF coefficients. Once apexpy is current, it must be rerun to generate a new apex.nc coefficient file via SH fits. This process synchronizes PyIRI's magnetic coordinate grids with the updated IGRF and ensures the model remains accurate in MLT–QDLat space for the new epoch.

Citation

If you use PyIRI in your research, please cite:

Forsythe, V. (2025). PyIRI: Python implementation of the IRI model using spherical harmonics. Zenodo. https://doi.org/10.5281/zenodo.8235173

Servan-Schreiber, N., Forsythe, V., et al. (2025). A Major Update to the PyIRI model. Space Weather, submitted.