gpuwrf run runs a forecast from a prepared WRF case: a namelist.input, wrfinput_d0* files and wrfbdy_d01, as made by WPS and real.exe. It writes WRF-style wrfout history files. This page covers the forecast itself; the other commands are on tools and commands.

Before the first run¶

Install wrf_gpu as described in installation, then check that the command and the GPU are visible:

gpuwrf --help
python -c "import jax; print(jax.devices())"

The GPU must be an NVIDIA Ampere or newer card (compute capability 8.0 or higher). Set GPUWRF_WRF_ROOT to a WRF installation so that schemes that read WRF's tables find them.

Run the bundled forecast¶

The repository ships a small 24-hour forecast over the Swiss Alps at 3 km with all inputs:

gpuwrf doctor examples/switzerland_d01
gpuwrf run --input-dir examples/switzerland_d01 \
  --output-dir runs/switzerland --domain d01 --hours 24 \
  --scratch-dir runs/switzerland_scratch

The first run compiles the model for your GPU before the forecast starts, which can take several minutes. Later runs with the same grid and physics reuse the compiled program and start quickly; a new grid, a different physics selection or a new version compiles again. The example notes list the dates, schemes and expected output, and the quickstart shows how to read it.

Run your own case¶

Prepare the case with WPS and real.exe as for WRF, or let gpuwrf quickstart do it from open GFS data. Then:

gpuwrf doctor /path/to/case
gpuwrf run --input-dir /path/to/case --output-dir runs/my_case \
  --domains-from-namelist --hours 24

doctor checks inputs, options, the time step and GPU memory first. Use a new output directory for every run; existing history files are never overwritten. Useful options:

• --domain d01 runs one domain; --domains-from-namelist or --max-dom N runs the fixed nests of the namelist together (see nesting).
• --dry-run checks the namelist and prints the run plan without starting the forecast.
• --emit-initial-history (nested runs) also writes a history file at the start time.
• --feedback turns on two-way nesting (or set feedback=1 in the namelist).

The physics and namelist options you select are used as requested or refused with a message; see physics options and namelist compatibility for what is validated. A case directory that also holds at least two CPU-WRF wrfout files is run in replay mode, which reads the CPU history; keep reference output elsewhere if you want a standalone forecast (input data).

Checkpoints, restart and longer forecasts¶

For long runs, write checkpoints at a fixed interval of root-domain steps:

gpuwrf run --input-dir /path/to/case --output-dir runs/my_case \
  --domains-from-namelist --hours 24 \
  --checkpoint-dir runs/checkpoints --checkpoint-interval-steps 120

If the run stops, resume from the newest verified checkpoint written by that run; the forecast continues in the same output directory:

gpuwrf run --input-dir /path/to/case --output-dir runs/my_case \
  --domains-from-namelist --hours 24 \
  --resume-checkpoint runs/checkpoints/<generation>

Replace <generation> with the checkpoint directory the run reported. Checkpoints are checked before use and a mismatching one is refused. With --extend-run a resumed forecast can continue past its original end time, as long as the boundary data cover the longer period. Checkpoints from earlier versions may not resume; see the upgrade notes. The namelist restart settings do not replace these checkpoints.

GPU memory¶

Memory depends on the grid, the number of levels, the physics and the number of nests. gpuwrf doctor estimates it for a case, and gpuwrf quickstart --profiles shows rough grid sizes for 12 to 32 GB cards. Before a nested forecast gpuwrf run checks that enough GPU memory is free and stops with a message if not. Compiling a new program needs more host memory than running it. The environment variables page lists the memory settings.

Several forecasts at once¶

Independent forecasts and ensemble members can share one GPU or spread across several. Use scripts/run_parallel_cases.sh or gpuwrf ens; both start as many forecasts side by side as fit in memory. Running on several GPUs is experimental.

After the forecast¶

The history files use WRF's variable names and dimensions, so existing NetCDF tools, WRF post-processors and scripts work. wrf_gpu adds offline tools for derived products, station verification, export, ensembles and soil/snow cycling: see tools and commands, and output files for what is written.