Tropo (Tropospheric Corrections)

Tropospheric delay and angular correction calculations based on ITU-R 2019 methods and ERA5 reanalysis data. Requires Python 3.12+.

Overview

gri-tropo provides tools for calculating tropospheric corrections and accessing atmospheric refractivity data:

• dgs: Calculate tropospheric angle and time corrections using ITU-R 2019 methods
• nsur: Access surface refractivity data from ERA5 reanalysis
• refht: Access reference height data (scale height of exponential refractivity decay)

Mathematical Background

The troposphere (0-~12 km altitude) causes signal delay and angular bending due to atmospheric refractivity. Unlike the ionosphere, tropospheric refraction is non-dispersive (frequency-independent) and affects all electromagnetic signals equally.

The refractivity profile is modeled as an exponential decay:

N(h) = N_sur * exp(-h / h_ref)

where N_sur is the surface refractivity in N-units, h is altitude in km, and h_ref is the reference (scale) height in km. The signal delay and angular bending are computed by integrating the refractivity along the propagation path using ray-tracing methods.

N_sur values typically range from 250-400 N-units and vary with latitude, season, and local weather. The reference height h_ref is typically 6-8 km.

References:

• ITU-R P.453. "The radio refractive index: its formula and refractivity data."
• ITU-R P.834. "Effects of tropospheric refraction on radiowave propagation."
• Bean & Dutton (1966). "Radio Meteorology." National Bureau of Standards Monograph 92.

Installation

pip install gri-tropo

For development:

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

Usage

DGS - Tropospheric Corrections

Calculate tropospheric angle and time corrections for signal propagation:

from gri_tropo.dgs import dgs_tropo_corrections
import numpy as np

# Define emitter location [lat, lon, alt_km]
emitter_lla = np.array([40.0, -105.0, 1.5])

# Define collector position in ECEF XYZ (meters)
collector_xyz = np.array([1000000.0, -5000000.0, 4000000.0])

# Calculate corrections with custom atmospheric parameters
cone_corr, time_corr = dgs_tropo_corrections(
    emitter_lla,
    collector_xyz,
    n_sur=315.0,    # Surface refractivity (N-units)
    ref_ht=7.35     # Reference height (km)
)

# cone_corr: Angular deflection correction (radians)
# time_corr: Time delay correction (seconds)

NSur - Surface Refractivity Data

Access hourly surface refractivity data from ERA5:

from gri_tropo.nsur import NSur
from datetime import datetime

# Initialize with data directory
nsur = NSur("./data/n_sur")

# Get value for specific location and time
value = nsur.get_n_sur(
    lat=40.0,
    lon=254.0,  # Longitude 0-359 degrees East
    dt=datetime(2025, 3, 15),
    hour=12
)

# Get values for multiple coordinates efficiently
coords = [
    (40.0, 254.0, datetime(2025, 3, 15), 12),
    (35.0, 250.0, datetime(2025, 3, 15), 14),
]
values = nsur.get_all_n_surs(coords)

RefHt - Reference Height Data

Access reference height data (scale height for exponential refractivity decay):

from gri_tropo.refht import RefHt
from datetime import datetime

# Initialize with data directory
refht = RefHt("./data/ref_ht")

# Get value for specific location and date
value = refht.get_ref_ht(
    lat=40.0,
    lon=254.0,  # Longitude 0-359 degrees East
    dt=datetime(2025, 3, 15)
)

# Get values for multiple coordinates efficiently
coords = [
    (40.0, 254.0, datetime(2025, 3, 15)),
    (35.0, 250.0, datetime(2025, 3, 16)),
]
values = refht.get_all_ref_hts(coords)

Data Download and Processing

The NPZ data files required by this package are generated by the separate gri-tropo-data package. This separation keeps gri-tropo lightweight with minimal dependencies for users who just need tropospheric corrections.

For information on downloading ERA5 data and processing it to generate n_sur and ref_ht datasets, see the gri-tropo-data repository.

Dependencies

• gri-utils: Coordinate conversions and geodetic utilities
• 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.