Tools and commands

Everything runs through one program, gpuwrf. Only the forecast itself needs the GPU. The other commands work offline on the CPU with files you already have, and the ones that read history files accept CPU-WRF wrfout files as well as wrf_gpu output.

All commands¶

gpuwrf <command> --help shows every option of a command. The tools are tested on the CPU; they never change forecast results, and a statistics or calibration tool is not by itself a claim of better forecast skill.

Set up a forecast for your region¶

gpuwrf quickstart --profiles     # how large a grid fits on a 12-32 GB GPU
gpuwrf quickstart --bbox -17 28 -16 28.6 --resolution-km 9 \
  --date 2026-10-12T00 --hours 3 --case-dir work/tenerife --run

Without --prepare or --run the command only prints a plan. --prepare downloads the GFS data and runs WPS and real.exe; --run also starts the GPU forecast. Use a recent GFS cycle as the date. The region guide covers the container that builds WPS and WRF for you, the geography data and each step. Region set-up is Experimental: its preparation steps are tested on three areas, but GPU forecasts for new regions have not yet been compared with CPU-WRF, and the grid sizes from --profiles are estimates.

Check a case before running¶

gpuwrf doctor /path/to/case
gpuwrf manifest /path/to/case --output runs/case_manifest.json
gpuwrf reproduce runs/case_manifest.json --case-dir /path/to/case

doctor reports missing inputs, refused options, the time-step stability margin (CFL) and an estimate of GPU memory. manifest and reproduce let you prove later that a forecast used exactly these inputs.

Weather products¶

gpuwrf post --list-products
gpuwrf post --input runs/my_case/wrfout_d01_* --output runs/products.nc \
  --product wind10,precip,cloud --rolling-hours 3 6

Each product writes CF-annotated NetCDF variables. Thermodynamic products (thermal, instability, helicity) need the optional MetPy package and helicity needs --storm-u/--storm-v; the solar product needs pip install 'gpuwrf[apps]'. --product radar computes reflectivity, composite reflectivity, echo tops and vertically integrated liquid from the history fields.

Station verification and calibration¶

gpuwrf verify --stations stations.csv --obs observations.csv \
  --model runs/my_case/wrfout_d01_* --output-dir runs/verification
gpuwrf calibrate fit --stations stations.csv --obs past-obs.csv \
  --forecasts past-forecasts.csv --method bias --output station-model.json
gpuwrf calibrate apply --model station-model.json \
  --forecasts future-forecasts.csv --output corrected-stations.csv

verify downloads observations only with --fetch-observations metar or isd-lite; with --obs it stays offline. The station verification guide explains station heights, wind heights, land-aware sampling and precipitation intervals.

Ensembles¶

gpuwrf perturb --case CASE --output runs/wind-members \
  --members 5 --seed 451 --wind-std 0.05
gpuwrf ens prepare --mode batch --cases runs/wind-members/member-* \
  --output-dir runs/member_plan --hours 24
gpuwrf ens launch --plan runs/member_plan/plan.json
gpuwrf ens products --members members.json --variable T2 --output runs/ensemble_T2.nc

ens prepare also builds physics ensembles (--mode physics, one case with several namelists) and lagged ensembles (--mode lagged). ens launch checks GPU and host memory and runs as many members side by side as fit. ens verify gives probabilities, scores and reliability against station observations. Stochastic physics inside the model (skebs, sppt, spp) is a namelist feature and is Experimental; see the ensemble guide.

Choose physics for your region¶

gpuwrf optimize plan --study study.json --output runs/study_plan.json
gpuwrf optimize run --study study.json --output runs/regional-study
gpuwrf optimize score --study study.json --forecasts forecasts.json --output runs/selection.json

A study lists candidate physics configurations (only ones the program accepts), training dates and held-out test dates. optimize identity prints the model version the study is bound to. The optimisation guide describes the study file.

Export and station files¶

gpuwrf export --input runs/my_case/wrfout_d01_* --output runs/surface.nc \
  --format netcdf --variables T2 PSFC U10 V10
gpuwrf tslist-export --input runs/my_case/STATION.d01.TS --output station.csv

export also writes pressure levels (--pressure-levels), regional cut-outs (--region), Zarr and GRIB2 on an explicit grid (pip install 'gpuwrf[export]'). --raw keeps the native WRF dimensions and attributes.

Soil and snow cycling¶

gpuwrf cycle --source previous_cycle/wrfout_at_new_init \
  --wrfinput new_case/wrfinput_d01 --output new_case/wrfinput_cycled_d01

The source history must be valid at the new start time and on the same grid. The command writes a new file and never overwrites the template. Cycling is not data assimilation and is different from restarting a stopped forecast; see the cycling guide.

Several forecasts and several GPUs¶

scripts/run_parallel_cases.sh --out-root runs/batch CASE_A CASE_B CASE_C -- \
  --domains-from-namelist --hours 24
scripts/run_parallel_cases.sh --gpus all --out-root runs/ens MEMBER_01 MEMBER_02 -- \
  --domains-from-namelist --hours 24

Independent forecasts can share one GPU; the launcher starts as many as fit in memory, and one failed case never stops the others. With --gpus each forecast runs on one GPU of several. A single very large domain can also be split across GPUs with gpuwrf run --decompose 2x1. Experimental: both multi-GPU paths are tested on simulated devices only; no run on real multi-GPU hardware has been measured yet. See several GPUs.

Runtime tables¶

python -m gpuwrf.assets list      # every table and where it is found
python -m gpuwrf.assets fetch --all
python -m gpuwrf.assets verify

Large microphysics lookup tables, including the Thompson tables of the default physics, are downloaded on first use from the GitHub release and checked against pinned checksums. The upload of the v0.4.0 tables is still pending; until it is done, runs that need them stop with an "asset unavailable" message. Runtime tables explains the cache and offline use.