ionotrace

High-performance ionospheric ray tracing engine in Rust. Implements the OT 75-76 algorithm for simulating HF radio wave propagation through the Earth's ionosphere.

Compiles to WebAssembly for in-browser use, or runs natively as a Rust library.

Features

Full 3D ray tracing — Hamilton's equations in spherical coordinates (r, θ, φ)
RK4 / Adams-Moulton adaptive integrator with automatic step-size control
6 electron density models — Chapman, ELECT1, Linear, Quasi-Parabolic, Variable Chapman, Dual Chapman
4 magnetic field models — Dipole, Constant, Cubic, IGRF-14 (degree-13 spherical harmonics)
4 refractive index models — Full/partial Appleton-Hartree with/without collisions and magnetic field
6 perturbation models — Torus, Trough, Shock, Bulge, Exponential
3 collision frequency models — Double-exponential, Constant, Single-exponential
Multi-hop propagation with ground reflection
Zero-allocation complex arithmetic for inner-loop performance
WASM bindings via wasm-bindgen (behind cfg(target_arch = "wasm32"))

Usage (Rust)

use ionotrace::{TraceConfig, ModelParams};
use ionotrace::params::{ElectronDensityModel, RayMode};

// Simple: 10 MHz, 20° elevation, all defaults
let result = TraceConfig::new(10.0, 20.0).trace();
println!("Max height: {:.2} km", result.max_height);

// Customized: dual-layer Chapman, O-mode, specific frequency
let config = TraceConfig {
    ray_mode: RayMode::Ordinary,
    azimuth_deg: 45.0,
    params: ModelParams {
        ed_model: ElectronDensityModel::DualChapman,
        fc: 8.0,
        ..ModelParams::default()
    },
    ..TraceConfig::new(15.0, 30.0)
};
let result = config.trace();

Usage (WASM)

When compiled with wasm-pack build --target web, the crate exposes a trace_fan_wasm(json) function that accepts and returns JSON strings:

import init, { trace_fan_wasm } from './pkg/ionotrace.js';
await init();

const result = JSON.parse(trace_fan_wasm(JSON.stringify({
    freq_mhz: 10.0,
    ray_mode: -1,
    elev_min: 5,
    elev_max: 80,
    elev_step: 2,
    fc: 10.0,
    hm: 250,
    sh: 100,
})));

console.log(`Traced ${result.n_rays} rays in ${result.elapsed_ms} ms`);

Building

# Native
cargo build --release

# WASM (requires wasm-pack)
wasm-pack build --target web --out-dir ../../apps/frontend/pkg

# Tests
cargo test

Algorithm

Solves Hamilton's equations for the ray path through the ionosphere:

H = ½(c²k²/ω² - n²)

where n² is the complex refractive index from the Appleton-Hartree formula. The integrator uses 4th-order Runge-Kutta with Adams-Moulton predictor-corrector and adaptive step-size control.

Based on: A Versatile Three-Dimensional Ray Tracing Computer Program for Radio Waves in the Ionosphere, R. M. Jones & J. J. Stephenson, OT Report 75-76 (1975). PDF

License

MIT — see LICENSE for details.

ionotrace 0.2.0