wrf-rust

Rust-powered WRF post-processing with Python bindings. 96 diagnostic variables, built-in plotting, and parallel computation.

Install

python -m pip install --force-reinstall "wrf-rust==0.2.38"

Pre-built wheels for Python 3.10-3.13 on Linux, macOS, and Windows. No Rust toolchain, no system libraries, no conda required.

0.2.38 is the conservative compatibility release for applications built against 0.2.35 and 0.2.36, including WRF-Runner's New-PC-Updates branch. Because PyPI already contains numerically higher 0.4.x releases, an unpinned pip install -U wrf-rust will not select 0.2.38; pin the version exactly as shown above.

0.2.38 Reflectivity Parity Fix

This release retains the 0.2.37 Python API, NumPy return contract, performance work, Formula Lab crate, and all-Rust NetCDF readers. It corrects simulated dbz/maxdbz parity with NCAR wrf-python: the exact gas constant is used, an all-zero QSNOW field follows wrf-python's no-snow branch, non-finite hydrometeor cells are not silently converted into false echoes, QRAIN remains required, and genuine read errors are no longer mistaken for absent optional snow or graupel fields. The Solar7 lowest-level dbz plot is also labeled accurately instead of being described as a 1 km AGL product.

Raw model-native REFL_10CM is intentionally distinct from the generic wrf-python-compatible dbz diagnostic and may differ according to the WRF microphysics scheme. maxdbz remains the vertical maximum of generic dbz.

0.2.37 Compatibility, Formula Lab, and Readers

This release starts from v0.2.36, preserving its Python API and numerical diagnostics. It adds the standalone Rust wrf-formula crate, restores the all-Rust classic NetCDF reader for CDF-1/2/5 WRF files, and repairs decoding of fixed-width scalar HDF5 string attributes such as START_DATE. Formula Lab has no Python bindings on this compatibility line, and numerical science files are unchanged from v0.2.36.

The underlying v0.2.36 release starts from the v0.2.35 source and backports only output-preserving performance work: effective-inflow caching, parallel depth-limited CAPE and EL columns, cached CAPE reuse in severe composites, parallel HDF5 chunk decoding, reduced CAPE allocations, and removal of full rotated-wind volume copies. It does not include the later science-formula, diagnostic-registry, ECAPE-dependency, or Python return-contract changes.

Validation on a real 2.39 GB, 800 x 800 x 79 WRF file found byte-identical results for all 96 registered diagnostics versus v0.2.35. A representative WRF-Runner batch with 18 plot workloads and six process workers improved from 48.27 s to 35.25 s on a 24-thread Linux system (1.37x), while sampled aggregate peak RSS fell from 23.38 GB to 22.68 GB. The larger approximately 3.25x result measured elsewhere is a single-process, shared-WrfFile diagnostic benchmark; it is not an end-to-end WRF-Runner claim.

Community Guide

The repo now includes a full WRF community setup guide for Windows, WSL 2, real-data initialization, domain sizing, and troubleshooting:

• Manual-first Pages guide: docs/index.html
• Starter files: docs/starter-files/README.md
• Optional Codex skill: skills/wrf-community-onboarding/SKILL.md

Scientific Notes

Recent correctness work tightened the severe-weather diagnostics without changing the basic getvar() workflow:

• effective_inflow now returns the actual effective inflow base/top heights, not the MU parcel EL.
• Effective stp and scp now use effective SRH plus effective bulk wind difference (EBWD).
• bri now uses BRN shear instead of plain 0-6 km bulk shear.
• Raw staggered fields (U, V, W) keep their native WRF shapes, and ALL_TIMES stacking now runs in Rust.

Usage

import numpy as np
from wrf import WrfFile, getvar

f = WrfFile("wrfout_d01_2024-06-01_00:00:00")

# Basic fields
temp = getvar(f, "temp", units="degC")
slp  = getvar(f, "slp",  units="hPa")
wspd = getvar(f, "wspd", units="knots")

# CAPE with parcel selection
sbcape = getvar(f, "sbcape")
mlcape = getvar(f, "mlcape")
mucape = getvar(f, "mucape")
sb3cap = getvar(f, "sbcape", top_m=3000)           # 0-3 km CAPE

# Custom parcel
cape = getvar(f, "cape", parcel_pressure=850,
              parcel_temperature=20, parcel_dewpoint=15)

# ECAPE family
ecape = getvar(f, "ecape", storm_motion_type="bunkers_rm",
               entrainment_rate=0.0005, pseudoadiabatic=False)
ecin  = getvar(f, "ecin", storm_motion_type="mean_wind")

# SRH with Bunkers storm motion
srh1 = getvar(f, "srh1")                            # 0-1 km
srh3 = getvar(f, "srh3")                            # 0-3 km
srh  = getvar(f, "srh", depth_m=1500, storm_motion=(12, 8))
srh_pw = getvar(f, "srh1", storm_motion_method="pressure_weighted")

# Per-grid custom storm motion
sm_u = np.full((f.ny, f.nx), 12.0)
sm_v = np.full((f.ny, f.nx), 8.0)
srh_custom = getvar(f, "srh", depth_m=1500, storm_motion=(sm_u, sm_v))

# Effective inflow layer
eff_srh  = getvar(f, "effective_srh")
eff_cape = getvar(f, "effective_cape")

# Severe composites
stp     = getvar(f, "stp")                           # fixed-layer
stp_eff = getvar(f, "stp", layer_type="effective")   # effective-layer
scp     = getvar(f, "scp")
ehi     = getvar(f, "ehi", depth_m=3000)             # 0-3 km EHI

# Configurable layers
shear = getvar(f, "bulk_shear", bottom_m=1000, top_m=6000)
mw    = getvar(f, "mean_wind",  bottom_m=0, top_m=6000)
lr    = getvar(f, "lapse_rate", bottom_p=700, top_p=500)
lr_v  = getvar(f, "lapse_rate", bottom_m=0, top_m=3000, use_virtual=True)

# Lake interpolation (removes 2m artifacts over water bodies)
cape = getvar(f, "sbcape", lake_interp=1000)         # interp lakes < 1000 km2

# All timesteps
slp_all = getvar(f, "slp", timeidx=None)             # shape (nt, ny, nx)

Also accepts netCDF4.Dataset directly:

from netCDF4 import Dataset
slp = getvar(Dataset("wrfout_d01..."), "slp")

Note: dataset inputs are reopened by filepath under the hood. On Windows, do not keep a netCDF4.Dataset open while calling wrf-rust on that same file, especially in subprocesses. Close the dataset first or pass a file path / WrfFile instead.

Plotting

from wrf import plot_field, plot_wind, plot_skewt, panel

plot_field(f, "sbcape")                               # auto colormap + cartopy
plot_field(f, "sbcape", style="solar7")               # Solarpower07 colormaps
plot_wind(f)                                           # wind barbs
plot_skewt(f, point=(35.0, -97.5))                    # Skew-T with hodograph
panel(f, ["sbcape", "srh1", "stp", "shear_0_6km"])   # multi-panel

# Multi-timestep with consistent scale + GIF
from wrf.plot import render_timesteps
render_timesteps(f, "sbcape", timesteps=[0,1,2,3],
                 gif=True, fixed_scale=True)

CLI

python -m wrf info  wrfout_d01_2024-06-01_00:00:00
python -m wrf stats wrfout_d01_2024-06-01_00:00:00 sbcape slp temp
python -m wrf plot  wrfout_d01_2024-06-01_00:00:00 slp -o slp.png
python -m wrf panel wrfout_d01_2024-06-01_00:00:00 sbcape srh1 stp -o severe.png

Benchmark vs wrf-python

Benchmarked on a 199x199x79 WRF grid. The fields below matched wrf-python on that case, but broader scientific equivalence still depends on variable and workflow.

Plus 23 variables wrf-python doesn't have (STP, SCP, EHI, critical angle, ECAPE, shear, Bunkers, lapse rates, fire indices, effective inflow layer).

Variables

96 diagnostic variables. All support units= parameter.

Thermodynamics

temp tc theta theta_e theta_w tv twb td rh

Pressure & height

pressure slp height height_agl terrain geopt omega

pressure defaults to hPa for wrf-python compatibility. Use pres / p or units="Pa" when you want Pascals.

Moisture

pw rh2m dp2m mixing_ratio specific_humidity

CAPE & convection

sbcape sbcin mlcape mlcin mucape mucin cape cin lcl lfc el effective_cape effective_inflow cape2d cape3d

All CAPE variables support top_m for truncated integration (e.g. top_m=3000 for 3CAPE). Generic cape/cin accept parcel_type or custom parcel (parcel_pressure, parcel_temperature, parcel_dewpoint). effective_inflow returns a two-plane output: effective layer base followed by effective layer top, both in meters AGL.

ECAPE-family variables use the same getvar() entry point but also accept storm_motion_type, entrainment_rate, and pseudoadiabatic. They support parcel_type="sb", "ml", or "mu", but they do not currently support the generic custom parcel thermodynamics (parcel_pressure, parcel_temperature, parcel_dewpoint).

Wind

ua va wa wspd wdir wspd10 wdir10 uvmet uvmet10

SRH & shear

srh1 srh3 srh effective_srh shear_0_1km shear_0_6km bulk_shear mean_wind bunkers_rm bunkers_lm mean_wind_0_6km

SRH/Bunkers diagnostics default to pressure-weighted Bunkers layer means when pressure is available. Set storm_motion_method="non_pressure_weighted" (or "classic") to force the non-pressure-weighted path. storm_motion=(u, v) accepts either scalar components or (ny, nx) component grids.

Severe composites

stp stp_fixed stp_effective scp ehi tehi tts vtp_mod critical_angle ship bri

STP supports layer_type="effective" for the 5-term formula with MLCIN. Effective stp uses ESRH + EBWD, and scp uses MUCAPE + effective SRH + EBWD. tehi and tts mirror the SPC beta Tornadic 0-1 km EHI and Tornadic Tilting and Stretching products. vtp_mod is the modified violent tornado parameter using MLCAPE, ESRH, EBWD, MLLCL, MLCIN, 0-3 km MLCAPE, and 700-500 hPa lapse rate.

ECAPE

ecape ncape ecape_cape ecape_cin ecape_lfc ecape_el

ECAPE diagnostics accept parcel_type, storm_motion or storm_motion_type, entrainment_rate, and pseudoadiabatic.

Radar & cloud

dbz maxdbz ctt cloudfrac uhel

Vorticity

avo pvo

Lapse rates & levels

lapse_rate_700_500 lapse_rate_0_3km lapse_rate freezing_level wet_bulb_0

Generic lapse_rate accepts bottom_m/top_m or bottom_p/top_p, plus use_virtual=True.

Fire weather

fosberg haines hdw

Parameters

Unit strings

Every registered variable supports units=. Raw WRF variables (RAINNC, T2, PSFC, etc.) also support conversion when their default unit is known. Case-insensitive.

Raw WRF variables

Any variable name not in the computed registry is read directly from the file. Common ones:

# These all work:
rain = getvar(f, "RAINNC", units="in")     # accumulated precip in inches
tsk  = getvar(f, "TSK", units="degF")      # skin temp in Fahrenheit
pblh = getvar(f, "PBLH", units="ft")       # PBL height in feet

Building from source

Only needed for development. Users should pip install wrf-rust.

git clone https://github.com/FahrenheitResearch/wrf-rust.git
cd wrf-rust
pip install maturin
maturin develop --release

Acknowledgments

Special thanks to Solarpower07 for the underlying Solar7 colormaps and product definitions, and for substantial guidance on severe-weather diagnostics, storm motion, SRH, and ECAPE. A lot of the recent correctness work in wrf-rust is better because of that help.

License

MIT