Metadata-Version: 2.4
Name: gri-tropo
Version: 0.2.3
Summary: Tropospheric delay and angular corrections based on ITU-R 2019 and ERA5 data
Project-URL: Homepage, https://geosolresearch.com
Project-URL: Repository, https://gitlab.com/geosol-foss/python/gri-tropo
Project-URL: Issues, https://gitlab.com/geosol-foss/python/gri-tropo/-/issues
Project-URL: Changelog, https://gitlab.com/geosol-foss/python/gri-tropo/-/releases
Author-email: GeoSol Research Inc <contact@geosolresearch.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ERA5,ITU-R,delay,refractivity,troposphere
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: ecmwf-datastores-client>=0.4.1
Requires-Dist: gri-utils>=0.3.4
Requires-Dist: netcdf4>=1.7.3
Requires-Dist: numpy>=2.3.3
Requires-Dist: scipy>=1.16.2
Requires-Dist: xarray>=2025.11.0
Description-Content-Type: text/markdown

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

# 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

```bash
pip install gri-tropo
```

For development:

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

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

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

```python
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](https://gitlab.com/geosol-foss/python/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](https://gitlab.com/geosol-foss/python/gri-tropo-data).

## Dependencies

- **gri-utils**: Coordinate conversions and geodetic utilities
- **numpy**: Array operations
- **scipy**: Scientific computing


## Other Projects

Current list of other [GRI FOSS Projects](https://gitlab.com/geosol-foss/python/gri-tropo/-/blob/main/.docs_other_projects.md) we are building and maintaining.

## License

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