PyIRI

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

---

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.