gri-iono 0.2.1

No project description provided

Iono (Ionospheric Corrections)

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

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."

Installation

pip install gri-iono

For development:

git clone https://gitlab.com/geosol-foss/python/gri-iono.git
cd gri-iono
. .init_venv.sh

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.

Experimental/Development Models

• ai_bent_ionospheric_correction: An experimental simplified version of the Bent model optimized for speed at the cost of accuracy. Not recommended for production use.
• josh_bent_model: The original Bent model implementation that served as the starting point for optimization work on the current bent model. Retained for reference and validation.

Usage

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

• angular_correction: Angular deflection in radians (positive is away from zenith)
• time_delay: Excess propagation time in seconds

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, 20200000.0],  # lat, lon, alt (deg, deg, m)
    collector_xyz=[...],                      # 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, 20200000.0],
    collector_xyz=[...],
    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, 20200000.0],
    collector_xyz=[...],
    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, 20200000.0],
    collector_xyz=[...],
    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.