wrf_gpu
User's Guide › Getting started › Quickstart: Your First Forecast

Quickstart: Your First Forecast

Run the bundled Switzerland 3 km case — real GFS-initialized inputs that ship in the repo — end-to-end on your GPU in three commands, then read the WRF-compatible wrfout it writes. No WPS or real.exe step and no CPU-WRF run are required.

Release tables pending

The bundled case uses Thompson microphysics, whose large lookup tables are downloaded on first use from the GitHub release. The upload of the v0.4.0 tables is still pending; until it is done, the run stops with an "asset unavailable" message. See runtime tables.

Before you start

You need wrf_gpu installed with a GPU-visible JAX (Installation & Requirements). The bundled case selects RRTMG radiation and Noah-MP land; Noah-MP reads WRF lookup tables, so set GPUWRF_WRF_ROOT to a pristine WRF v4 tree first. This case needs only GPUWRF_WRF_ROOT — GPUWRF_CANAIRY_ROOT is for the larger validation corpus, not this case.

Three steps

# 1. Point at a pristine WRF v4 source/run tree (for the RRTMG + Noah-MP tables):
export GPUWRF_WRF_ROOT=/path/to/WRF

# 2. Run one forecast hour of the bundled Switzerland 3 km case on the GPU:
gpuwrf run \
    --input-dir   examples/switzerland_d01 \
    --output-dir  runs/switzerland_d01 \
    --domain      d01 \
    --hours       1 \
    --scratch-dir /fast/nvme/scratch          # any real (non-tmpfs) fast disk

# 3. Read the WRF-compatible history file:
ncdump -h runs/switzerland_d01/wrfout_d01_*

Raise --hours for a longer forecast — the bundled namelist window covers 24 h.

The bundled case

examples/switzerland_d01/ is a small, self-contained real-data case:

PropertyValue
Domain42 × 42 mass points, 44 vertical levels, Δx = Δy = 3 km, single domain
Initialization2023-01-15 00:00 UTC; 3-hourly boundary interval
Physics menump_physics=8 (Thompson), ra_lw/sw=4 (RRTMG), sf_surface_physics=4 (Noah-MP), bl_pbl_physics=5 / sf_sfclay_physics=5 (MYNN), cu_physics=0
ProvenanceDerived from public-domain NCEP GFS analysis via the standard WPS / real.exe chain — freely redistributable

What just happened

  1. Fail-closed namelist check — instant, no GPU. The case's namelist.input is validated before any heavy import; an unsupported scheme is refused here with a named reason (see Namelist Compatibility).
  2. Init-mode auto-detect — the case has no CPU-WRF wrfout, so run announces standalone native-init: it assembles the initial and boundary state and integrates entirely on the GPU, with no CPU-WRF dependency. See Input Data & Initialization.
  3. Cold compile, then integrate — the first run pays a one-time JIT compile (details below), then advances the forecast and writes output.
  4. Output — a WRF-compatible wrfout_d01_* history file plus a run-payload JSON land under --output-dir. The writer emits full WRF history by default, with a case-specific inventory (see Output).
The first run is slow on purpose

The first forecast JIT-compiles the GPU kernels — a one-time cold compile with no output before integration starts. It is compiling, not hung. Compile time scales with domain size: roughly ½–2 min for this single-domain d01 case, and up to ~8–12 min for a large nested case. A persistent, per-user on-disk JIT cache is on by default with zero config, so later runs hit the warm cache and start in seconds. Full detail on Performance & GPU Modes.

A live-nested forecast (down to 1 km)

For a multi-domain run (d01→d02→d03, including a 1 km nest), add --max-dom N instead of --domain. This is explicit opt-in and defaults to 1 (single-domain). The parent advances and builds each child's lateral boundary live, so you only need a per-domain wrfinput_d0N and wrfbdy_d01 for the outer domain — no CPU-WRF wrfout and no pre-supplied wrfbdy_d02:

gpuwrf run \
    --input-dir   /path/to/case \
    --output-dir  runs/nested \
    --max-dom     3 \
    --hours       24 \
    --scratch-dir /fast/nvme/scratch

This writes a synchronized wrfout_d01_*, wrfout_d02_*, and wrfout_d03_* set. The larger fused nest is a bigger one-time cold compile (the ~8–12 min range above), cached thereafter. See Running the Model for the full CLI and Nesting for the mechanics.

Reading the output

The output is a standard WRF-compatible NetCDF history file — inspect it with any WRF tooling:

ncdump -h runs/switzerland_d01/wrfout_d01_*
python -c "import xarray as xr; print(xr.open_dataset('runs/switzerland_d01/wrfout_d01_...'))"
Where to go next

Running the Model — the full gpuwrf run CLI reference (single-domain, nested, replay, two-way). Input Data & Initialization — how wrf_gpu uses wrfinput and wrfbdy real-data artifacts. Performance & GPU Modes — cold compile, warm cache, VRAM, and batched ensembles.