Nesting

wrf_gpu runs fixed nested domains together on the GPU. The parent domain builds each child's lateral boundary live during the run, so you do not need a wrfbdy_d02: each child starts from its own wrfinput_d0N, and only wrfbdy_d01 forces the outer domain. The default physics are validated on nested forecasts: 24-hour comparisons with the original CPU-WRF on three-domain Tenerife (9/3/1 km) and two-domain Canary Islands (9/3 km) cases, and 72-hour runs in earlier releases.

How live nesting works¶

The nested driver is a standalone recursion faithful to WRF's module_integrate sub-cycling: the parent advances one step, constructs each child's lateral-boundary package from its own freshly-advanced state, and recurses into the child, which sub-cycles to catch up to the parent's clock. Each child's boundary update cadence is its parent's timestep. This is the validated one-way wiring (parent → child; the child does not modify the parent).

Grid and time sub-cycling ratios¶

The nest refinement is set by the WRF &domains key parent_grid_ratio (the spatial refinement, e.g. 3), read from the domain metadata. In this port parent_grid_ratio is both the spatial and the temporal sub-cycle ratio: a child takes parent_grid_ratio steps for every one parent step (WRF sub-cycling), which matches WRF's usual configuration where parent_time_step_ratio equals parent_grid_ratio.

Enabling a nested run¶

Nesting is opt-in via --max-dom N on gpuwrf run. With --max-dom 1 (the default) you get the single-domain path on --domain; with --max-dom N > 1 all domains d01..dN run together as the live-nested forecast.

gpuwrf run --input-dir my_case --output-dir runs/nested \
    --max-dom 3 --hours 24 --scratch-dir /fast/nvme/gpuwrf_scratch

A namelist max_dom is not auto-run

If your namelist declares max_dom > 1 but you omit both --max-dom and --domains-from-namelist, the CLI runs a single domain (--domain) by default and prints a note telling you to pass --max-dom N to run the standalone live-nested forecast. Nesting is never entered implicitly. Remember the one-time cold compile on the first run (a large nested case can take several minutes) — later runs read the persistent JIT cache; see Running the Model and Performance.

Gravity-wave drag on nests¶

Orographic gravity-wave drag (gwd_opt=1) is used on every domain that requests it in the namelist. Set GPUWRF_GWD_NESTED=0 to switch it off on nests to save memory. See dynamical core.

Restart¶

Nested runs (max_dom > 1), like native single-domain d01 runs, write verified, rotating checkpoint generations with --checkpoint-dir DIR --checkpoint-interval-steps N (root-domain steps; all domains are captured at one synchronized time) and resume in the same output stream with --resume-checkpoint GEN. The namelist restart/restart_interval settings do not provide crash recovery. See Running.

Two-way nesting¶

Two-way nesting is off by default. Turn it on with feedback=1 in the namelist or with gpuwrf run --feedback. After each child finishes its sub-steps, its interior is fed back onto the overlapping parent cells with WRF's area average, followed by the smoother selected with smooth_option (0, 1 or 2).

Status: validated on one set-up

Two-way nesting passed a 24-hour comparison with the original CPU-WRF on one two-domain configuration (Thompson, MYNN, Noah-MP, RRTMG, no cumulus, smooth_option=2). It runs only with the default physics (Kain-Fritsch cumulus or none), an odd parent_grid_ratio and without nudging, lakes, urban models, SST updates or online diagnostics; other set-ups stop with a message. Its compiled GPU code exceeds our code-quality limits for speed and robustness; it runs correctly, but its speed has not been measured.

Moving nests are not supported¶

Moving and vortex-following nests stop with a message. Use fixed nests.

Options inside nests¶

The default physics are validated inside nests. Most other options were checked in single-domain forecasts only: they run inside nests but are not validated there. A few are refused in nested runs: the RUC land model, the single-layer urban model, the 3-D TKE turbulence options (km_opt=2/5), digital filter initialization and splitting a domain across GPUs; gpuwrf doctor and gpuwrf run name them before the forecast starts.