itu-rs

itu-rs is a Rust implementation of selected ITU-R P-series atmospheric propagation routines, ported from python-itu-r for fast Earth-space slant-path attenuation calculations.

This first crate is intentionally scoped: it supports the propagation features needed by the current Rust port, not the full python-itu-r API surface.

Data Files

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

The crates.io package excludes those grids because the compressed data package is larger than the crates.io .crate upload limit. For published-package use, set ITU_RS_DATA_DIR to a directory containing the same itur/data layout copied from python-itu-r:

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

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(())
}

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:

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

Validation

Current local checks:

cargo check
cargo test
cargo test --doc

Before publishing, also run:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo package --allow-dirty

The local source checkout packages to a small crates.io-compatible .crate by excluding data/**. Keep the data directory in the repository for development and parity testing, but do not include it in the crates.io upload unless the registry size limit is handled another way.

Attribution

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