iri20py 0.0.3

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\ucrt\bin (defaults to C:\msys64\ucrt\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 ucrt\bin (defaults to C:\msys64\ucrt\bin)
  • Click "Ok" on the environment variable windows to save the changes.

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},
}