rustmatrix 2.1.1

Rust-backed T-matrix scattering for nonspherical particles (port of pytmatrix)

rustmatrix

Rust-backed T-matrix scattering for nonspherical particles. A drop-in replacement for the numerical core of pytmatrix, with substantially faster orientation averaging, parallel PSD integration, hydrometeor mixtures (HydroMix), and a full Doppler + polarimetric spectra engine (rustmatrix.spectra). Targets Python 3.9–3.13 via ABI3 wheels.

Existing code that uses pytmatrix.tmatrix.Scatterer, pytmatrix.psd, pytmatrix.radar, pytmatrix.refractive, or pytmatrix.tmatrix_aux ports over by changing imports — the APIs are identical where the physics matches.

Documentation

📖 Full docs: https://rustmatrix.readthedocs.io — install guide, 5-minute quickstart, 14 narrated tutorial notebooks, background theory, every public symbol.

🦀 Rust crate API: https://docs.rs/rustmatrix — for using the crate directly from Rust without the Python wrapper.

Install

pip install maturin
maturin develop --release      # from a checkout; builds the Rust extension

Requires a Rust toolchain (rustup default stable, 1.75+) and Python 3.9+. Pre-built wheels are planned for a future release; see the install guide for per-OS instructions.

Quickstart

from rustmatrix import Scatterer, radar
from rustmatrix.tmatrix_aux import wl_X, K_w_sqr, geom_horiz_back, dsr_thurai_2007
from rustmatrix.refractive import m_w_10C

s = Scatterer(radius=1.0, wavelength=wl_X, m=m_w_10C[wl_X],
              axis_ratio=1.0 / dsr_thurai_2007(2.0), Kw_sqr=K_w_sqr[wl_X])
s.set_geometry(geom_horiz_back)
print(f"Z_h = {radar.refl(s):.3f} mm⁶/m³")

Full walkthrough in the quickstart — sphere → raindrop → PSD in five minutes.

What's here

• Core T-matrix solver — Mishchenko's Fortran kernel, ported to Rust with the GIL released and rayon-parallel orientation averaging.
• HydroMix — combine multiple species (rain + ice + graupel) into a single Scatterer-shaped object.
• Doppler + polarimetric spectra — SpectralIntegrator with fall-speed presets, turbulence kernels (including Zhu 2023 particle-inertia), beam broadening, optional system noise.
• Pattern × scene integration — spectra.beam for non-uniform beams where the closed-form σ_beam breaks down.
• 14 reproducible tutorials covering published results from Kollias 2002 through Lakshmi 2024.

Performance

~6× on orientation averaging, ~10× on PSD tabulation, ~430× on orient_averaged_adaptive versus the Fortran pytmatrix backend. See the profiling how-to for how to measure on your own workload, and benches/bench_vs_pytmatrix.py for the head-to-head script.

Development

See the contributing guide for dev install, tests, style, and release flow.

pytest tests/                                 # Python (97 tests)
cargo test --lib --release                    # Rust crate
cargo fmt --all && cargo clippy --all-targets -- -D warnings

About

rustmatrix is developed by Steve Nesbitt, Professor in the Department of Climate, Meteorology & Atmospheric Sciences at the University of Illinois Urbana-Champaign. It grows out of instruction material for ATMS 410 — Radar Meteorology and accompanies the textbook Radar Meteorology: A First Course (Rauber & Nesbitt, 2018, Wiley).

See also myPSD — an interactive web frontend for radar simulation that drives rustmatrix under the hood.

License

MIT — see LICENSE.