Metadata-Version: 2.4
Name: gri-iono
Version: 0.2.4
Summary: Ionospheric delay and angular correction models for trans-ionospheric signal propagation
Project-URL: Homepage, https://geosolresearch.com
Project-URL: Repository, https://gitlab.com/geosol-foss/python/gri-iono
Project-URL: Issues, https://gitlab.com/geosol-foss/python/gri-iono/-/issues
Project-URL: Changelog, https://gitlab.com/geosol-foss/python/gri-iono/-/releases
Author-email: GeoSol Research Inc <contact@geosolresearch.com>
License-Expression: MIT
License-File: LICENSE
Keywords: IRI,NeQuick,delay,ionosphere,propagation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.12
Requires-Dist: gri-utils>=0.3.3
Requires-Dist: numpy>=2.3.3
Requires-Dist: pyiri>=0.1.4
Requires-Dist: scipy>=1.16.2
Description-Content-Type: text/markdown

[![GeoSol Research Logo](https://geosolresearch.com/logos/foss_logo.png "GeoSol Research")](https://geosolresearch.com)

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

## Installation

```bash
pip install gri-iono
```

For development:

```bash
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

- **`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:

```python
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:

```python
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:

```python
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:

```python
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](https://gitlab.com/geosol-foss/python/gri-iono/-/blob/main/.docs_other_projects.md) we are building and maintaining.

## License

MIT License. See [LICENSE](https://gitlab.com/geosol-foss/python/gri-iono/-/blob/main/LICENSE) for details.
