Chapter 3: WRF Standard Initialization

User's Guide for the NMM Core of the

Weather Research and Forecast (WRF)

Modeling System Version 2.2

Chapter 3: WRF Preprocessing System (WPS)

Preparing Input Data

Introduction

The WRF Preprocessing System (WPS) is a set of three programs whose collective role is to prepare input to the real_nmm.exe program. Each of the programs performs one stage of the preparation: geogrid defines model domains and interpolates static geographical data to the grids; ungrib extracts meteorological fields from GRIB-formatted files; and metgrid horizontally interpolates the meteorological fields extracted by ungrib to the model grids defined by geogrid. The work of vertically interpolating meteorological fields to the WRF vertical coordinates is now performed within the real_nmm.exe program, a task that was previously performed by the vinterp program in the WRF-NMM SI.

The data flow between the programs of the WPS is shown in the figure above. Each of the WPS programs reads parameters from a common namelist file, as shown in the figure. This namelist file has separate namelist records for each of the programs and a shared namelist record, which defines parameters that are used by more than one WPS program. Not shown in the figure are additional table files that are used by individual programs. These tables provide additional control over the programs’ operation, though they generally do not need to be changed by the user. The purpose, contents, and format of these tables are documented later in this chapter, and for now, the user need not be concerned with them.

The build mechanism for the WPS, which is very similar to the build mechanism used by the WRF model, provides options for compiling the WPS on a variety of platforms. The metgrid and geogrid programs may be run as a distributed memory job, which allows larger model domains to be processed in less time. The work performed by the ungrib program is not amenable to parallelization, so ungrib may only be run on a single processor.

Function of Each WPS Program

The WPS consists of three independent programs: geogrid, ungrib, and metgrid. Also included in the WPS are several utility programs, which are described in the section on utility programs. A brief description of each of the three main programs is given below, with further details presented in subsequent sections.

Program geogrid:

The purpose of geogrid is to define the simulation domains, and interpolate various terrestrial data sets to the model grids. The simulation domain is defined using information specified by the user in the “geogrid” namelist record of the WPS namelist file, namelist.wps. By default, and in addition to computing latitude and longitudes for every grid point, geogrid will interpolate soil categories, land use category, terrain height, annual mean deep soil temperature, monthly vegetation fraction, monthly albedo, maximum snow albedo, and slope category to the model grids. Global data sets for each of these fields are provided through the WRF-NMM Users Page, and only need to be downloaded once. Several of the data sets are available in only one resolution, but others are made available in resolutions of 30”, 2’, 5’, and 10’. The user may not need to download all available resolutions for a data set, although the interpolated fields will generally be more representative if a resolution of source data near to that of the simulation domain is used. Thus, users who expect to work with domains having grid spacings that cover a large range may wish to eventually download all available resolutions of the terrestrial data.

Besides interpolating the default terrestrial fields, the geogrid program is general enough to be able to interpolate most continuous and categorical fields to the simulation domains. New and additional data sets may be interpolated to the simulation domain through the use of the table file, GEOGRID.TBL. The GEOGRID.TBL file defines each of the fields that will be produced by geogrid; it describes the interpolation methods to be used for a field, as well as the location on the filesystem where the data set for that field is located.

Note: When running the WRF-NMM, WPS/geogrid/GEOGRID.TBL.NMM needs to be linked to WPS/geogrid/GEOGRID.TBL

Output from geogrid is written in the WRF I/O API format, and thus, by selecting the NetCDF I/O format, geogrid can be made to write its output in netCDF for easy visualization using the external software package ncview.

Program ungrib:

The ungrib program reads GRIB files, degribs the data, and writes the data in a simple format, called the intermediate format (see the section on writing data to the intermediate format for details of the format). The GRIB files contain time-varying meteorological fields and are typically from another regional or global model, such as NCEP's NAM or GFS models. The ungrib program can read GRIB Edition 1 and GRIB Edition 2 files.

GRIB files typically contain more fields than are needed to initialize WRF. Both versions of the GRIB format use various codes to identify the variables and levels in the GRIB file. Ungrib uses tables of these codes – called Vtables, for variable tables – to define which fields to extract from the GRIB file and write to the intermediate format. Details about the codes can be found in the WMO GRIB documentation and in documentation from the originating center. Vtables for common GRIB model output files are provided with the ungrib software.

Vtables are available for NAM 104 and 212 grids, the NAM AWIP format, GFS, the NCEP/NCAR Reanalysis archived at NCAR, RUC (pressure level data and hybrid coordinate data), and AFWA's AGRMET land surface model output. Users can create their own Vtable for other model output using any of the Vtables as a template.

Ungrib can write intermediate data files in any one of three user-selectable formats:

· WPS – a new format containing additional information useful for the downstream programs;

· SI – the previous intermediate format of the WRF system; and

· MM5 format – which is included here so that ungrib can be used to provide GRIB2 input to the MM5 modeling system.

Any of these formats may be used by WPS to initialize WRF, although the WPS format is recommended.

Program metgrid:

The metgrid program horizontally interpolates the intermediate-format meteorological data that are extracted by the ungrib program onto the simulation domains defined by the geogrid program. The interpolated metgrid output can then be ingested by the real_nmm.exe program. The range of dates that will be interpolated by metgrid are defined in the “share” namelist record of the WPS namelist file. Since the work of the metgrid program, like that of the ungrib program, is time-dependent, metgrid is run every time a new simulation is initialized.

Control over how each meteorological field is interpolated is provided by the METGRID.TBL file. The METGRID.TBL file provides one section for each field, and within a section, it is possible to specify options such as the interpolation methods to be used for the field, the field that acts as the mask to be used for masked interpolations, and the staggering (e.g., H, V in NMM) to which a field is to be interpolated.

Note: When running the WRF-NMM, WPS/metgrid/METGRID.TBL.NMM needs to be linked to WPS/metgrid/METGRID.TBL.

Output from metgrid is written in the WRF I/O API format, and thus, by selecting the NetCDF I/O format, metgrid can be made to write its output in netCDF for easy visualization using external software packages.

Running the WPS

Note: For software requirements and how to compile the WRF Preprocessing System package, see Chapter 2.

There are essentially three main steps to running the WRF Preprocessing System:

1. Define a model domain and nests with geogrid.

2. Extract meteorological data from GRIB data sets for the simulation period with ungrib.

3. Horizontally interpolate meteorological data to the model domains with metgrid.

When multiple simulations are to be run for the same model domains, it is only necessary to perform the first step once; thereafter, only time-varying data need to be processed for each simulation using steps two and three. Below, the details of each of the three steps are explained.

Step 1: Define model domains with geogrid.

The model domain and nests are defined in the “geogrid” namelist record of the namelist.wps file, and, in addition, parameters in the “share” namelist record need to be set. The user is referred to the description of namelist variables for more information on the purpose and possible values of each variable.

To summarize a set of typical changes to the “share” namelist record relevant to geogrid, the WRF dynamical core must first be selected with wrf_core, and the number of grids, including the coarsest grid, must be chosen with max_dom. Additionally, a location (if not the default - which is set to the current working directory) where domain files should be written may be chosen with opt_output_from_geogrid_path, and the format of these domain files may be changed with io_form_geogrid.

In the “geogrid” namelist record, the projection of the simulation domain is defined, as are the size and location of all model grids. Again, the user is referred to a description of the namelist variables for more details on the meaning and possible values for each variable.

Having suitably defined the simulation coarse domain (also see Creating Nested domains with the WPS), the geogrid.exe executable may be run to produce domain files by issuing the following command:

./geogrid.exe

After running geogrid.exe, the success message below should be displayed:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Successful completion of geogrid. !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

If not, the geogrid.log file may be consulted to determine the possible cause of failure.

The file suffix for the output file generated by geogrid will vary depending on the io_form_geogrid that is selected. The file prefix will depend on the wrf_core selection in the namelist (geo_nmm for NMM). For a NMM run using netCDF, the output file name for the coarse domain will be:

geo_nmm.d01.nc

For more information on checking the output of geogrid, the user is referred to the section on checking WPS output

Step 2: Extracting meteorological fields from GRIB files with ungrib.

Having already downloaded meteorological data in GRIB format, the first step in extracting fields to the intermediate format involves editing the “share” and “ungrib” namelist records of the namelist.wps file – the same file that was edited to define the simulation domains.

In the “share” namelist record, the variables that are relevant to ungrib are the starting and ending times of the coarsest grid (start_date and end_date) and the interval between meteorological data files (interval_seconds).

In the “ungrib” namelist record, out_format, defines the format of the intermediate data to be written by ungrib. The metgrid program can read any of the formats supported by ungrib, and thus, any of ‘WPS’, ‘SI’, or ‘MM5’ may be specified for out_format.

After suitably modifying the namelist.wps file, a Vtable must be supplied, and the GRIB files must be linked (or copied) to the filenames that are expected by ungrib. The WPS is supplied with Vtable files for many sources of meteorological data, and the appropriate Vtable may simply be symbolically linked to the file “Vtable,” which is the Vtable name expected by ungrib. For example, if the GRIB data are from the GFS model, this may be accomplished with the following command:

ln -sf ungrib/Variable_Tables/Vtable.GFS Vtable

The ungrib program will try to read GRIB files named GRIBFILE.AAA, GRIBFILE.AAB, …, GRIBFILE.ZZZ. In order to simplify the work of linking the GRIB files to these filenames, a shell script, link_grib.csh, is provided. The link_grib.csh script takes as a command-line argument a list of the GRIB files to be linked. For example, if the GRIB data were downloaded to the directory /wrf/gribdata/gfs, the files could be linked with link_grib.csh as in the following command:

link_grib.csh /wrf/gribdata/gfs/gfs_061101_12_*

After editing the namelist.wps file and linking the appropriate Vtable and GRIB files, the ungrib.exe executable may be run to produce files of meteorological data in intermediate format. Ungrib may be run by simply typing the following:

./ungrib.exe >& ungrib.log

Since the ungrib program may produce a significant volume of standard output, it is recommended that the standard output be redirected to a log file, as shown in the command above. If ungrib.exe runs successfully, the message

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Successful completion of ungrib. !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

will be written to the end of the ungrib.log file, and the intermediate files should appear in the current working directory. The intermediate files written by ungrib will have names of the form FILE:YYYY-MM-DD_HH.

Step 3: Horizontally interpolating meterological data with metgrid.

In the final step of running the WPS, meteorological data extracted by ungrib are horizontally interpolated to the simulation grids defined by geogrid. In order to run metgrid, the namelist.wps file must be edited. In particular, the “share” and “metgrid” namelist records are of relevance to the metgrid program.

By this point, there is generally no need to change any of the variables in the “share” namelist record, since those variables should have been suitably set in previous steps. If not, the WRF dynamical core, number of domains, starting and ending times, and path to the domain files must be set in the “share” namelist record.

In the “metgrid” namelist record, the path and prefix of the intermediate meteorological data files must be given with fg_name, and the output format for the horizontally interpolated files should be specified with the io_form_metgrid variable. Other variables in the “metgrid” namelist record, namely, opt_output_from_metgrid_path and opt_metgrid_tbl_path, allow the user to specify where interpolated data files should be written by metgrid and where the METGRID.TBL file may be found.

After suitably editing the namelist.wps file, metgrid may be run by issuing the command

./metgrid.exe

If metgrid successfully ran, the message

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Successful completion of metgrid. !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

will be printed. After successfully running, metgrid output files should appear in the current working directory (or in the directory specified by opt_output_from_metgrid_path, if not set to ‘./’). These files will be named met_nmm.d01.YYYY-MM-DD_HH:00:00. Here, YYYY-MM-DD_HH:00:00 refers to the date of the interpolated data in each file. If these files do not exist for each of the times in the range given in the “share” namelist record, the metgrid.log file may be consulted to help in determining the problem in running metgrid.

Creating Nested Domains with the WPS

At this time, the WRF-NMM supports only one-way stationary nests. The WRF-NMM nesting strategy is also targeted towards the future capability of moving nests. For this reason, time-invariant information, such as topography, soil type, albedo, etc. for a nest must be acquired over the entire domain of the coarsest grid even though, for a stationary nest, that information will only be used over the location where the nest is initialized.

Running the WPS for WRF-NMM nested-domain simulations is essentially no more difficult than running for a single-domain case; the geogrid program simply processes more than one grid when it is run, rather than a single grid.

The number of grids is unlimited. Grids may be located side by side (i.e. two nests may be children of the same parent and located on the same nest level), or telescopically nested. The nesting ratio for the WRF-NMM is always 3. Hence, the grid spacing of a nest is always 1/3 of its parent.

The nest level is dependant on the parent domain. If one nest is defined inside the coarsest domain, the nest level will be one and one additional static file will be created. If two nests are defined to have the same parent, again, only one additional static file will be created.

For example:

will create an output file for the parent domain: geo_nmm.d01.nc and one higher resolution output file for nest level one: geo_nmm_nest.l01.nc

If, however, two telescopic nests are defined (nest 1 inside the parent and nest 2 inside nest 1), then two additional static files will be created. Even if an additional nest 3 was added at the same grid spacing as nest1, or at the same grid spacing as nest 2, there would still be only two additional static files created.