metrust

MetPy-compatible calculation layer, powered by Rust.

150/150 metpy.calc functions implemented natively, plus 36 extras. Often faster on real-world workflows. Verified against MetPy on SounderPy, MetPy Cookbook examples, and synthetic global grids.

# The only change: swap the import
from metrust.calc import cape_cin, potential_temperature, vorticity
from metrust.units import units

Installation

pip install metrust

Optional GPU acceleration for supported calculations:

pip install "metrust[gpu]"

For plotting, xarray accessor, or Level2File (forwarded to MetPy):

pip install metrust metpy

What It Does

metrust implements every function in metpy.calc with a Rust backend compiled via PyO3. The Python API now matches MetPy's public metpy.calc signatures and is designed for MetPy-compatible units, return types, and runtime behavior on the shared calculation surface:

import numpy as np
from metrust.calc import (
    cape_cin, parcel_profile, bunkers_storm_motion,
    storm_relative_helicity, significant_tornado_parameter,
    vorticity, divergence, advection,
)
from metrust.units import units

# Sounding analysis (same API as MetPy)
p = np.array([1000, 925, 850, 700, 500, 300]) * units.hPa
T = np.array([25, 20, 15, 5, -15, -40]) * units.degC
Td = np.array([20, 15, 10, -5, -25, -50]) * units.degC

prof = parcel_profile(p, T[0], Td[0])
cape, cin = cape_cin(p, T, Td, prof)  # MetPy parcel_profile form works

# Grid kinematics with xarray (dx/dy inferred from lat/lon coords)
vort = vorticity(u_xarray, v_xarray)  # spherical metric corrections included
div = divergence(u_xarray, v_xarray)

Optional GPU Backend

Current users do not need to change anything. metrust stays on the Rust CPU backend by default.

When met-cu is installed, you can opt in explicitly:

import metrust.calc as mcalc

mcalc.set_backend("gpu")
theta = mcalc.potential_temperature(pressure, temperature)

with mcalc.use_backend("cpu"):
    theta_cpu = mcalc.potential_temperature(pressure, temperature)

The GPU backend currently targets the overlap where met-cu is already strong and verified:

• potential_temperature
• equivalent_potential_temperature
• dewpoint
• vorticity
• frontogenesis
• q_vector
• compute_cape_cin
• compute_srh
• compute_shear
• compute_pw
• composite_reflectivity_from_hydrometeors

Eligible dispatch currently focuses on scalar thermo plus uniform 2-D Cartesian grid workloads. Latitude/longitude-derived spacing, map-scale corrections, and other projection-aware cases fall back to the Rust CPU backend.

metrust still returns the same Pint/NumPy-facing API surface. Unsupported cases automatically stay on the Rust CPU path.

Speed

Benchmarked on real-world workflows (v0.3.3, validated by Codex against MetPy):

Current replay-harness snapshot from benches/bench_workflows.py on Windows 11 / Python 3.13.7: sounding 2.16x, grid diagnostics 8.53x, xarray workflow 1.46x.

Three-Way Benchmark: MetPy vs Rust vs CUDA

Real HRRR model output (40 isobaric levels, 1059 × 1799 grid, ~1.9 M points). RTX 5090, python tests/benchmark_gpu.py.

Scalar Thermodynamics (2D: 1059×1799)

Grid Kinematics (2D: 1059×1799)

1D Sounding (40 levels, single column)

Grid Composites (3D: 40×1059×1799 → 2D) — MetPy has no grid equivalents

Summary

★ = dispatches to CUDA when set_backend("gpu"). All other functions stay on Rust CPU regardless of backend setting.

Array Throughput

1M elements, 32-core Ryzen, rayon parallel:

Numerical Parity

Verified on the MetPy OUN 2011-05-22 12Z test sounding:

Uses MetPy-exact physical constants (Rd, Cp, Lv, epsilon), MetPy's CAPE integration formula (g * dTv/Tv * dz), pressure-weighted Bunkers algorithm, Newton solver for isentropic interpolation, and spherical metric tensor corrections for lat/lon grid kinematics.

Coverage

• 150/150 metpy.calc functions (100% coverage)
• 36 extras not in MetPy (grid composites, fire weather indices, etc.)
• 28 Rust array bindings with rayon parallelism and GIL release
• Pint application registry shared with MetPy (no cross-registry errors)
• xarray support with coordinate inference and shape preservation

What's Not Native

These forward to MetPy when installed:

• metrust.plots (matplotlib-based plotting)
• metrust.xarray (xarray accessor)
• metrust.io.Level2File (NEXRAD Level II)

Core metrust.calc stays native Rust by default with no required MetPy dependency. The shared calc surface now stays on native metrust implementations even when MetPy is installed. The optional met-cu backend is an explicit accelerator, not a requirement.

End-to-end replay benchmarks for sounding, grid, and xarray workflows live in benches/bench_workflows.py and the published docs page workflow-benchmarks.md.

Examples

See examples/ for complete drop-in demos:

• cookbook_sounding.py — MetPy Cookbook sounding analysis
• cookbook_500hpa_grid.py — MetPy Cookbook 500 hPa vorticity advection
• sounderpy_dropin.py — SounderPy-style full sounding pipeline

Testing

cargo test --workspace          # 1,186 Rust tests
python -m pytest tests/ -q      # 30 Python tests (including MetPy compatibility regression)

Documentation

Full docs at fahrenheitresearch.github.io/metrust-py, including:

• API reference for all 186 functions
• Beginner tutorials (Weather 101, soundings, grids, recipes)
• Migration guide from MetPy
• Performance benchmarks

License

MIT