ionotrace 0.2.0

High-performance ionospheric ray tracing engine — Hamilton's equations for HF radio propagation through a magnetized, collisional plasma
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# ionotrace

[![Crates.io](https://img.shields.io/crates/v/ionotrace.svg)](https://crates.io/crates/ionotrace)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)

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)

```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:

```javascript
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

```bash
# 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](https://www.ionolab.org/pubs/OT_Report_75_76.pdf)

## License

MIT — see [LICENSE](../../LICENSE) for details.