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.

For published-package use, the recommended path is to enable the data feature:

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

With features = ["data"], no runtime configuration is required. The build script first uses local data/ files when they are present; otherwise it downloads a source archive, extracts data/**, and embeds those bytes into the compiled crate. The default download URL points at the itu-rs-data-v1.zip GitHub Release asset and verifies its pinned SHA256.

The raw ITU-R grids are too large to include directly in the crates.io package because crates.io limits the size of uploaded .crate archives.

Override it with ITU_RS_DATA_URL, use a local archive with ITU_RS_DATA_ARCHIVE, set ITU_RS_DATA_CACHE for a persistent download cache, and set ITU_RS_DATA_SHA256 to require a different checksum.

The feature is intentionally opt-in because it makes builds network-dependent when local data is unavailable and increases the final binary size by roughly the compressed grid data size.

Manual data directory

If you do not want automatic data embedding, 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.