WRF
Overview
The following is a description of the DART interface module for the Weather Research and Forecasting model (WRF) model. This page provides an overview of the module compiled into DART that interfaces with the WRF data in the state vector. The WRF-DART interface is compatible with WRF versions 4 and later, and is no longer backwards compatible with WRFv3.9 and earlier. For more information on the interface changes required between different WRF versions, read through this documentation and the WRF-DART tutorial link in the next section.
There have been several important updates to the WRF-DART interface starting with DARTv11.5.0. Some important WRF-DART updates include:
Version 11.4.1: Detects use of the Hybrid Vertical Coordinate system (terrain following at surface) and accounts for this in the forward operator calculations.
Version 11.5.0: Improves compatibility with WRFv4+ versions where the prognostic 3D temperature variable is THM. It is now mandatory to include THM instead of T in the
wrf_state_variables
namelist.
It is always recommended that you update your DART version to the latest release before beginning new research.
WRF-DART Tutorial
This tutorial provides a real-world example of assimilating a wide variety of atmospheric observations during an extreme storm event for the United States during April 2017. It is strongly recommended that you also review and perform the tutorial for running a WRF-DART assimilation here.
WRF Interface Overview
The model interface code supports WRF configurations with multiple domains. Data
for all domains is read into the DART state vector. During the computation of
the forward operators (getting the estimated observation values from each
ensemble member), the search starts in the domain with the highest number, which
is generally the finest nest or one of multiple finer nests. The search stops as
soon as a domain contains the observation location, working its way from largest
number to smallest number domain, ending with domain 1. For example, in a 4
domain case the data in the state vector that came from wrfinput_d04
is
searched first, then wrfinput_d03
, wrfinput_d02
, and finally
wrfinput_d01
.
Important
Although the model interface code is compatible with multiple domains, the supporting shell scripts and WRF-DART tutorial are currently designed for a single domain and will require some modifications for multiple (nested) domain functionality. If you need help with these modifications please contact DART support.
In summary, the forward operator is computed from the first domain grid (searching from finest grid to coarsest grid) that contains the lat/lon of the observation. During the assimilation phase, however, when the state values are adjusted based on the correlations and assimilation increments, all points in all domains that are within the localization radius are adjusted, regardless of domain. The impact of an observation on the state depends only on the distance between the observation and the state vector point, and the regression coefficient based on the correlation between the distributions of the ensemble of state vector points and the ensemble of observation forward operator values.
The fields from WRF that are copied into the DART state vector are controlled by
the namelist within input.nml
. See below for the documentation on the &model_nml
entries within
input.nml
. The state vector should include all fields needed to restart a WRF run.
There may be additional fields needed depending on the microphysics scheme selected. See the
ascii file wrf_state_variables_table
that includes a list of fields that may be added to the DART state.
Namelist
The &model_nml
namelist is read from the input.nml
file. Namelists
start with an ampersand &
and terminate with a slash /
. Character
strings that contain a /
must be enclosed in quotes to prevent them from
prematurely terminating the namelist.
&model_nml
default_state_variables = .true.
wrf_state_variables = 'NULL'
wrf_state_bounds = 'NULL'
num_domains = 1
calendar_type = 3
assimilation_period_seconds = 21600
allow_obs_below_vol = .false.
vert_localization_coord = 3
center_search_half_length = 500000.
center_spline_grid_scale = 10
circulation_pres_level = 80000.0
circulation_radius = 108000.0
sfc_elev_max_diff = -1.0
polar = .false.
periodic_x = .false.
periodic_y = .false.
scm = .false.
allow_perturbed_ics = .false. # testing purposes only
/
Namelist Description:
Item |
Type |
Description |
---|---|---|
default_state_variables |
logical |
If .true., the dart state vector contains the fields U, V, W, PH, THM, MU, in that order, and only those. Any values listed in the wrf_state_variables namelist item will be ignored. |
wrf_state_variables |
character(:,5) |
A 2D array of strings, 5 per wrf array to be added to the dart state vector. If default_state_variables is .true., this is ignored. When .false., this list of array names controls which arrays and the order that they are added to the state vector. The 5 strings are:
|
wrf_state_bounds |
character(:,4) |
A 2D array of strings, 4 per wrf array. During the copy of data to and from the WRF (wrfinput*) file, variables listed here will have minimum and maximum values enforced. The 4 strings are:
|
num_domains |
integer |
Total number of WRF domains, including nested domains. |
calendar_type |
integer |
Calendar type. Should be 3 (GREGORIAN) for WRF. |
assimilation_period_seconds |
integer |
The time (in seconds) between assimilations. This is modified if necessary to be an integer multiple of the underlying model timestep. |
periodic_x |
logical |
If .true., the grid is periodic in longitude, and points above the last grid cell and points below the first grid cell are wrapped. Note this is not the same as a grid which crosses the prime meridian. WRF handles that with an offset in longitude and points beyond the last grid index are outside the domain. |
periodic_y |
logical |
Used for the WRF single column model to make the grid wrap in Y (see scm below). This is NOT the same as wrapping in latitude (see polar below). |
polar |
logical |
If .true., points at the poles are wrapped across the grid. It is not clear this is a good idea because the grid is degnerate here. |
scm |
logical |
If .true. the single column model is assumed. The grid is a single vertical column, and there are 9 cells arranged in a 3x3 grid. See the WRF documentation for more information on this configuration. periodic_x and periodic_y should also be .true. in this case. |
sfc_elev_max_diff |
real(r8) |
The maximum elevation difference (in meters) between a ‘surface’ observation and the land surface elevation defined in WRF. If the value is > 0, that value is the threshold at which the surface observations are rejected. If the value is negative the test is skipped. |
allow_obs_below_vol |
logical |
If .false. then if an observation with a vertical coordinate of pressure or height (i.e. not a surface observation) is below the lowest 3d sigma level, it is outside the field volume and the interpolation routine rejects it. If this is set to .true. and the observation is above the surface elevation but below the lowest field volume level, the code will extrapolate downward from data values at levels 1 and 2. |
center_search_half_length |
real(r8) |
A parameter in the ‘use_old_vortex’
scheme used to search for a vortex
center location. It is the half-length
(meters) of a square box used during
the vortex search. This value and the
‘center_spline_grid_scale’ namelist
items are required. To implement, set
|
center_spline_grid_scale |
integer |
A parameter in the ‘use_old_vortex’
scheme used to search for a vortex
center location. It is the fine grid
ratio for the spline interpolation
used during the vortex search. This
value and the
‘center_search_half_length’ namelist
items are required. To implement, set
|
circulation_pres_level |
real(r8) |
A parameter in the ‘circulation’
scheme used to search for a vortex
center location. It is the pressure
(Pascals) at which the circulation is
computed during the vortex search.
This value and the
‘circulation_radius’ namelist items
are required. To implement, set
|
circulation_radius |
real(r8) |
A parameter in the ‘circulation’
scheme used to search for a vortex
center location. It is the radius
(meters) of the circle over which the
search for the vortex center is
performed. This value and the
‘circulation_pres_level’ namelist
items are required. To implement,
set |
vert_localization_coord |
integer |
Vertical coordinate for vertical localization.
|
allow_perturbed_ics |
logical |
allow_perturbed_ics should not be used in most cases. It is provided only as a means to create a tiny ensemble for non-advancing tests. Creating an initial ensemble is covered in WRF/DART Tutorial Materials for the Manhattan Release. |
Additional Namelist Information
default_state_variables
You must set default_state_variables = .false.
before changing the value
of wrf_state_variables
to have it take effect.
wrf_state_variables
The format for wrf_state_variables
is an array of 5 strings:
WRF output field, DART Quantity, WRF TYPE, ‘UPDATE’ or ‘NO_COPY_BACK’, and a numerical
string ‘XXX’. If XXX=999 the variable is part of all domains, otherwise it is limited
to specific domains (e.g. ‘12’ for domains 1 and 2, ‘13’ for domains 1 and 3).
For example:
wrf_state_variables='U','QTY_U_WIND_COMPONENT','TYPE_U','UPDATE','999',
'V','QTY_V_WIND_COMPONENT','TYPE_V','UPDATE','999',
'W','QTY_VERTICAL_VELOCITY','TYPE_W','UPDATE','999',
'THM','QTY_POTENTIAL_TEMPERATURE','TYPE_T','UPDATE','999',
'PH','QTY_GEOPOTENTIAL_HEIGHT','TYPE_GZ','UPDATE','999',
'MU','QTY_PRESSURE','TYPE_MU','UPDATE','999',
'QVAPOR','QTY_VAPOR_MIXING_RATIO','TYPE_QV','UPDATE','999',
'QCLOUD','QTY_CLOUD_LIQUID_WATER','TYPE_QC','UPDATE','999',
'QRAIN','QTY_RAINWATER_MIXING_RATIO','TYPE_QR','UPDATE','999',
'U10','QTY_U_WIND_COMPONENT','TYPE_U10','UPDATE','999',
'V10','QTY_V_WIND_COMPONENT','TYPE_V10','UPDATE','999',
'T2','QTY_TEMPERATURE','TYPE_T2','UPDATE','999',
'TH2','QTY_POTENTIAL_TEMPERATURE','TYPE_TH2','UPDATE','999',
'Q2','QTY_SPECIFIC_HUMIDITY','TYPE_Q2','UPDATE','999',
'PSFC','QTY_PRESSURE','TYPE_PS','UPDATE','999',
Important
It is mandatory to include THM
instead of T
as the TYPE_T
WRF
temperature variable. This is because THM
is the prognostic temperature variable
that will impact the forecast when updated.
polar, periodic_x
The Polar
and periodic_x
namelist values are used in global WRF simulations.
If polar
is true, the grid interpolation routines will wrap over the north and south poles.
If periodic_x
is true, when the east and west edges of the grid are
reached the interpolation will wrap. Note this is a separate issue
from regional models which cross the GMT line. Those grids are marked
as having a negative offset and do not need to wrap. This flag controls
what happens when the edges of the grid are reached.
Single Column Model (scm)
The scm
flag is used for the single column model version of WRF.
It needs the periodic_x and periodic_y flags set to true, in which
case the X and Y directions are periodic. There is no collapsing of the grid
into a single location like the 3d-spherical polar flag implies.
sfc_elev_max_diff
The intent of the sfc_elev_max_diff
quality control check is to eliminate
surface observations that are mismatched from the WRF model’s surface elevation.
Mismatch can occur if the WRF land surface elevation is not finely resolved (coarse grid)
thus there is a significant representation mismatch between a point observation
and the WRF model. Assimilating surface observations with large mismatch can
deprecate assimilation forecast skill.
This check can only be applied to surface observations which are automatically
assigned to observations that use the VERTISSURFACE
vertical coordinate
defined in the obs_seq.out
file.
allow_obs_below_vol
The allow_obs_below_vol
enables vertical extrapolation in cases where the
observation vertical location is below the lowest WRF model vertical layer, thus
used as an alternative for the standard vertical interpolation routine.
The bottom WRF layer can vary based on total vertical levels, however, in general,
descends to (roughly) 10-50 meters above the surface and does not encompass common
surface observations at 2 and 10 meters. This is not recommended given
(linear) extrapolation is a poor approximation of surface observations at the
land-atmosphere boundary where energy and vapor exchange are controlled by
similarity theory. When using surface observations it is preferred
(and the default of the WRF model_mod.f90
) to operate on the WRF 2D
surface output (e.g. T2, U10) instead of WRF 3D output (e.g. T, THM) to
avoid the need for extrapolation.
Vortex option
The vortex searching namelist options are only required during WRF simulations where the spatial domain of interest is dynamic such as with a hurricane.
References
https://www2.mmm.ucar.edu/wrf/users/docs/user_guide_v4/contents.html