itu-rs

itu-rs is a Rust implementation of selected ITU-R P-series atmospheric propagation routines, ported from python-itu-r for Earth-space slant-path attenuation calculations that run 30-50x faster than the Python implementation in benchmarked workloads.

• Data Files
  • Automatic Data Download
  • Git Repo Checkout
  • Manual Data Directory
• Python Package
• Example
• Supported Coverage
• Benchmarks
• API
• Attribution

Data Files

itu-rs requires ITU-R data grids, which are too large to include directly because crates.io limits uploaded .crate archive size. The preferred way to automatically get the data files is by enabling the data feature.

Automatic Data Download

For published-package use, enable the data feature:

[dependencies]
itu-rs = { version = "1", features = ["data"] }

With features = ["data"], no runtime configuration is required: the build uses local data/ files when present, otherwise downloads and embeds the verified data archive.

Git Repo Checkout

The working repository checkout includes the required ITU-R grids under itu-rs/data, so local development is self-contained.

Manual Data Directory

If you do not want automatic data download, set ITU_RS_DATA_DIR to a directory containing the same itur/data layout copied from python-itu-r.

Unix shells:

export ITU_RS_DATA_DIR=/path/to/ITU-Rpy/itur/data

Windows PowerShell:

$env:ITU_RS_DATA_DIR = "C:\path\to\ITU-Rpy\itur\data"

Python Package

itu-rs is also available as an optional Python package backed by the same Rust implementation:

uv add itu-rs
# or: pip install itu-rs

Python imports use an underscore because Python module names cannot contain hyphens:

import itu_rs

attenuation = itu_rs.atmospheric_attenuation_slant_path(
    45.4215,
    -75.6972,
    12.0,
    30.0,
    0.1,
    1.2,
)

print(f"{attenuation.total_db:.6f} dB")

Published wheels embed the ITU-R data grids, so normal Python installs do not require ITU_RS_DATA_DIR.

For local Python binding development, use uv:

uv run --project python --group dev maturin develop --manifest-path python/Cargo.toml
uv run --project python --group dev pytest python/tests

Example

Compute the full atmospheric attenuation contribution set for one Earth-space slant path:

use itu_rs::{atmospheric_attenuation_slant_path, SlantPathOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let attenuation = atmospheric_attenuation_slant_path(
        45.4215,   // latitude, degrees
        -75.6972,  // longitude, degrees
        12.0,      // frequency, GHz
        30.0,      // elevation, degrees
        0.1,       // time percentage
        1.2,       // antenna diameter, m
        SlantPathOptions::default(),
    )?;

    println!("{:.6} dB", attenuation.total_db);
    Ok(())
}

Sweep multiple elevation angles for one fixed site and link configuration:

use itu_rs::{atmospheric_attenuation_slant_path_many, SlantPathOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let elevations = [5.0, 17.5, 45.0, 89.0];
    let attenuation = atmospheric_attenuation_slant_path_many(
        45.4215,
        -75.6972,
        12.0,
        &elevations,
        0.1,
        1.2,
        SlantPathOptions::default(),
    )?;

    for (elevation, result) in elevations.iter().zip(attenuation.iter()) {
        println!("{elevation:5.1} deg: {:.6} dB", result.total_db);
    }

    Ok(())
}

Use exact gaseous attenuation or disable individual components through SlantPathOptions:

use itu_rs::{atmospheric_attenuation_slant_path, SlantPathOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = SlantPathOptions {
        exact: true,
        include_rain: false,
        include_clouds: false,
        ..SlantPathOptions::default()
    };

    let attenuation = atmospheric_attenuation_slant_path(
        10.0, 20.0, 18.0, 17.5, 0.7, 0.8, options,
    )?;

    println!("gas + scintillation: {:.6} dB", attenuation.total_db);
    Ok(())
}

Use recommendation helper APIs directly when only one part of the propagation model is needed:

use itu_rs::{rainfall_rate_mmh, surface_month_mean_temperature_k, zero_isotherm_height_km};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let lat = 45.4215;
    let lon = -75.6972;

    let january_temp_k = surface_month_mean_temperature_k(lat, lon, 1)?;
    let rain_rate_mmh = rainfall_rate_mmh(lat, lon, 0.1)?;
    let h0_km = zero_isotherm_height_km(lat, lon)?;

    println!("{january_temp_k:.2} K, {rain_rate_mmh:.2} mm/h, {h0_km:.2} km");
    Ok(())
}

Supported Coverage

Benchmarks

The current comparison benchmark was run from the source workspace on May 8, 2026 using the existing Python parity harness against python-itu-r and the Rust port. Results are means over repeated runs.

Run the Rust-only Criterion benchmarks with:

cargo bench

API

The primary public calls are:

Additional scalar APIs expose the implemented recommendation pieces directly:

SlantPathOptions::default() matches the default slant-path configuration used by the port. Set exact = true to use exact gaseous attenuation.

Attribution

This crate contains a Rust port of selected functionality from python-itu-r, which is MIT licensed. See NOTICE.md.