.. index:: wrf_chem, WRF-Chem, WRF CHEM .. _wrf_unified: WRF WRF-Chem Unified Model Interface ==================================== DART interface module for the Weather Research and Forecasting `(WRF) `__ model including the WRF-Chem extension. 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``. The forward operator is computed from the first (highest resolution) domain that contains the lat/lon of the observation. During the assimilation phase, 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 fields from WRF that are read into the DART state vector are controlled by namelist. See below for the documentation on the &model_nml entries. 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. .. note:: PHB (base state geopotential) should be included in the state vector, but with the 'NO_COPY_BACK' option, which means that the values of PHB are not written back to the WRF netcdf file after the assimilation. 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. .. code-block:: text &model_nml wrf_state_variables = 'U', 'QTY_U_WIND_COMPONENT', 'UPDATE','999', 'V', 'QTY_V_WIND_COMPONENT', 'UPDATE','999', 'W', 'QTY_VERTICAL_VELOCITY', 'UPDATE','999', 'PH', 'QTY_GEOPOTENTIAL_HEIGHT', 'UPDATE','999', 'T', 'QTY_POTENTIAL_TEMPERATURE','UPDATE','999', 'MU', 'QTY_PRESSURE', 'UPDATE','999', 'QVAPOR','QTY_VAPOR_MIXING_RATIO', 'UPDATE','999', 'PSFC', 'QTY_SURFACE_PRESSURE', 'UPDATE','999', 'PHB', 'QTY_BASE_STATE_GEOP', 'NO_COPY_BACK', '999', wrf_state_bounds = 'QVAPOR','0.0','NULL', 'QRAIN', '0.0','NULL', 'QCLOUD','0.0','NULL', chem_state_variables = 'o3', 'QTY_O3', 'UPDATE', '999', 'no', 'QTY_NO', 'UPDATE', '999' chem_state_bounds = 'o3', '0.0', 'NULL' chemistry_separate_file = .true., num_domains = 1 calendar_type = 3 # GREGORIAN assimilation_period_seconds = 216001600 sfc_elev_max_diff = - 1.0 vert_localization_coord = 3 # VERTISHEIGHT allow_perturbed_ics = .false. # testing purposes only allow_obs_below_vol = .false. # Allow observations above the surface but below the lowest sigma level. log_vert_interp = .true. # Do the interpolation of pressure values only after taking the log log_horz_interpM = .false. log_horz_interpQ = .false. / Description of each namelist entry ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 25 15 60 * - Item - Type - Description * - wrf_state_variables - character(:,4) - A 2D array of strings, 4 per wrf field to be added to the dart state vector. The 4 strings are: #. WRF field name - must match netcdf name exactly #. DART QTY name - must match a valid DART QTY_xxx exactly #. 'UPDATE' or 'NO_COPY_BACK'. If 'UPDATE', the data is written to netcdf file after the assimilation. If 'NO_COPY_BACK', the data is not written back to the wrf netcdf file after the assimilation. #. A numeric string listing the domain numbers this array is part of. The special string 999 means all domains. For example, '12' means domains 1 and 2, '13' means 1 and 3. * - wrf_state_bounds - character(:,3) - A 2D array of strings, 3 per wrf array. During the writing of data to/from the wrf netcdf file, variables listed here will have minimum and maximum values enforced. The 3 strings are: #. WRF field name - must match netcdf name exactly #. Minimum -- specified as a string but must be a numeric value (e.g. '0.1'). Can be 'NULL' to allow any minimum value. #. Maximum -- specified as a string but must be a numeric value (e.g. '0.1'). Can be 'NULL' to allow any maximum value. * - chemistry_separate_file - logical - If .false., chemistry fields are in the same netcdf file as meterological fields, and the chemistry state fields and bounds should be specified in the wrf_state_variables and wrf_state_bounds arrays. If .true., chemistry fields are included in a separate netcdf file, and the chemistry fields and bounds should be specified in the chem_state_variables and chem_state_bounds arrays. * - chem_state_variables - character(:,4) - Chemistry state variables, same format as wrf_state_variables. Only used if chemistry_separate_file is .true. * - chem_state_bounds - character(:,3) - Chemistry state bounds, same format as wrf_state_bounds. Only used if `chemistry_separate_file` is .true. * - 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. * - sfc_elev_max_diff - real(r8) - TODO If > 0, the maximum difference, in meters, between an observation marked as a 'surface obs' as the vertical type (with the surface elevation, in meters, as the numerical vertical location), and the surface elevation as defined by the model. Observations further away from the surface than this threshold are rejected and not assimilated. If the value is negative, this test is skipped. * - vert_localization_coord - integer - Vertical coordinate for vertical localization. - 1 = model level - 2 = pressure (in pascals) - 3 = height (in meters) - 4 = scale height (unitless) * - allow_perturbed_ics - logical - Should not be used in most cases. Provided only for testing purposes to create a tiny ensemble for non-advancing tests. * - allow_obs_below_vol - logical - If .false., observations above the surface but below the lowest sigma level are rejected. If .true., code will extrapolate downward from data values at levels 1 and 2. * - log_vert_interp - logical - If .true., interpolation of pressure values is done after taking the log. * - log_horz_interpM - logical - If .true., horizontal interpolation for M grid points is done after taking the log. * - log_horz_interpQ - logical - If .true., horizontal interpolation for quad points is done after taking the log. References ---------- https://www2.mmm.ucar.edu/wrf/users/docs/user_guide_v4/contents.html