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.

Data Files

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

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. The raw ITU-R grids are too large to include directly because crates.io limits .crate archive size.

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"

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:

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.