iri20py 0.0.5

Python bindings for IRI-2020 model

IRI-2020 Python Wrapper

iri20py is a wrapper around the IRI-2020 empirical model.

This repository includes a version of the IRI-2020 model where the call signatures have been modified for ease of integration with Python. The integration is achieved by means of a FORTRAN shim (irishim.f90) that is compiled into a module using F2PY. Data files associated with IRI-2020 are included in the data folder and are available at runtime. The wrapper automatically retrieves the latest available ig_rz.dat and apf107.dat files on import.

Prerequisites

A Fortran compiler is REQUIRED.

Linux

Ensure that you have the following development packages installed:

• build-essential (for gcc, g++, make, etc.)
• gfortran (Fortran compiler)

macOS

Ensure that you have the Xcode Command Line Tools installed. You can install them by running:

xcode-select --install

Install homebrew if you haven't already, and then install gfortran:

brew install gfortran

Note: For macOS Big Sur and above, you may need to add the following line to your environment script (~/.zshrc if using ZSH, or the relevant shell init script):

export LIBRARY_PATH="$LIBRARY_PATH:/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib"

Then reopen the terminal. This fixes the issue where -lSystem fails for gfortran.

Windows (amd64 or x86_64 targets)

On Windows, MSYS2 is the preferred distribution for installing the Fortran compiler toolchain (for GNU Compiler Collection).

• Install MSYS2. Note the directory where MSYS2 was installed (defaults to C:\msys64) [referred to as MSYS_INSTALL_DIR]. It is not recommended to change this directory.
• Launch the MSYS2 terminal (MSYS2 MSYS application on the start menu)
• Update MSYS2 environment (assuming fresh install):

  pacman -Syu # Restart the terminal
  pacman -Su  # Update packages
  

• Install the GNU Compiler Collection:

  pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain mingw-w64-ucrt-x86_64-gcc-fortran
  

• Add MSYS_INSTALL_DIR\ucrt64\bin (defaults to C:\msys64\ucrt64\bin) to PATH:
  • Search for env in the Start menu,
  • Select "Edit the system environment variables",
  • Click "Environment Variables",
  • Double click 'Path' under 'User variables for USER'
  • Click "New"
  • Type in, or paste the full path to ucrt64\bin (defaults to C:\msys64\ucrt64\bin)
  • Click "Ok" on the environment variable windows to save the changes.
• Continue with installation instructions for the Python packages below, in a new, regular terminal (e.g. Command Prompt or PowerShell with Python installed).

[!NOTE] Change the toolchain names accordingly for Windows arm64. This platform has not been tested and is not officially supported.

Installation

From PyPI

pip install iri20py

From GitHub

pip install iri20py@git+https://github.com/sunipkm/iri20py

Usage

Quick Test

On the command line, execute Iri20Test. This should produce a plot of noon and midnight electron density profiles.

Python

from iri20py import Iri2020, alt_grid
from datetime import datetime, UTC
import matplotlib.pyplot as plt

# Instantiate the model
iri = Iri2020()
# Note: iri is a singleton (thread safety with FORTRAN)
# Evaluate the model
_, ds = iri.evaluate(
    datetime(2022, 3, 12, 0, 0, 0, tzinfo=UTC),
    40, -70,
    alt_grid()
)

# ds is an xarray Dataset
# Plot electron density profile
ds.Ne.plot(y='alt_km')
plt.show()

Output Dataset Format

• Coordinates
  • Altitude (alt_km): Altitude in km
• Data Variables (as a function of altitude)
  • Electron density (Ne) in cm^-3
  • Electron temperature (Te) in K
  • Ion temperature (Ti) in K
  • O⁺, H⁺, He⁺, O₂⁺, NO⁺, N⁺ and cluster ion densities (cm^-3)
• Attributes
  • settings: JSON string of settings (iri20py.Settings) used to evaluate the model.
  • date: ISO formatted date and time for which the model was evaluated.
  • lat and lon: Latitude and longitude for where the model was evaluated.
  • Additional attributes as returned in the OARR struct (refer to IRI-2020 documentation). These additional attributes are provided as JSON dictionaries containing a value, its unit, a longer name (long_name) and an associated description, if available.

The dataset is NetCDF4 compatible.

Example Plot

An example script to generate the following plot is available in the tests/test_iri2020.py file.

Citation

If you use this code in your work, please cite the repository:

@software{sunipkm_iri20py_2025,
  author       = {Sunip K. Mukherjee},
  title        = {{iri20py}: A Python Wrapper for the IRI-2020 Empirical Model},
  month        = nov,
  year         = 2025,
  publisher    = {GitHub},
  version      = {v0.0.2},
  doi          = {https://zenodo.org/badge/latestdoi/1089134543},
  url          = {https://github.com/sunipkm/iri20py},
}