Namelist compatibility

wrf_gpu reads your WRF namelist.input as it is. Every option it understands is used exactly as requested; an option it cannot honour stops the run with a message that names it. Nothing is silently replaced by a default.

How your namelist is checked¶

gpuwrf run checks the namelist before any GPU work. A refused selection, a missing pairing or a missing input gives a short message naming the setting to change. You can run the same checks in advance:

gpuwrf doctor /path/to/case          # inputs, options, time step (CFL) and GPU memory
gpuwrf run --input-dir /path/to/case --output-dir runs/check --dry-run
gpuwrf namelist-support               # every physics code the program knows

Being accepted is not the same as being validated. This page and the physics options page give the status of each option in v0.4.0, using the same words: Default, Validated 24 h, Experimental, CPU only and Not supported (what they mean).

Model features¶

Each "Validated 24 h" feature passed a 24-hour comparison with the original CPU-WRF in one tested configuration; other combinations and nested domains are not validated. A note ¹ means the compiled GPU code exceeds our code-quality limits for speed and robustness (it runs correctly; its speed is not measured).

Feature	Namelist settings	Status	Guide
Analysis (grid) nudging	`grid_fdda=1` with `wrffdda` input	Validated 24 h	below
Spectral nudging	`grid_fdda=2`	Validated 24 h	spectral nudging
Surface analysis nudging	`grid_sfdda=1/2`	Validated 24 h	surface nudging
Observation nudging	`obs_nudge_opt=1`	Validated 24 h¹	observation nudging
Digital filter initialization	`dfi_opt=1/2/3` (single domain)	Validated 24 h	below
Single-layer urban canopy	`sf_urban_physics=1` (single domain)	Validated 24 h	urban guide
LCZ land use, urban morphology, anthropogenic heat	`use_wudapt_lcz=1`, `distributed_ahe_opt` (with `sf_urban_physics=1`)	Experimental	urban guide
Multi-layer urban (BEP, BEP+BEM)	`sf_urban_physics=2/3`	Validated 24 h¹	BEP/BEM guide
Lake model	`sf_lake_physics=1`	Validated 24 h¹	lake guide
Ocean mixed layer	`sf_ocean_physics=1`	Validated 24 h	ocean guide
Hurricane surface fluxes	`isftcflx=1/2`	Validated 24 h¹	ocean guide
SST updates from `wrflowinp`	`sst_update=1`	Validated 24 h	input data
Slope radiation and terrain shading	`slope_rad=1`, `topo_shading=1`	Validated 24 h	input data
Wind farms (Fitch)	`windfarm_opt=1`	Validated 24 h¹	wind-farm guide
Passive tracers	`tracer_opt=2`	Validated 24 h¹	tracer guide
Two-way nesting	`feedback=1`, `smooth_option`	Validated 24 h¹ on one two-domain set-up; default physics only	nesting
Noah-MP options	`&noah_mp` selectors	Defaults validated; others mostly Experimental	physics
Stochastic physics and perturbations	`skebs`, `sppt`, `spp`, `spp_conv/pbl/lsm`, `rand_perturb`, `stoch_force_opt`	Experimental	stochastic guide
Online diagnostics	`prec_acc_dt`, `nwp_diagnostics=1`, `do_radar_ref=1`, WRF-Solar diagnostics	Experimental	diagnostics guide
Station time series	a `tslist` file in the case directory	Experimental	tslist guide
Regional output streams	`gpuwrf.streams.json` next to the namelist	Experimental	streams guide

Analysis nudging (grid FDDA)¶

With grid_fdda=1, WRF's analysis nudging relaxes wind, temperature and water vapour towards gridded analyses during the forecast. wrf_gpu ports WRF's routine and reads the same input file. Validated 24 h in single-domain forecasts; nested domains are not validated.

Input. Run real.exe with the same &fdda settings; it writes wrffdda_d01 (named by gfdda_inname, NetCDF only). Put the file in the case directory next to wrfinput_d01 and wrfbdy_d01; each domain with grid_fdda=1 needs its own wrffdda_d0N. The file must hold one record per analysis time from the start to the end of nudging; a missing or short file, record times off the analysis interval, wrong grid sizes or invalid values stop the run before the forecast.

As written by real.exe, each record holds a pair of analyses: *_NDG_OLD at the record's time and *_NDG_NEW at the next analysis time. Between them the nudging target is interpolated linearly in time.

Fields (OLD and NEW)	Grid	Content
`U_NDG_OLD`, `U_NDG_NEW`	levels × south_north × west_east_stag	x-wind, m/s
`V_NDG_OLD`, `V_NDG_NEW`	levels × south_north_stag × west_east	y-wind, m/s
`T_NDG_OLD`, `T_NDG_NEW`	levels × south_north × west_east	dry potential temperature minus 300 K, K
`Q_NDG_OLD`, `Q_NDG_NEW`	levels × south_north × west_east	water vapour mixing ratio, kg/kg
`PH_NDG_OLD`, `PH_NDG_NEW`	staggered levels × south_north × west_east	geopotential perturbation; needed only for spectral nudging (`grid_fdda=2`)

The nudging coefficients guv, gt and gq are in s^-1.

&fdda
 grid_fdda            = 1,
 gfdda_inname         = "wrffdda_d<domain>",
 gfdda_interval_m     = 360,      ! analysis interval, minutes
 gfdda_end_h          = 24,       ! stop nudging after this many hours
 io_form_gfdda        = 2,
 fgdt                 = 0,        ! minutes between nudging updates (0 = every step)
 if_no_pbl_nudging_uv = 0, if_no_pbl_nudging_t = 1, if_no_pbl_nudging_q = 1,
 if_zfac_uv = 0, k_zfac_uv = 10, if_zfac_t = 0, k_zfac_t = 10, if_zfac_q = 0, k_zfac_q = 10,
 guv = 0.0003, gt = 0.0003, gq = 0.0003,
 if_ramping           = 0,
 dtramp_min           = 60.0,
/

Timing. As in WRF, analyses are read every gfdda_interval_m minutes from the start time and the nudging terms are updated every fgdt minutes (0 means every time step). When nudging ends depends on the ramp:

if_ramping=0: full strength until gfdda_end_h, then off.
if_ramping=1 with a positive dtramp_min: the ramp starts at gfdda_end_h and extends nudging beyond it, falling linearly to zero over dtramp_min minutes while the target is held at the most recent analysis. With gfdda_end_h=24 and dtramp_min=60, nudging is at half strength at 24.5 h and ends at 25 h.
if_ramping=1 with a negative dtramp_min: the ramp ends at gfdda_end_h. With gfdda_end_h=24 and dtramp_min=-60, nudging falls from full strength at 23 h to zero at 24 h.

What is nudged. The horizontal wind, potential temperature and water vapour; surface pressure and the air mass are not nudged. The nudging heat flux HFX_FDDA is written to the history files.

Restrictions. As in WRF, nudging starts at the model start (gfdda_begin_* must be 0) and times are given in gfdda_end_h and gfdda_interval_m. Switching off nudging inside the boundary layer (if_no_pbl_nudging_*=1) needs the MYNN boundary layer (bl_pbl_physics=5). Grid nudging cannot be combined with digital filter initialization or two-way nesting, Pleim-Xiu soil nudging (pxlsm_soil_nudge) is not supported, and an &fdda key the program does not know stops the run instead of being ignored. The history files lack WRF's global attributes FGDT, GUV, GT, GQ, IF_RAMPING and DTRAMP_MIN; the forecast itself is unaffected.

Restart. The nudging state is part of the checkpoints, so a resumed run continues nudging where it stopped. Checkpoints from versions without this state are refused.

Spectral nudging (grid_fdda=2) reads the same file (spectral nudging guide); surface nudging (grid_sfdda) adds a surface analysis file (surface nudging guide); observation nudging can run alongside (observation nudging guide).

Digital filter initialization¶

Single-domain cases support dfi_opt=1/2/3 (DFL, DDFI and TDFI) with WRF's filter and window settings. DFL keeps its natural shifted timestamps, as in WRF. Nested DFI is not supported. With dfi_opt=0 or no setting nothing is filtered, and a resumed run does not filter again. The upgrade notes list the remaining restrictions.

Turbulence, diffusion and advection¶

Setting	Status
`diff_opt=1` with `km_opt=4` (2-D Smagorinsky, WRF's real-data default)	Default
`diff_opt=0` (no explicit horizontal diffusion)	Runs as requested; not separately validated
`diff_opt=2` with `km_opt=2` (3-D TKE) or `km_opt=5` (SMS-3DTKE)	Experimental: passed 24-hour comparisons; restrictions on extra scalars, nests and PBL pairing apply
`diff_opt=2` with `km_opt=1` (constant K)	Python API only
`km_opt=3` (3-D Smagorinsky)	Not supported on the GPU
`moist_adv_opt`, `scalar_adv_opt` = 0/1/2	Used as requested; the default suite's values are validated, other values are not separately validated

gpuwrf run refuses any other diff_opt/km_opt pair rather than running without diffusion.

The dynamical core page explains the numerics.

Not supported in v0.4.0¶

Moving and vortex-following nests; adaptive time stepping.
WRF-Chem, WRF-Fire, WRF-Hydro, wave coupling and WRFDA data assimilation.
km_opt=3 on the GPU; constant-K diffusion (km_opt=1) from the command line; surface mosaic (sf_surface_mosaic=1); the PWP ocean model (sf_ocean_physics=2); green roofs and photovoltaic panels in the urban models; LCZ land use with BEP/BEM; two-way tracer feedback.
Two-way nesting with anything other than the default physics, with nudging, lakes, urban models or SST updates, or with an even parent_grid_ratio.
In nested runs: digital filter initialization, the RUC land model, the single-layer urban model and km_opt=2/5.
The physics codes marked Not supported on the physics page.

Options that have only single-domain evidence still run inside nests, but are not validated there. The support matrix lists the exact tested configurations and the evidence for each row.

Coming from v0.3¶

v0.3.3 and earlier could silently run the default schemes when a different scheme was requested. If you ran non-default physics with those versions, run the forecasts again. Checkpoints from earlier versions may not resume; see the upgrade notes.