Iono (Ionospheric Corrections)

Ionospheric delay and angular correction models for trans-ionospheric signal propagation. Requires Python 3.12+.

Overview

gri-iono implements several ionospheric models for calculating signal delays and angular deflections caused by the ionosphere. Each model returns a tuple of (angular_correction, time_delay) representing the angular deflection in radians and the excess propagation time in seconds.

Mathematical Background

The ionosphere is a region of the atmosphere (~60-1000 km altitude) where solar radiation ionizes atmospheric gases, creating free electrons that affect electromagnetic wave propagation. The ionospheric delay is proportional to the Total Electron Content (TEC) along the signal path and inversely proportional to the square of the carrier frequency:

delay_s = (40.3 / c) * TEC / f^2

where TEC is in electrons/m^2, f is the carrier frequency in Hz, and c is the speed of light. This dispersive property means lower frequencies experience greater delay -- a characteristic exploited by dual-frequency GNSS receivers to estimate and remove the ionospheric error.

The electron density profile varies with solar activity (F10.7 solar flux index), local time, season, geomagnetic latitude, and solar cycle phase. Each model in this library approximates this profile differently.

References:

• Bent et al. (1972). "The Development of a Highly-Successful Worldwide Empirical Ionospheric Model."
• Nava et al. (2008). "A new version of the NeQuick ionosphere electron density model." Journal of Atmospheric and Solar-Terrestrial Physics.
• ITU-R P.531. "Ionospheric propagation data and prediction methods required for the design of satellite services and systems."

Documentation

The wheel ships its documentation inside the package, in gri_iono/docs/, so it is available wherever the package is installed:

• overview.md -- the common contract, choosing a model, their inputs and approximations, and batches
• api_summary.md -- every public function and signature (generated)

Print the directory with python -c "import gri_iono, pathlib; print(pathlib.Path(gri_iono.__file__).parent / 'docs')". Every example in those files is run by the test suite.

Installation

pip install gri-iono

For development:

git clone https://gitlab.com/geosol-foss/python/gri-iono.git
cd gri-iono
uv sync

Available Ionospheric Models

Bent Model (bent_ionospheric_correction)

The Bent model is a classical empirical ionospheric model developed in the 1970s that uses Chapman-like electron density profiles with parameters derived from solar activity and geomagnetic conditions.

IRI Model (iri_ionospheric_correction)

The International Reference Ionosphere (IRI) is the internationally recognized empirical standard for ionospheric parameters, maintained by COSPAR and URSI. It provides the most comprehensive climatological representation of the ionosphere.

NeQuick2 Model (nequick2_ionospheric_correction)

NeQuick2 is a three-dimensional ionospheric electron density model developed by ICTP Trieste and the University of Graz, designed for trans-ionospheric propagation applications using a three-layer (E, F1, F2) structure.

NeQuickG Model (nequickg_ionospheric_correction)

NeQuickG is the Galileo-adapted version of NeQuick, designed to work with broadcast ionospheric coefficients (ai0, ai1, ai2) transmitted by Galileo satellites for real-time ionospheric correction.

Usage

All ionospheric correction functions return a tuple of (angular_correction, time_delay) where:

• angular_correction: Elevation-angle correction at the source end of the path, in radians (negative is toward zenith)
• time_delay: One-way excess propagation time in seconds

The source is the low end of the path: elevation is measured at the source toward the collector. For a ground receiver tracking a GNSS satellite, pass the receiver as source_lla and the satellite as collector_xyz. Bent raises ValueError if the collector is at or below the source's horizon.

bent_ionospheric_correction

High-level interface with automatic solar flux derivation from date:

from gri_iono import bent_ionospheric_correction
from datetime import datetime

angular, delay = bent_ionospheric_correction(
    source_lla=[40.0, -105.0, 1600.0],        # ground receiver: lat, lon, alt (deg, deg, m)
    collector_xyz=[...],                      # satellite ECEF position (m)
    frequency_hz=1575.42e6,                   # L1 frequency
    time=datetime(2024, 6, 15, 12, 0, 0),     # UTC time
)

iri_ionospheric_correction

Grid-based IRI model with configurable resolution:

from gri_iono import iri_ionospheric_correction
from datetime import datetime

angular, delay = iri_ionospheric_correction(
    source_lla=[40.0, -105.0, 1600.0],  # ground end
    collector_xyz=[...],                # satellite ECEF (m)
    frequency_hz=1575.42e6,
    solar_flux=150.0,           # F10.7 solar flux units
    time=datetime(2024, 6, 15, 12, 0, 0),
    grid_resolution=2.0,        # lat/lon grid spacing (degrees)
    alt_resolution=5.0,         # altitude grid spacing (km)
    num_path_points=200,        # integration points along ray
)

nequick2_ionospheric_correction

Full NeQuick2 model using solar flux:

from gri_iono import nequick2_ionospheric_correction

angular, delay = nequick2_ionospheric_correction(
    source_lla=[40.0, -105.0, 1600.0],  # ground end
    collector_xyz=[...],                # satellite ECEF (m)
    frequency_hz=1575.42e6,
    solar_flux=150.0,      # F10.7 solar flux units
    utc_hours=12.5,        # UTC time as decimal hours
    month=6,               # month (1-12) for seasonal variation
)

nequickg_ionospheric_correction

NeQuickG model using Galileo broadcast coefficients:

from gri_iono import nequickg_ionospheric_correction

angular, delay = nequickg_ionospheric_correction(
    source_lla=[40.0, -105.0, 1600.0],  # ground end
    collector_xyz=[...],                # satellite ECEF (m)
    frequency_hz=1575.42e6,
    coefficients=(236.831641, 0.0, 0.0),  # ai0, ai1, ai2 from Galileo broadcast
    utc_hours=12.5,
    month=6,
)

Dependencies

• gri-utils: Coordinate conversions and physical constants
• numpy: Array operations
• scipy: Scientific computing

Other Projects

Current list of other GRI FOSS Projects we are building and maintaining.

License

MIT License. See LICENSE for details.