User’s Guide for Advanced Research WRF (ARW) Modeling System Version 2

Chapter 3: The WRF Preprocessing System (WPS) – Preparing Input Data

Table of Contents

• Introduction
• Function of Each WPS Program
• Installing the WPS
• Running the WPS
• Creating Nested Domains with the WPS
• Using Multiple Data Sources
• Parallelism in the WPS
• Checking WPS Output
• WPS Utility Programs
• Writing Meteorological Data to the Intermediate Format
• Creating and Editing Vtables
• Writing Static Data to the Geogrid Binary Format
• Description of Namelist Variables
• Description of GEOGRID.TBL Options
• Description of METGRID.TBL Options

Introduction

The WRF Preprocessing System (WPS) is a set of three programs whose collective role is to prepare input to the real.exe program for real-data simulations. 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 WRF eta levels is now performed within the real.exe program, a task that was previously performed by the vinterp program in the WRF 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 elsewhere, 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. When MPICH libraries and suitable compilers are available, the metgrid and geogrid programs may be compiled for distributed memory execution, 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 MMM website, 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 need not 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. However, 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.

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 external software packages, including ncview and the new release of RIP4.

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; further details on the meaning of fields in a Vtable are provided in the section on creating and editing Vtables.

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.exe program. The range of dates that will be interpolated by metgrid are defined in the “share” namelist record of the WPS namelist file, and date ranges must be specified individually in the namelist for each simulation domain. 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., U, V in ARW; H, V in NMM) to which a field is to be interpolated.

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, including the new version of RIP4.

Installing the WPS

The WRF Preprocessing System uses a build mechanism similar to that used by the WRF model. External libraries for geogrid and metgrid are limited to those required by the WRF model, since the WPS uses the WRF model's implementations of the I/O API; consequently, WRF must be compiled prior to installation of the WPS so that the I/O API libraries in the “external” directory of WRF will be available to WPS programs. Additionally, the ungrib program requires three compression libraries for GRIB Edition 2 support; however, if support for GRIB2 data is not needed, ungrib can be compiled without these compression libraries.

Required Libraries

The only library that is required to build the WRF model is NetCDF. The user can find the source code, precompiled binaries, and documentation at the UNIDATA home page (http://www.unidata.ucar.edu/software/netcdf/). Most users will select the NetCDF I/O option for WPS due to the easy access to utility programs that support the NetCDF data format.

Where WRF adds a software layer between the model and the communications package, the WPS parallel programs make MPI calls directly. Most multi-processor machines come preconfigured with a version of MPI, so it is unlikely that users will need to install this package by themselves.

Three libraries are required by the ungrib program for GRIB Edition 2 compression support. Users are encouraged to engage their system administrators for the installation of these packages so that traditional library paths and include paths are maintained. Paths to user-installed compression libraries are handled in the configure.wps file.

1) JasPer (an implementation of the JPEG2000 standard for "lossy" compression)

http://www.ece.uvic.ca/~mdadams/jasper/

Go down to “JasPer software”, one of the "click here" parts is the source.

> ./configure

> make

> make install

2) zlib (another compression library, which is used by the PNG library)

http://www.zlib.net/

Go to "The current release is publicly available here" section and download.

> ./configure

> make

> make install

3) PNG (compression library for "lossless" compression)

http://www.libpng.org/pub/png/libpng.html

Scroll down to "Source code" and choose a mirror site.

> ./configure

> make check

> make install

To get around portability issues, the NCEP GRIB libraries, w3 and g2, have been included in the WPS distribution. The original versions of these libraries are available for download from NCEP at http://www.nco.ncep.noaa.gov/pmb/codes/GRIB2/. The specific tar files to download are g2lib and w3lib. Because the ungrib program requires modules from these files, they are not suitable for usage with a traditional library option during the link stage of the build.

Required Compilers and Scripting Languages

The WPS requires the same Fortran and C compilers used to build the WRF model. The following table lists the currently supported operating system and compiler combinations for WPS.

Architecture	OS	Compiler
IBM POWER-4/5	AIX	xlf90
Compaq Alpha	OSF1	f90
PC x86	GNU/Linux 32-bit	PGI (pgf90)
PC x86	GNU/Linux 32-bit	Intel (ifort)
PC x86	GNU/Linux 32-bit	g95
PC x86_64	GNU/Linux 32-bit	PGI (pgf90)
PC x86_64	GNU/Linux 32-bit	PathScale (pathf90)
SGI	IRIX64	f90
SGI Altix	Linux	Intel (ifort)
Sun	SunOS	f90
Apple G5	OS X	xlf90

Installation Steps

• Download the WPS.tar.gz file and unpack it at the same directory level as WRFV2, as shown below.

>ls

-rw-r--r-- 1 537490 Oct 30 16:38 WPS.tar.gz

drwxr-xr-x 17 512 Oct 30 16:18 WRFV2

>tar xf WPS.tar.gz

>ls

drwxr-xr-x 8 512 Oct 30 16:38 WPS

-rw-r--r-- 1 537490 Oct 30 16:38 WPS.tar.gz

drwxr-xr-x 17 512 Oct 30 16:18 WRFV2

• At this point, a listing of the current working directory should at least include the directories WRFV2 and WPS. First, compile WRF (see the instructions for installing WRF). Then, after the WRF executables are generated, change to the WPS directory and issue the configure command followed by the compile command as below.

>cd WPS

>./configure

o Choose one of the configure options

>./compile >& compile.output

• After issuing the compile command, a listing of the current working directory should reveal symbolic links to executables for each of the three WPS programs: geogrid.exe, ungrib.exe, and metgrid.exe. If any of these links do not exist, check the compilation output in compile.output to see what went wrong.

>ls

drwxr-xr-x 2 512 Oct 30 16:38 arch

-rwxr-xr-x 1 1672 Sep 8 18:50 clean

-rwxr-xr-x 1 3349 Sep 12 11:11 compile

-rw-r--r-- 1 100168 Nov 1 10:02 compile.output

-rwxr-xr-x 1 4257 Jul 19 13:47 configure

-rw-r--r-- 1 2465 Nov 1 10:00 configure.wps

drwxr-xr-x 5 512 Nov 1 10:02 geogrid

lrwxrwxrwx 1 23 Nov 1 10:02 geogrid.exe -> geogrid/src/geogrid.exe

-rwxr-xr-x 1 1138 Aug 3 10:09 link_grib.csh

drwxr-xr-x 4 512 Nov 1 10:02 metgrid

lrwxrwxrwx 1 23 Nov 1 10:02 metgrid.exe -> metgrid/src/metgrid.exe

-rw-r--r-- 1 1638 Oct 30 11:54 namelist.wps

-rw-r--r-- 1 5074 Sep 15 13:05 README

drwxr-xr-x 7 512 Oct 30 16:38 test_suite

drwxr-xr-x 4 512 Nov 1 10:02 ungrib

lrwxrwxrwx 1 21 Nov 1 10:02 ungrib.exe -> ungrib/src/ungrib.exe

drwxr-xr-x 3 512 Nov 1 10:02 util

-rw-r--r-- 1 13 Oct 30 16:38 VERSION

Running the WPS

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.

In the root of the WPS directory structure, symbolic links to the programs geogrid.exe, ungrib.exe, and metgrid.exe should exist if the WPS software was successfully installed. In addition to these three links, a namelist.wps file should exist. Thus, a listing of the WPS root directory should look something like:

>ls

drwxr-xr-x 2 512 Oct 30 16:38 arch

-rwxr-xr-x 1 1672 Sep 8 18:50 clean

-rwxr-xr-x 1 3349 Sep 12 11:11 compile

-rw-r--r-- 1 100168 Nov 1 10:02 compile.output

-rwxr-xr-x 1 4257 Jul 19 13:47 configure

-rw-r--r-- 1 2465 Nov 1 10:00 configure.wps

drwxr-xr-x 5 512 Nov 1 10:02 geogrid

lrwxrwxrwx 1 23 Nov 1 10:02 geogrid.exe -> geogrid/src/geogrid.exe

-rwxr-xr-x 1 1138 Aug 3 10:09 link_grib.csh

drwxr-xr-x 4 512 Nov 1 10:02 metgrid

lrwxrwxrwx 1 23 Nov 1 10:02 metgrid.exe -> metgrid/src/metgrid.exe

-rw-r--r-- 1 1638 Oct 30 11:54 namelist.wps

-rw-r--r-- 1 5074 Sep 15 13:05 README

drwxr-xr-x 7 512 Oct 30 16:38 test_suite

drwxr-xr-x 4 512 Nov 1 10:02 ungrib

lrwxrwxrwx 1 21 Nov 1 10:02 ungrib.exe -> ungrib/src/ungrib.exe

drwxr-xr-x 3 512 Nov 1 10:02 util

-rw-r--r-- 1 13 Oct 30 16:38 VERSION

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. An example of these two namelist records is given below, and the user is referred to the description of namelist variables for more information on the purpose and possible values of each variable.

&share

wrf_core = 'ARW',

max_dom = 2,

start_date = '2006-08-16_12:00:00','2006-08-16_12:00:00',

end_date = '2006-08-16_18:00:00','2006-08-16_12:00:00',

interval_seconds = 21600

io_form_geogrid = 2,

opt_output_from_geogrid_path = './',

debug_level = 0

/

&geogrid

parent_id = 1, 1,

parent_grid_ratio = 1, 3,

i_parent_start = 1, 31

j_parent_start = 1, 17

s_we = 1, 1,

e_we = 74,112,

s_sn = 1, 1,

e_sn = 61,97,

geog_data_res = '10m','2m',

dx = 30000,

dy = 30000,

map_proj = 'lambert',

ref_lat = 34.83

ref_lon = -81.03

truelat1 = 30.0,

truelat2 = 60.0,

stand_lon = -98.

geog_data_path = '/data3a/mp/gill/DATA/GEOG'

opt_geogrid_tbl_path = 'geogrid/'

/

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 nests, including the mother domain, must be chosen with max_dom. Additionally, a location (if not the default – the current working directory) where domain files should be written to 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 and nested domains, the geogrid.exe executable may be run to produce domain files, which are named geo_em.d0N.nc, where N is the number of the nest defined in each file. It is important, to note that the geo_em prefix is used for ARW domain files, while the geo_nmm prefix is used for NMM domain files; also, the file suffix will vary depending on the io_form_geogrid that is selected. To run geogrid, issue the following command:

>geogrid.exe

After running geogrid.exe, the success message

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

should be printed, and a listing of the WPS root directory (or the directory specified by opt_output_from_geogrid_path, if not ‘./’) should show the domain files. If not, the geogrid.log file may be consulted in an attempt to determine the possible cause of failure. For more information on checking the output of geogrid, the user is referred to the section on checking WPS output.

>ls

drwxr-xr-x 2 512 Oct 30 16:38 arch

-rwxr-xr-x 1 1672 Sep 8 18:50 clean

-rwxr-xr-x 1 3349 Sep 12 11:11 compile

-rw-r--r-- 1 100168 Nov 1 10:02 compile.output

-rwxr-xr-x 1 4257 Jul 19 13:47 configure

-rw-r--r-- 1 2465 Nov 1 10:00 configure.wps

-rw-r--r-- 1 1831720 Nov 1 10:22 geo_em.d01.nc

-rw-r--r-- 1 4443720 Nov 1 10:22 geo_em.d02.nc

drwxr-xr-x 5 512 Nov 1 10:02 geogrid

lrwxrwxrwx 1 23 Nov 1 10:02 geogrid.exe -> geogrid/src/geogrid.exe

-rw-r--r-- 1 9672 Nov 1 10:22 geogrid.log

-rwxr-xr-x 1 1138 Aug 3 10:09 link_grib.csh

drwxr-xr-x 4 512 Nov 1 10:02 metgrid

lrwxrwxrwx 1 23 Nov 1 10:02 metgrid.exe -> metgrid/src/metgrid.exe

-rw-r--r-- 1 1638 Oct 30 11:54 namelist.wps

-rw-r--r-- 1 5074 Sep 15 13:05 README

drwxr-xr-x 7 512 Oct 30 16:38 test_suite

drwxr-xr-x 4 512 Nov 1 10:02 ungrib

lrwxrwxrwx 1 21 Nov 1 10:02 ungrib.exe -> ungrib/src/ungrib.exe

drwxr-xr-x 3 512 Nov 1 10:02 util

-rw-r--r-- 1 13 Oct 30 16:38 VERSION

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. An example of the two namelist records is given below.

&share

wrf_core = 'ARW',

max_dom = 2,

start_date = '2006-08-16_12:00:00','2006-08-16_12:00:00',

end_date = '2006-08-16_18:00:00','2006-08-16_12:00:00',

interval_seconds = 21600

io_form_geogrid = 2,

opt_output_from_geogrid_path = './',

debug_level = 0

/

&ungrib
out_format = 'WPS',

prefix = 'FILE'
/

In the “share” namelist record, the variables that are of relevance to ungrib are the starting and ending times of the mother domain (start_year, start_month, start_day, start_hour, end_year, end_month, end_day, and end_hour) and the interval between meteorological data files (interval_seconds). In the “ungrib” namelist record, the only variable, 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’, and ‘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

>ln -s 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 /mmmtmp/mm5rt/data/gfs, the files could be linked with link_grib.csh as in the following commands:

>ls /mmmtmp/mm5rt/data/gfs

-rw-r--r-- 1 24008620 Nov 1 08:25 gfs_060816_12_00

-rw-r--r-- 1 27106796 Nov 1 08:28 gfs_060816_12_06

>link_grib.csh /mmmtmp/mm5rt/data/gfs/gfs_061101_12_*

After linking the GRIB files and Vtable, a listing of the WPS directory should look something like the following:

>ls

drwxr-xr-x 2 512 Oct 30 16:38 arch

-rwxr-xr-x 1 1672 Sep 8 18:50 clean

-rwxr-xr-x 1 3349 Sep 12 11:11 compile

-rw-r--r-- 1 100168 Nov 1 10:02 compile.output

-rwxr-xr-x 1 4257 Jul 19 13:47 configure

-rw-r--r-- 1 2465 Nov 1 10:00 configure.wps

-rw-r--r-- 1 1831720 Nov 1 10:22 geo_em.d01.nc

-rw-r--r-- 1 4443720 Nov 1 10:22 geo_em.d02.nc

drwxr-xr-x 5 512 Nov 1 10:02 geogrid

lrwxrwxrwx 1 23 Nov 1 10:02 geogrid.exe -> geogrid/src/geogrid.exe

-rw-r--r-- 1 9672 Nov 1 10:22 geogrid.log

lrwxrwxrwx 1 39 Nov 1 10:35 GRIBFILE.AAA -> /mmmtmp/mm5rt/data/gfs/gfs_060816_12_00

lrwxrwxrwx 1 39 Nov 1 10:35 GRIBFILE.AAB -> /mmmtmp/mm5rt/data/gfs/gfs_060816_12_06

-rwxr-xr-x 1 1138 Aug 3 10:09 link_grib.csh

drwxr-xr-x 4 512 Nov 1 10:02 metgrid

lrwxrwxrwx 1 23 Nov 1 10:02 metgrid.exe -> metgrid/src/metgrid.exe

-rw-r--r-- 1 1638 Oct 30 11:54 namelist.wps

-rw-r--r-- 1 5074 Sep 15 13:05 README

drwxr-xr-x 7 512 Oct 30 16:38 test_suite

drwxr-xr-x 4 512 Nov 1 10:02 ungrib

lrwxrwxrwx 1 21 Nov 1 10:02 ungrib.exe -> ungrib/src/ungrib.exe

drwxr-xr-x 3 512 Nov 1 10:02 util

-rw-r--r-- 1 13 Oct 30 16:38 VERSION

lrwxrwxrwx 1 33 Nov 1 10:35 Vtable -> ungrib/Variable_Tables/Vtable.GFS

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 output, it is recommended that ungrib 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.

>ls

drwxr-xr-x 2 512 Oct 30 16:38 arch

-rwxr-xr-x 1 1672 Sep 8 18:50 clean

-rwxr-xr-x 1 3349 Sep 12 11:11 compile

-rw-r--r-- 1 100168 Nov 1 10:02 compile.output

-rwxr-xr-x 1 4257 Jul 19 13:47 configure

-rw-r--r-- 1 2465 Nov 1 10:00 configure.wps

-rw-r--r-- 1 38869928 Nov 1 10:44 FILE:2006-08-16_12

-rw-r--r-- 1 38869928 Nov 1 10:44 FILE:2006-08-16_18

-rw-r--r-- 1 1831720 Nov 1 10:22 geo_em.d01.nc

-rw-r--r-- 1 4443720 Nov 1 10:22 geo_em.d02.nc

drwxr-xr-x 5 512 Nov 1 10:02 geogrid

lrwxrwxrwx 1 23 Nov 1 10:02 geogrid.exe -> geogrid/src/geogrid.exe

-rw-r--r-- 1 9672 Nov 1 10:22 geogrid.log

lrwxrwxrwx 1 39 Nov 1 10:35 GRIBFILE.AAA -> /mmmtmp/mm5rt/data/gfs/gfs_060816_12_00

lrwxrwxrwx 1 39 Nov 1 10:35 GRIBFILE.AAB -> /mmmtmp/mm5rt/data/gfs/gfs_060816_12_06

-rwxr-xr-x 1 1138 Aug 3 10:09 link_grib.csh

drwxr-xr-x 4 512 Nov 1 10:02 metgrid

lrwxrwxrwx 1 23 Nov 1 10:02 metgrid.exe -> metgrid/src/metgrid.exe

-rw-r--r-- 1 1638 Nov 1 10:42 namelist.wps

-rw-r--r-- 1 5074 Sep 15 13:05 README

drwxr-xr-x 7 512 Oct 30 16:38 test_suite

drwxr-xr-x 4 512 Nov 1 10:02 ungrib

lrwxrwxrwx 1 21 Nov 1 10:02 ungrib.exe -> ungrib/src/ungrib.exe

-rw-r--r-- 1 29754 Nov 1 10:44 ungrib.log

drwxr-xr-x 3 512 Nov 1 10:02 util

-rw-r--r-- 1 13 Oct 30 16:38 VERSION

lrwxrwxrwx 1 33 Nov 1 10:35 Vtable -> ungrib/Variable_Tables/Vtable.GFS

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. Examples of these records are shown below.

&share

wrf_core = 'ARW',

max_dom = 2,

start_date = '2006-08-16_12:00:00','2006-08-16_12:00:00',

end_date = '2006-08-16_18:00:00','2006-08-16_12:00:00',

interval_seconds = 21600

io_form_geogrid = 2,

opt_output_from_geogrid_path = './',

debug_level = 0

/

&metgrid
fg_name = './FILE'
io_form_metgrid = 2,
opt_output_from_metgrid_path = './',
opt_metgrid_tbl_path = 'metgrid/',
/

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 WPS root directory (or in the directory specified by opt_output_from_metgrid_path, if not set to ‘./’). These files will be named met_em.d0N.YYYY-MM-DD_HH:00:00 in the case of ARW domains, where N is the number of the nest whose data reside in the file, or met_nmm.d0N.YYYY-MM-DD_HH:00:00 in the case of NMM domains. 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.

>ls

drwxr-xr-x 2 512 Oct 30 16:38 arch

-rwxr-xr-x 1 1672 Sep 8 18:50 clean

-rwxr-xr-x 1 3349 Sep 12 11:11 compile

-rw-r--r-- 1 100168 Nov 1 10:02 compile.output

-rwxr-xr-x 1 4257 Jul 19 13:47 configure

-rw-r--r-- 1 2465 Nov 1 10:00 configure.wps

-rw-r--r-- 1 38869928 Nov 1 10:44 FILE:2006-08-16_12

-rw-r--r-- 1 38869928 Nov 1 10:44 FILE:2006-08-16_18

-rw-r--r-- 1 1831720 Nov 1 10:22 geo_em.d01.nc

-rw-r--r-- 1 4443720 Nov 1 10:22 geo_em.d02.nc

drwxr-xr-x 5 512 Nov 1 10:02 geogrid

lrwxrwxrwx 1 23 Nov 1 10:02 geogrid.exe -> geogrid/src/geogrid.exe

-rw-r--r-- 1 9672 Nov 1 10:22 geogrid.log

lrwxrwxrwx 1 39 Nov 1 10:35 GRIBFILE.AAA -> /mmmtmp/mm5rt/data/gfs/gfs_060816_12_00

lrwxrwxrwx 1 39 Nov 1 10:35 GRIBFILE.AAB -> /mmmtmp/mm5rt/data/gfs/gfs_060816_12_06

-rwxr-xr-x 1 1138 Aug 3 10:09 link_grib.csh

-rw-r--r-- 1 5092340 Nov 1 10:58 met_em.d01.2006-08-16_12:00:00.nc

-rw-r--r-- 1 5092340 Nov 1 10:58 met_em.d01.2006-08-16_18:00:00.nc

-rw-r--r-- 1 12356572 Nov 1 10:58 met_em.d02.2006-08-16_12:00:00.nc

drwxr-xr-x 4 512 Nov 1 10:02 metgrid

lrwxrwxrwx 1 23 Nov 1 10:02 metgrid.exe -> metgrid/src/metgrid.exe

-rw-r--r-- 1 62170 Nov 1 10:58 metgrid.log

-rw-r--r-- 1 1638 Nov 1 10:58 namelist.wps

-rw-r--r-- 1 5074 Sep 15 13:05 README

drwxr-xr-x 7 512 Oct 30 16:38 test_suite

drwxr-xr-x 4 512 Nov 1 10:02 ungrib

lrwxrwxrwx 1 21 Nov 1 10:02 ungrib.exe -> ungrib/src/ungrib.exe

-rw-r--r-- 1 29754 Nov 1 10:44 ungrib.log

drwxr-xr-x 3 512 Nov 1 10:02 util

-rw-r--r-- 1 13 Oct 30 16:38 VERSION

lrwxrwxrwx 1 33 Nov 1 10:35 Vtable -> ungrib/Variable_Tables/Vtable.GFS

Creating Nested Domains with the WPS

To run the WPS for nested-domain simulations is essentially no more difficult than running for a single-domain case; the difference with nested-domain simulations is that the geogrid and metgrid programs process more than one grid when they are run, rather than the sole grid for the simulation. In order to specify the size and location of nests, a number of variables in the namelist.wps file must be given lists of values, one value per nest.

&share

wrf_core = 'ARW',

max_dom = 2,

start_date = '2006-08-16_12:00:00','2006-08-16_12:00:00',

end_date = '2006-08-16_18:00:00','2006-08-16_12:00:00',

interval_seconds = 21600

io_form_geogrid = 2,

opt_output_from_geogrid_path = './',

debug_level = 0

/

&geogrid

parent_id = 1, 1,

parent_grid_ratio = 1, 3,

i_parent_start = 1, 31,

j_parent_start = 1, 17,

s_we = 1, 1,

e_we = 74,112,

s_sn = 1, 1,

e_sn = 61, 97,

geog_data_res = '10m','2m',

dx = 30000,

dy = 30000,

map_proj = 'lambert',

ref_lat = 34.83

ref_lon = -81.03

truelat1 = 30.0,

truelat2 = 60.0,

stand_lon = -98.

geog_data_path = '/data3a/mp/gill/DATA/GEOG'

opt_geogrid_tbl_path = 'geogrid/'

/

The namelist variables that are affected by nests are shown in the (partial) namelist records above. The example shows namelist variables for a two-domain run (the coarse domain plus a single nest), though the effect on the namelist variables generalize to multiple nests in the obvious way; that is, rather than specifying lists of two values, lists of N values must be specified, where N is the total number of model grids.

In the above example, the first change to the “share” namelist record is to the max_dom variable, which must be set to the total number of nests in the simulation, including the coarse domain. Having determined the number of nests, say N, all of the other affected namelist variables must be given a list of N values, one for each nest. The only other change to the “share” namelist record is to the starting and ending times. Here, a starting and ending time must be given for each nest, with the restriction that a nest cannot begin before its parent domain or end after its parent domain; also, it is suggested that nests be given starting and ending times that are identical to the desired starting times of the nest when running WPS. This is because the nests get their lateral boundary conditions from their parent domain, and thus, only the initial time for a nest needs to be processed by WPS. It is important to note that, when running WRF, the actual starting and ending times for all nests must be given in the WRF namelist.input file.

The remaining changes are to the “geogrid” namelist record. In this record, the parent of each nest must be specified with the parent_id variable. Every nest must be a child of exactly one other nest, with the coarse domain being its own parent. Related to the parent of a nest is the nest refinement ratio with respect to a nest’s parent, which is given by the parent_grid_ratio variable; this ratio determines the nominal grid spacing for a nest in relation to the grid spacing of the its parent.

Next, the lower-left corner of a nest is specified as an (i, j) location in the nest’s parent domain; this is done through the i_parent_start and j_parent_start variables, and the specified location is given with respect to the unstaggered grid. Finally, the dimensions of each nest, in grid points, are given for each nest using the s_we, e_we, s_sn, and e_sn variables. The nesting setup in our example is shown in the figure above, where it may be seen how each of the above-mentioned variables is found. Currently, the starting grid point values in the south-north (s_sn) and west-east (s_we) directions must be specified as 1, and the ending grid point values (e_sn and e_we) determine, essentially, the full dimensions of the nest; to ensure that the upper-right corner of the nest's grid is coincident with an unstaggered grid point in the parent domain, both e_we and e_sn must be one greater than some integer multiple of the nesting ratio. Also, for each nest, the resolution of source data to interpolate from is specified with the geog_data_res variable. For a complete description of these namelist variables, the user is referred to the description of namelist variables.

Using Multiple Data Sources

The metgrid program is capable of interpolating time-invariant fields, and it can also interpolate from multiple sources of meteorological data. The first of these capabilities uses the constants_name variable in the &metgrid namelist record. This variable may be set to a list of filenames – including path information where necessary – of intermediate-formatted files which contains time-invariant fields, and which should be used in the output for every time period processed by metgrid. For example, short simulations may use a constant SST field; this field need only be available at a single time, and may be used by setting the constants_name variable to the path and filename of the SST file. Typical uses of constants_name might look like

&metgrid
constants_name = '/data/ungribbed/constants/SST_FILE:2006-08-16_12'
/

or

&metgrid
constants_name = 'LANDSEA', 'SOILHGT'
/

The second metgrid capability – that of interpolating data from multiple sources – may be useful in situations where two or more complementary data sets need to be combined to produce the full input data needed by real.exe. To interpolate from multiple sources of time-varying, meteorological data, the fg_name variable in the &metgrid namelist record should be set to a list of prefixes of intermediate files, including path information when necessary. When multiple path-prefixes are given, and the same meteorological field is available from more than one of the sources, data from the last-specified source will take priority over all preceding sources. Thus, data sources may be prioritized by the order in which the sources are given.

As an example of this capability, if surface fields are given in one data source and upper-air data are given in another, the values assigned to the fg_name variable may look something like:

&metgrid
fg_name = '/data/ungribbed/SFC', '/data/ungribbed/UPPER_AIR'
/

To simplify the process of extracting fields from GRIB files, the prefix namelist variable in the &ungrib record may be employed. This variable allows the user to control the names of (and paths to) the intermediate files that are created by ungrib. The utility of this namelist variable is most easily illustrated by way of an example. Suppose we wish to work with the North American Regional Reanalysis (NARR) data set, which is split into separate GRIB files for 3-dimensional atmospheric data, surface data, and fixed-field data. We may begin by linking all of the "3D" GRIB files using the link_grib.csh script, and by linking the NARR Vtable to the filename Vtable. Then, we may suitably edit the &ungrib namelist record before running ungrib.exe so that the resulting intermediate files have an appropriate prefix:

&ungrib

out_format = 'WPS',
prefix = 'NARR_3D',
/

After running ungrib.exe, the following files should exist (with a suitable substitution for the appropriate dates):

NARR_3D:1979-01-01_00

NARR_3D:1979-01-01_03

NARR_3D:1979-01-01_06

...

Given intermediate files for the 3-dimensional fields, we may process the surface fields by linking the surface GRIB files and changing the prefix variable in the namelist:

&ungrib

out_format = 'WPS',
prefix = 'NARR_SFC',
/

Again running ungrib.exe, the following should exist in addition to the NARR_3D files:

NARR_SFC:1979-01-01_00

NARR_SFC:1979-01-01_03

NARR_SFC:1979-01-01_06

...

Finally, the fixed file is linked with the link_grib.csh script, and the prefix variable in the namelist is again set:

&ungrib

out_format = 'WPS',
prefix = 'NARR_FIXED',
/

Having run ungrib.exe for the third time, the fixed fields should be available in addition to the surface and "3D" fields:

NARR_FIXED:1979-11-08_00

For the sake of clarity, the fixed file may be renamed to remove any date information, for example, by renaming to simply NARR_FIXED, since the fields in the file are static. In this example, we note that the NARR fixed data are only available at a specific time, 1979 November 08 at 0000 UTC, and thus, the user would need to set the correct starting and ending time for the data in the &share namelist record before running ungrib on the NARR fixed file; of course, the times should be re-set before metgrid is run. Given intermediate files for all three parts of the NARR data set, metgrid.exe may be run after the constants_name and fg_name variables in the &metgrid namelist record are set:

&metgrid

constants_name = 'NARR_FIXED',
fg_name = 'NARR_3D', 'NARR_SFC'

/

Although less common, another situation where multiple data sources would be required is when a source of meteorological data from a regional model is insufficient to cover the entire simulation domain, and data from a larger regional model, or a global model, must be used when interpolating to the remaining points of the simulation grid.

For example, to use NAM data wherever possible, and GFS data elsewhere, the following values might be assigned in the namelist:

&metgrid
fg_name = '/data/ungribbed/GFS', '/data/ungribbed/NAM'
/

Then the resulting model domain would use data as shown in the figure below.

If no field is found in more than one source, then no prioritization need be applied by metgrid, and each field will simply be interpolated as usual; of course, each source should cover the entire simulation domain to avoid areas of missing data.

Parallelism in the WPS

If the dimensions of the domains to be processed by the WPS become too large to fit in the memory of a single CPU, it is possible to run the geogrid and metgrid programs in a distributed memory configuration. In order to compile geogrid and metgrid for distributed memory execution, the user must have MPI libraries installed on the target machine, and must have compiled WPS using one of the "DM parallel" configuration options. Upon successful compilation, the geogrid and metgrid programs may be run with the mpirun command or through a batch queuing system, depending on the machine.

As mentioned earlier, the work of the ungrib program is not amenable to parallelization, and, further, the memory requirements for ungrib's processing are independent of the memory requirements of geogrid and metgrid; thus, ungrib is always compiled for a single processor and run on a single CPU, regardless of whether a "DM parallel" configuration option was selected during configuration.

Each of the standard WRF I/O API formats (NetCDF, GRIB1, binary) has a corresponding parallel format, whose number is given by adding 100 to the io_form value (e.g., io_form_geogrid) for the standard format. It is not necessary to use a parallel io_form, but when one is used, each CPU will read (write) its input (output) to a separate file, whose name is simply the name that would be used during serial execution, but with a four-digit processor ID appended to the name. For example, running geogrid on four processors with io_form_geogrid=102 would create output files named geo_em.d01.nc.0000, geo_em.d01.nc.0001, geo_em.d01.nc.0002, and geo_em.d01.nc.0003 for the coarse domain.

During distributed-memory execution, model domains are decomposed into rectangular patches, with each processor working on a single patch. When reading (writing) from (to) the WRF I/O API format, each processor reads (writes) only its patch. Consequently, if a parallel io_form is chosen for the output of geogrid, metgrid must be run using the same number of processors as were used to run geogrid. Similarly, if a parallel io_form is chosen for the metgrid output files, the real.exe program must be run using the same number of processors. Of course, it is still possible to use a standard io_form when running on multiple processors, in which case all data for the model domain will be distributed (collected) upon input (output). As a final note, when geogrid or metgrid are run on multiple processors, each processor will write its own log file, with the log file names being appended with the same four-digit processor ID numbers that are used for the I/O API files.

Checking WPS Output

When running the WPS, it may be helpful to examine the output produced by the programs. For example, when determining the location of nests, it may be helpful to see the interpolated static geographical data and latitude/longitude fields. As another example, when importing a new source of data into WPS – either static data or meteorological data – it can often be helpful to check the resulting interpolated fields in order to make adjustments the interpolation methods used by geogrid or metgrid.

By using the NetCDF format for the geogrid and metgrid I/O forms, a variety of visualization tools that read NetCDF data may be used to check the domain files processed by geogrid or the horizontally interpolated meteorological fields produced by metgrid. In order to set the file format for geogrid and metgrid to NetCDF, the user should specify 2 as the io_form_geogrid and io_form_metgrid in the WPS namelist file:

&share
io_form_geogrid = 2,
/

&metgrid
io_form_metgrid = 2,
/

Among the available tools, the ncdump, ncview, and new RIP4 programs may be of interest. The ncdump program is a compact utility distributed with the NetCDF libraries that lists the variables and attributes in a NetCDF file. This can be useful, in particular, for checking the domain parameters (e.g., west-east dimension, south-north dimension, or domain center point) in geogrid domain files, or for listing the fields in a file. The ncview program provides an interactive way to view fields in NetCDF files. Also, for users wishing to produce plots of fields suitable for use in publications, the new release of the RIP4 program may be of interest. The new RIP4 is capable of plotting horizontal contours, map backgrounds, and overlaying multiple fields within the same plot.

Output from the ungrib program is always written in a simple binary format (either ‘WPS’, ‘SI’, or ‘MM5’), so software for viewing NetCDF files will almost certainly be of no use. However, an NCAR Graphics-based utility, plotfmt.exe, is supplied with the WPS source code. This utility produces contour plots of the fields found in an intermediate-format file. If the NCAR Graphics libraries are properly installed, the plotfmt.exe program is automatically compiled, along with other utility programs, when WPS is built.

WPS Utility Programs

Besides the three main WPS programs – geogrid, ungrib, and metgrid – there are a number of utility programs that come with WPS, and are compiled in the util directory. These utilities may be used to examine data files, visualize the location of nested domains, and compute average surface temperature fields.

A. avg_tsfc.exe

The avg_tsfc.exe program computes a daily mean surface temperature given input files in the intermediate format. Based on the range of dates specified in the "share" namelist section of the namelist.wps file, and also considering the interval between intermediate files, avg_tsfc.exe will use as many complete days' worth of data as possible in computing the average, beginning at the starting date specified in the namelist. If a complete day's worth of data is not available, no output file will be written, and the program will halt as soon as this can be determined. Similarly, any intermediate files for dates that cannot be used as part of a complete 24-hour period are ignored; for example, if there are five intermediate files available at a six-hour interval, the last file would be ignored. The computed average field is written to a new file named TAVGSFC using the same intermediate format version as the input files. This daily mean surface temperature field can then be ingested by metgrid by specifying 'TAVGSFC' for the constants_name variable in the "metgrid" namelist section.

B. mod_levs.exe

The mod_levs.exe program is used to remove levels of data from intermediate format files. The levels which are to be kept are specified in new namelist record in the namelist.wps file:

&mod_levs

press_pa = 201300 , 200100 , 100000 ,

95000 , 90000 ,

85000 , 80000 ,

75000 , 70000 ,

65000 , 60000 ,

55000 , 50000 ,

45000 , 40000 ,

35000 , 30000 ,

25000 , 20000 ,

15000 , 10000 ,

5000 , 1000

/

Within the &mod_levs namelist record, the variable press_pa is used to specify a list of levels to keep; the specified levels should match values of xlvl in the intermediate format files (see the discussion of the WPS intermediate format for more information on the fields of the intermediate files). The mod_levs program takes two command-line arguments as its input. The first argument is the name of the intermediate file to operate on, and the second argument is the name of the output file to be written.

Removing all but a specified subset of levels from meteorological data sets is particularly useful, for example, when one data set is to be used for the model initial conditions and a second data set is to be used for the lateral boundary conditions. This can be done by providing the initial conditions data set at the first time period to be interpolated by metgrid, and the boundary conditions data set for all other times. If the both data sets have the same number of vertical levels, then no work needs to be done; however, when these two data sets have a different number of levels, it will be necessary, at a minimum, to remove (m – n) levels, where m > n and m and n are the number of levels in each of the two data sets, from the data set with m levels. The necessity of having the same number of vertical levels in all files is due to a limitation in real.exe, which requires a constant number of vertical levels to interpolate from.

The mod_levs utility is something of a temporary solution to the problem of accommodating two or more data sets with differing numbers of vertical levels. Should a user choose to use mod_levs, it should be noted that, although the vertical locations of the levels need not match between data sets, all data sets should have a surface level of data, and, when running real.exe and wrf.exe, the value of p_top must be chosen to be below the lowest top among the data sets.

C. plotgrids.exe

The plotgrids.exe program is an NCAR Graphics-based utility whose purpose is to plot the locations of all nests defined in the namelist.wps file. The program operates on the namelist.wps file, and thus, may be run without having run any of the three main WPS programs. Upon successful completion, plotgrids produces an NCAR Graphics metafile, gmeta, which may be viewed using the idt command. The coarse domain is drawn to fill the plot frame, a map outline with political boundaries is drawn over the coarse domain, and any nested domains are drawn as rectangles outlining the extent of each nest. This utility may be useful particularly during initial placement of domains, at which time the user can iteratively adjust the locations of nests by editing the namelist.wps file, running plotgrids.exe, and determining a set of adjustments to the nest locations.

D. g1print.exe

The g1print.exe program takes as its only command-line argument the name of a GRIB Edition 1 file. The program prints a listing of the fields, levels, and dates of the data in the file.

E. g2print.exe

Similar to g1print.exe, the g2print.exe program takes as its only command-line argument the name of a GRIB Edition 2 file. The program prints a listing of the fields, levels, and dates of the data in the file.

F. plotfmt.exe

The plotfmt.exe is an NCAR Graphics program that plots the contents of an intermediate format file. The program takes as its only command-line argument the name of the file to plot, and produces an NCAR Graphics metafile, which contains contour plots of each field in input file. The graphics metafile output, gmeta, may be viewed with the idt command, or converted to another format using utilities such as ctrans.

G. rd_intermediate.exe

Given the name of a singe intermediate format file on the command line, the rd_intermediate.exe program prints information about the fields contained in the file.

Writing Meteorological Data to the Intermediate Format

The role of the ungrib program is to decode GRIB data sets into a simple intermediate format that is understood by metgrid. If meteorological data are not available in GRIB Edition 1 or GRIB Edition 2 formats, the user is responsible for writing such data into the intermediate file format. Fortunately, the intermediate format is relatively simple, consisting of a sequence of unformatted Fortran writes. It is important to note that these unformatted writes use big-endian byte order, which can typically be specified with compiler flags. Below, we describe the WPS intermediate format; users interested in the SI or MM5 intermediate formats can first gain familiarity with the WPS format, which is very similar, and later examine the Fortran subroutines that read and write all three intermediate formats (metgrid/src/read_met_module.F90 and metgrid/src/write_met_module.F90, respectively).

When writing data to the WPS intermediate format, 2-dimensional fields are written as a rectangular array of real values. 3-dimensional arrays must be split across the vertical dimension into 2-dimensional arrays, which are written independently. The sequence of writes used to write a single 2-dimensional array in the WPS intermediate format is as follows (note that not all of the variables declared below are used for a given projection of the data).

integer :: version ! Format version (must =5 for WPS format)

integer :: nx, ny ! x- and y-dimensions of 2-d array

integer :: iproj ! Code for projection of data in array:

! 0 = cylindrical equidistant

! 1 = Mercator

! 3 = Lambert conformal conic

! 4 = Gaussian

! 5 = Polar stereographic

integer :: nlats ! Number of latitudes north of equator

! (for Gaussian grids)

real :: xfcst ! Forecast hour of data

real :: xlvl ! Vertical level of data in 2-d array

real :: startlat, startlon ! Lat/lon of point in array indicated by

! startloc string

real :: deltalat, deltalon ! Grid spacing, degrees

real :: dx, dy ! Grid spacing, km

real :: xlonc ! Standard longitude of projection

real :: truelat1, truelat2 ! True latitudes of projection

real :: earth_radius ! Earth radius, km

real, dimension(nx,ny) :: slab ! The 2-d array holding the data

logical :: is_wind_grid_rel ! Flag indicating whether winds are

! relative to source grid (TRUE) or

! relative to earth (FALSE)

character (len=8) :: startloc ! Which point in array is given by

! startlat/startlon; set either

! to 'SWCORNER' or 'CENTER '

character (len=9) :: field ! Name of the field

character (len=24) :: hdate ! Valid date for data YYYY:MM:DD_HH:00:00

character (len=25) :: units ! Units of data

character (len=32) :: map_source ! Source model / originating center

character (len=46) :: desc ! Short description of data

! 1) WRITE FORMAT VERSION

write(unit=ounit) version

! 2) WRITE METADATA

! Cylindrical equidistant

if (iproj == 0) then

write(unit=ounit) hdate, xfcst, map_source, field, &

units, desc, xlvl, nx, ny, iproj

write(unit=ounit) startloc, startlat, startlon, &

deltalat, deltalon, earth_radius

! Mercator

else if (iproj == 1) then

write(unit=ounit) hdate, xfcst, map_source, field, &

units, desc, xlvl, nx, ny, iproj

write(unit=ounit) startloc, startlat, startlon, dx, dy, &

truelat1, earth_radius

! Lambert conformal

else if (iproj == 3) then

write(unit=ounit) hdate, xfcst, map_source, field, &

units, desc, xlvl, nx, ny, iproj

write(unit=ounit) startloc, startlat, startlon, dx, dy, &

xlonc, truelat1, truelat2, earth_radius

! Gaussian

else if (iproj == 4) then

write(unit=ounit) hdate, xfcst, map_source, field, &

units, desc, xlvl, nx, ny, iproj

write(unit=ounit) startloc, startlat, startlon, &

nlats, deltalon, earth_radius

! Polar stereographic

else if (iproj == 5) then

write(unit=ounit) hdate, xfcst, map_source, field, &

units, desc, xlvl, nx, ny, iproj

write(unit=ounit) startloc, startlat, startlon, dx, dy, &

xlonc, truelat1, earth_radius

end if

! 3) WRITE WIND ROTATION FLAG

write(unit=ounit) is_wind_grid_rel

! 4) WRITE 2-D ARRAY OF DATA

write(unit=ounit) slab

Creating and Editing Vtables

Although Vtables are provided for many common data sets, it would be impossible for ungrib to anticipate every possible source of meteorological data in GRIB format. When a new source of data is to be processed by ungrib.exe, the user may create a new Vtable either from scratch, or by using an existing Vtable as an example. In either case, a basic knowledge of the meaning and use of the various fields of the Vtable will be helpful.

Each Vtable contains either seven or eleven fields, depending on whether the Vtable is for a GRIB Edition 1 data source or a GRIB Edition 2 data source, respectively. The fields of a Vtable fall into one of three categories: fields that describe how the data are identified within the GRIB file, fields that describe how the data are identified by the ungrib and metgrid programs, and fields specific to GRIB Edition 2. Each variable to be extracted by ungrib.exe will have one or more lines in the Vtable, with multiple lines for data that are split among different level types – for example, a surface level and upper-air levels. The fields that must be specified for a line, or entry, in the Vtable depends on the specifics of the field and level.

The first group of fields, those that describe how the data are identified within the GRIB file, are given under the column headings of the Vtable shown below.

GRIB1| Level| From | To |
Param| Type |Level1|Level2|
-----+------+------+------+

The "GRIB1 Param" field specifies the GRIB code for the meteorological field, which is a number unique to that field within the data set. However, different data sets may use different GRIB codes for the same field – for example, temperature at upper-air levels has GRIB code 11 in GFS data, but GRIB code 130 in ECMWF data. To find the GRIB code for a field, the g1print.exe and g2print.exe utility program may be used.

Given a GRIB code, the "Level Type", "From Level1", and "From Level2" fields are used to specify which levels a field may be found at. As with the "GRIB1 Param" field, the g1print.exe and g2print.exe programs may be used to find values for the level fields. The meanings of the level fields are dependent on the "Level Type" field, and are summarized in the following table.

Level	Level Type	From Level1	To Level2
Upper-air	100	*	(blank)
Surface	1	0	(blank)
Sea-level	102	0	(blank)
Levels at a specified height AGL	105	Height, in meters, of the level above ground	(blank)
Fields given as layers	112	Starting level for the layer	Ending level for the layer

When layer fields (Level Type 112) are specified, the starting and ending points for the layer have units that are dependent on the field itself; appropriate values may be found with the g1print.exe and g2print.exe utility programs.

The second group of fields in a Vtable, those that describe how the data are identified within the metgrid.exe program and real.exe, fall under the column headings shown below.

| metgrid | metgrid | metgrid |
| Name | Units | Description |
+----------+---------+-----------------------------------------+

The most important of these three fields is the "metgrid Name" field, which determines the variable name that will be assigned to a meteorological field when it is written to the intermediate files by ungrib. This name should also match an entry in the METGRID.TBL file, so that the metgrid program can determine how the field is to be horizontally interpolated. The "metgrid Units" and "metgrid Description" fields specify the units and a short description for the field, respectively; here, it is important to note that if no description is given for a field, then ungrib will not write that field out to the intermediate files.

The final group of fields, which provide GRIB2-specific information, are found under the column headings below.

|GRIB2|GRIB2|GRIB2|GRIB2|
|Discp|Catgy|Param|Level|
+-----------------------+

The GRIB2 fields are only needed in a Vtable that is to be used for GRIB Edition 2 data sets, although having these fields in a Vtable does not prevent that Vtable from also being used for GRIB Edition 1 data. For example, the Vtable.GFS file contains GRIB2 Vtable fields, but is used for both 1-degree (GRIB1) GFS and 0.5-degree (GRIB2) GFS data sets. Since Vtables are provided for most known GRIB Edition 2 data sets, the corresponding Vtable fields are not described here at present.

Writing Static Data to the Geogrid Binary Format

The static geographical data sets that are interpolated by the geogrid program are stored as regular 2-dimensional and 3-dimensional arrays written in a simple binary format. Users with a new source for a given static field can ingest their data with WPS by writing the data set into this binary format. The geogrid format is capable of supporting single-level and multi-level continuous fields, categorical fields represented as dominant categories, and categorical fields given as fractional fields for each category. The most simple of these field types in terms of representation in the binary format is a categorical field given as a dominant category at each source grid point, an example of which is the 30-second USGS land use data set.

For a categorical field given as dominant categories, the data must first be stored in a regular 2-dimensional array of integers, with each integer giving the dominant category at the corresponding source grid point. Given this array, the data are written to a file, row-by-row, beginning at the bottom (smallest index) row. For example, in the figure above, the elements of the n ´ m array would be written in the order x₁₁, x₁₂, ..., x_1m, x₂₁, ..., x_2m, ..., x_n1, ..., x_nm. When written to the file, every element is stored as a 1-, 2-, 3-, or 4-byte integer in big-endian byte order (i.e., for the 4-byte integer ABCD, byte A is stored at the lowest address and byte D at the highest). Every element in a file must use the same number of bytes for its storage, and, of course, it is advantageous to use the fewest number of bytes needed to represent the complete range of values in the array.

Similar in format to a field of dominant categories is the case of a field of continuous, or real, values. Like dominant-category fields, single-level continuous fields are first organized as a regular 2-dimensional array, then written, row-by-row, to a binary file. However, because a continuous field may contain non-integral or negative values, the storage representation of each element within the file is slightly more complex. All elements in the array must first be converted to integral values. This may be done by first scaling all element by a constant, chosen to maintain the required precision, and then removing any remaining fractional part through rounding. For example, if three decimal places of precision are required, the value -2.71828 would need to be scaled by 1000 and rounded to -2718. Following conversion of all array elements to integral values, if any negative values are found in the array, a second conversion must be applied: if elements are stored using 1 byte each, then 2⁸ is added to each negative element; for storage using 2 bytes, 2¹⁶ is added to each negative element; for storage using 3 bytes, 2²⁴ is added to each negative element; and for storage using 4 bytes, a value of 2³² is added to each negative element. It is important to note that positive elements are unaffected by this second conversion. Finally, the resulting positive, integral array is written as in the case of a dominant-category field.

Multi-level continuous fields are handled much the same as single-level continuous fields. For an n ´ m ´ r array, conversion to a positive, integral field is first performed as described above. Then, each n ´ m sub-array is written continguously to the binary file as before, beginning with the smallest r-index. Categorical fields that are given as fractional fields for each possible category can be thought of as multi-level continuous fields, where each level k is the fractional field for category k.

When writing a field to a file in the geogrid binary format, the user should adhere to the naming convention used by the geogrid program, which expects data files to have names of the form xstart-xend.ystart-yend, where xstart, xend, ystart, and yend are five-digit integers specifying, respectively, the starting x-index of the array contained in the file, the ending x-index of the array, the starting y-index of the array, and the ending y-index of the array; here, indexing begins at 1, rather than 0. So, for example, an 800 ´ 1200 array (i.e., 800 rows and 1200 columns) might be named 00001-01200.00001-00800.

When a data set is given in several pieces, each of the pieces may be formed as a regular rectangular array, and each array may be written as a separate file. In this case, the relative locations of the arrays are determined by the range of x- and y-indices in the file names for each of the arrays. It is important to note, however, that every tile must have the same x- and y-dimensions, and that tiles of data within a data set must not overlap; furthermore, all tiles must start and end on multiples of the index ranges. For example, the global 30-second USGS topography data set is divided into arrays of dimension 1200 ´ 1200, with each array containing a 10-degree ´ 10-degree piece of the data set; the file whose south-west corner is located at (90S, 180W) is named 00001-01200.00001-01200, and the file whose north-east corner is located at (90N, 180E) is named 42001-43200.42001-43200.

Clearly, since the starting and ending indices have five digits, a field cannot have more than 99999 data points in either of the x- or y-directions. In case a field has more than 99999 data points in either dimension, the user can simply split the data set into several smaller data sets which will be identified separately to geogrid.

Besides the binary data files themselves, geogrid requires one extra metadata file per data set. This metadata file is always named 'index', and thus, two data sets cannot reside in the same directory. Essentially, this metadata file is the first file that geogrid looks for when processing a data set, and the contents of the file provide geogrid with all of the information necessary for constructing names of possible data files. The contents of an example index file are given below.

type = continuous

signed = yes

projection = regular_ll

dx = 0.00833333

dy = 0.00833333

known_x = 1.0

known_y = 1.0

known_lat = -89.99583

known_lon = -179.99583

wordsize = 2

tile_x = 1200

tile_y = 1200

tile_z = 1

tile_bdr=3

units="meters MSL"

description="Topography height"

For a complete listing of keywords that may appear in an index file, along with the meaning of each keyword, the user is referred to the second part of the section on GEOGRID.TBL keywords.

Description of the Namelist Variables

A. SHARE section

This section provides variables that are used by more than one WPS program. For example, the wrf_core variable specifies whether WPS is to produce data for the ARW or the NMM core – information which is needed by both the geogrid and metgrid programs.

1. WRF_CORE : A character string set to either ‘ARW’ or ‘NMM’ that tells WPS which dynamical core the input data are being prepared for. Default value is ‘ARW’.

2. MAX_DOM : An integer specifying the total number of domains/nests, including the parent domain, in the simulation. Default value is 1.

3. START_YEAR : A list of MAX_DOM 4-digit integers specifying the starting UTC year of the simulation for each nest. No default value.

4. START_MONTH : A list of MAX_DOM 2-digit integers specifying the starting UTC month of the simulation for each nest. No default value.

5. START_DAY : A list of MAX_DOM 2-digit integers specifying the starting UTC day of the simulation for each nest. No default value.

6. START_HOUR : A list of MAX_DOM 2-digit integers specifying the starting UTC hour of the simulation for each nest. No default value.

7. END_YEAR : A list of MAX_DOM 4-digit integers specifying the ending UTC year of the simulation for each nest. No default value.

8. END_MONTH : A list of MAX_DOM 2-digit integers specifying the ending UTC month of the simulation for each nest. No default value.

9. END_DAY : A list of MAX_DOM 2-digit integers specifying the ending UTC day of the simulation for each nest. No default value.

10. END_HOUR : A list of MAX_DOM 2-digit integers specifying the ending UTC hour of the simulation for each nest. No default value.

11. START_DATE : A list of MAX_DOM character strings of the form 'YYYY-MM-DD_HH:mm:ss' specifying the starting UTC date of the simulation for each nest. The start_date variable is an alternate to specifying start_year, start_month, start_day, and start_hour, and if both methods are given for specifying the starting time, the start_date variable will take precedence. No default value.

12. END_DATE : A list of MAX_DOM character strings of the form 'YYYY-MM-DD_HH:mm:ss' specifying the ending UTC date of the simulation for each nest. The end_date variable is an alternate to specifying end_year, end_month, end_day, and end_hour, and if both methods are given for specifying the ending time, the end_date variable will take precedence. No default value.

13. INTERVAL_SECONDS : The integer number of seconds between time-varying meteorological input files. No default value.

14. IO_FORM_GEOGRID : The WRF I/O API format that the domain files created by the geogrid program will be written in. Possible options are: 1 for binary; 2 for NetCDF; 3 for GRIB1. When option 1 is given, domain files will have a suffix of .int; when option 2 is given, domain files will have a suffix of .nc; when option 3 is given, domain files will have a suffix of .gr1. Default value is 2 (NetCDF).

15. OPT_OUTPUT_FROM_GEOGRID_PATH : A character string giving the path, either relative or absolute, to the location where output files from geogrid should be written to and read from. Default value is ‘./’.

16. DEBUG_LEVEL : An integer value indicating the threshold for sending debugging information to standard output. The useful range for the debugging level is 0 to 1000, with higher values permitting more output to be sent to standard output. Default value is 0.

B. GEOGRID section

This section specifies variables that are specific to the geogrid program. Variables in the geogrid section primarily define the size and location of all model domains, and where the static geographical data are found.

1. PARENT_ID : A list of MAX_DOM integers specifying, for each nest, the domain number of the nest’s parent; for the coarsest domain, parent_id should be set to 1. Default value is 1.

2. PARENT_GRID_RATIO : A list of MAX_DOM integers specifying, for each nest, the nesting ratio relative to the domain’s parent. No default value.

3. I_PARENT_START : A list of MAX_DOM integers specifying, for each nest, the x-coordinate of the lower-left corner of the nest in the parent unstaggered grid. For the coarsest domain, a value of 1 should be specified. No default value.

4. J_PARENT_START : A list of MAX_DOM integers specifying, for each nest, the y-coordinate of the lower-left corner of the nest in the parent unstaggered grid. For the coarsest domain, a value of 1 should be specified. No default value.

5. S_WE : A list of MAX_DOM integers which should all be set to 1. Default value is 1.

6. E_WE : A list of MAX_DOM integers specifying, for each nest, the nest’s full west-east dimension. For nested domains, e_we must be one greater than an integer multiple of the nest's parent_grid_ratio (i.e., e_ew = n*parent_grid_ratio+1 for some integer n). No default value.

7. S_SN : A list of MAX_DOM integers which should all be set to 1. Default value is 1.

8. E_SN : A list of MAX_DOM integers specifying, for each nest, the nest’s full south-north dimension. For nested domains, e_sn must be one greater than an integer multiple of the nest's parent_grid_ratio (i.e., e_sn = n*parent_grid_ratio+1 for some integer n). No default value.

9. GEOG_DATA_RES : A list of MAX_DOM character strings specifying, for each nest, a corresponding resolution of source data to be used when interpolating static terrestrial data to the nest’s grid. For each nest, this string should match a string preceding a colon in a rel_path or abs_path specification (see the description of GEOGRID.TBL options) in the GEOGRID.TBL file for each field; if the string does not match any such string in a rel_path or abs_path specification for a field in GEOGRID.TBL, a default resolution of data for that field, if one is specified, will be used. Default value is ‘default’.

10. DX : A real value specifying the grid distance in the x-direction where the map scale factor is 1. For ARW, the grid distance is in meters; for NMM, the grid distance is in degrees longitude. Grid distances for nests are determined recursively based on values specified for parent_grid_ratio. Default value is 10000.

11. DY : A real value specifying the nominal grid distance in the y-direction where the map scale factor is 1. For ARW, the grid distance is in meters; for NMM, the grid distance is in degrees longitude. Grid distances for nests are determined recursively based on values specified for parent_grid_ratio. Default value is 10000.

12. MAP_PROJ : A character string specifying the projection of the simulation domain. For ARW, accepted projections are ‘Lambert’, ‘polar’, and ‘Mercator’; for NMM, a projection of ‘rotated_ll’ must be specified. Default value is ‘Lambert’.

13. REF_LAT : A real value specifying the latitude part of a (latitude, longitude) location whose (i,j) location in the simulation domain is known. For ARW, ref_lat gives the latitude of the center-point of the coarse domain by default (i.e., when ref_x and ref_y are not specified). For NMM, ref_lat always gives the latitude to which the origin is rotated. No default value.

14.REF_LON : A real value specifying the longitude part of a (latitude, longitude) location whose (i,j) location in the simulation domain is known. For ARW, ref_lon gives the longitude of the center-point of the coarse domain by default (i.e., when ref_x and ref_y are not specified). For NMM, ref_lon always gives the longitude to which the origin is rotated. When wrf_core = 'ARW', west longitudes are negative, and when wrf_core = 'NMM', west longitudes are positive; the value of ref_lon should be in the range [-180, 180]. No default value.

15. REF_X : A real value specifying the i part of an (i, j) location whose (latitude, longitude) location in the simulation domain is known. The (i, j) location is always given with respect to the mass-staggered grid, whose dimensions are one less than the dimensions of the unstaggered grid. Default value is (((E_WE-1.)+1.)/2.) = (E_WE/2.).

16.REF_Y : A real value specifying the j part of an (i, j) location whose (latitude, longitude) location in the simulation domain is known. The (i, j) location is always given with respect to the mass-staggered grid, whose dimensions are one less than the dimensions of the unstaggered grid. Default value is (((E_SN-1.)+1.)/2.) = (E_SN/2.).

17. TRUELAT1 : A real value specifying, for ARW, the first true latitude for the Lambert conformal conic projection, or the true latitude for the polar stereographic projection. For NMM, truelat1 is ignored. No default value.

18. TRUELAT2 : A real value specifying, for ARW, the second true latitude for the Lambert conformal conic projection. For NMM, truelat2 is ignored. No default value.

19. STAND_LON : A real value specifying, for ARW, the longitude that is parallel with the y-axis in conic and azimuthal projections. For NMM, stand_lon is ignored. No default value.

20. GEOG_DATA_PATH : A character string giving the path, either relative or absolute, to the directory where the geographical data directories may be found. This path is the one to which rel_path specifications in the GEOGRID.TBL file are given in relation to. No default value.

121. OPT_GEOGRID_TBL_PATH : A character string giving the path, either relative or absolute, to the GEOGRID.TBL file. The path should not contain the actual file name, as GEOGRID.TBL is assumed, but should only give the path where this file is located. Default value is ‘./geogrid/’.

C. UNGRIB section

Currently, this section contains only two variables, which determine the output format written by ungrib and the name of the output files.

1. OUT_FORMAT : A character string set either to ‘WPS’, ‘SI’, or ‘MM5’. If set to ‘MM5’, ungrib will write output in the format of the MM5 pregrid program; if set to ‘SI’, ungrib will write output in the format of grib_prep.exe; if set to ‘WPS’, ungrib will write data in the WPS intermediate format. Default value is ‘WPS’.

2. PREFIX : A character string that will be used as the prefix for intermediate-format files created by ungrib; here, prefix refers to the string PREFIX in the filename PREFIX:YYYY-MM-DD_HH. The prefix may contain path information, either relative or absolute, in which case the intermediate files will be written in the directory specified. This option may be useful to avoid renaming intermediate files if ungrib is to be run on multiple sources of GRIB data. Default value is 'FILE'.

D. METGRID section

This section defines variables used only by the metgrid program. Typically, the user will be interested in the fg_name variable, and may need to modify other variables of this section less frequently.

1. FG_NAME : A list of character strings specifying the path and prefix of ungribbed data files. The path may be relative or absolute, and the prefix should contain all characters of the filenames up to, but not including, the colon preceding the date. When more than one fg_name is specified, and the same field is found in two or more input sources, the data in the last encountered source will take priority over all preceding sources for that field. Default value is an empty list (i.e., no meteorological fields).

2. CONSTANTS_NAME : A list of character strings specifying the path and full filename of ungribbed data files which are time-invariant. The path may be relative or absolute, and the filename should be the complete filename; since the data are assumed to be time-invariant, no date will be appended to the specified filename. Default value is an empty list (i.e., no constant fields).

3. IO_FORM_METGRID : The WRF I/O API format that the output created by the metgrid program will be written in. Possible options are: 1 for binary; 2 for NetCDF; 3 for GRIB1. When option 1 is given, output files will have a suffix of .int; when option 2 is given, output files will have a suffix of .nc; when option 3 is given, output files will have a suffix of .gr1. Default value is 2 (NetCDF).

4. OPT_OUTPUT_FROM_METGRID_PATH : A character string giving the path, either relative or absolute, to the location where output files from metgrid should be written to. The default value is the current working directory. Default value is ‘./’.

5. OPT_METGRID_TBL_PATH : A character string giving the path, either relative or absolute, to the METGRID.TBL file; the path should not contain the actual file name, as METGRID.TBL is assumed, but should only give the path where this file is located. Default value is ‘./metgrid/’.

6. OPT_IGNORE_DOM_CENTER : A logical value, either .TRUE. or .FALSE., specifying whether, for times other than the initial time, interpolation of meteorological fields to points on the interior of the simulation domain should be avoided in order to decrease the runtime of metgrid. Default value is .FALSE..

Description of GEOGRID.TBL Options

The GEOGRID.TBL file is a text file that defines parameters of each of the data sets to be interpolated by geogrid. Each data set is defined in a separate section, with sections being delimited by a line of equality signs (e.g., ‘==============’). Within each section, there are specifications, each of which has the form of keyword=value. Some keywords are required in each data set section, while others are optional; some keywords are mutually exclusive with other keywords. Below, the possible keywords and their expected range of values are described.

1. NAME : A character string specifying the name that will be assigned to the interpolated field upon output. No default value.

2. PRIORITY : An integer specifying the priority that the data source identified in the table section takes with respect to other sources of data for the same field. If a field has n sources of data, then there must be n separate table entries for the field, each of which must be given a unique value for priority in the range [1,n]. No default value.

3. DEST_TYPE : A character string, either categorical or continuous, that tells whether the interpolated field from the data source given in the table section is to be treated as a continuous or a categorical field. No default value.

4. INTERP_OPTION : A sequence of one or more character strings, which are the names of interpolation methods to be used when horizontally interpolating the field. Available interpolation methods are: average_4pt, average_16pt, wt_average_4pt, wt_average_16pt, nearest_neighbor, four_pt, sixteen_pt, search, average_gcell(r); for the grid cell average method (average_gcell), the optional argument r specifies the minimum ratio of source data resolution to simulation grid resolution at which the method will be applied. When a sequence of two or more methods are given, the methods should be separated by a + sign. No default value.

5. SMOOTH_OPTION : A character string giving the name of a smoothing method to be applied to the field after interpolation. Available smoothing options are: 1-2-1, smth-desmth, and smth-desmth_special. Default value is null (i.e., no smoothing is applied).

6. SMOOTH_PASSES : If smoothing is to be performed on the interpolated field, smooth_passes specifies an integer number of passes of the smoothing method to apply to the field. Default value is 1.

7. REL_PATH : A character string specifying the path relative to the path given in the namelist variable geog_data_path. A specification is of the general form RES_STRING:REL_PATH, where RES_STRING is a character string identifying the source or resolution of the data in some unique way and may be specified in the namelist variable geog_data_res, and REL_PATH is a path relative to geog_data_path where the index and data tiles for the data source are found. More than one rel_path specification may be given in a table section if there are multiple sources or resolutions for the data source. See also abs_path. No default value.

8. ABS_PATH : A character string specifying the absolute path to the index and data tiles for the data source. A specification is of the general form RES_STRING:ABS_PATH, where RES_STRING is a character string identifying the source or resolution of the data in some unique way and may be specified in the namelist variable geog_data_res, and ABS_PATH is the absolute path to the data source's files. More than one abs_path specification may be given in a table section if there are multiple sources or resolutions for the data source. See also rel_path. No default value.

9. OUTPUT_STAGGER : A character string specifying the grid staggering to which the field is to be interpolated. For ARW domains, possible values are U, V, and M; for NMM domains, possible values are HH and VV. Default value for ARW is M; default value for NMM is HH.

10. LANDMASK_WATER : An integer value that is the index of the category within the field that represents water. When landmask_water is specified in the table section of a field for which dest_type=categorical, the LANDMASK field will be computed from the field using the specified category as the water category. The keywords landmask_water and landmask_land are mutually exclusive. Default value is null (i.e., a landmask will not be computed from the field).

11. LANDMASK_LAND : An integer value that is the index of the category within the field that represents land. When landmask_water is specified in the table section of a field for which dest_type=categorical, the LANDMASK field will be computed from the field using the specified category as the land category. The keywords landmask_water and landmask_land are mutually exclusive. Default value is null (i.e., a landmask will not be computed from the field).

12. MASKED : Either land or water, indicating that the field is not valid at land or water points, respectively. If the masked keyword is used for a field, those grid points that are of the masked type (land or water) will be assigned the value specified by fill_missing. Default value is null (i.e., the field is not masked).

13. FILL_MISSING : A real value used to fill in any missing or masked grid points in the interpolated field. Default value is 1.E20.

14. HALT_ON_MISSING : Either yes or no, indicating whether geogrid should halt with a fatal message when a missing value is encountered in the interpolated field. Default value is no.

15. DOMINANT_CATEGORY : When specified as a character string, the effect is to cause geogrid to compute the dominant category from the fractional categorical field, and to output the dominant category field with the name specified by the value of dominant_category. This option can only be used for fields with dest_type=categorical. Default value is null (i.e., no dominant category will be computed from the fractional categorical field).

16. DOMINANT_ONLY : When specified as a character string, the effect is similar to that of the dominant_category keyword: geogrid will compute the dominant category from the fractional categorical field and output the dominant category field with the name specified by the value of dominant_only. Unlike with dominant_category, though, when dominant_only is used, the fractional categorical field will not appear in the geogrid output. This option can only be used for fields with dest_type=categorical. Default value is null (i.e., no dominant category will be computed from the fractional categorical field).

17. DF_DX : When df_dx is assigned a character string value, the effect is to cause geogrid to compute the directional derivative of the field in the x-direction using a central difference along the interior of the domain, or a one-sided difference at the boundary of the domain; the derivative field will be named according to the character string assigned to the keyword df_dx. Default value is null (i.e., no derivative field is computed).

18. DF_DY : When df_dy is assigned a character string value, the effect is to cause geogrid to compute the directional derivative of the field in the y-direction using a central difference along the interior of the domain, or a one-sided difference at the boundary of the domain; the derivative field will be named according to the character string assigned to the keyword df_dy. Default value is null (i.e., no derivative field is computed).

19. Z_DIM_NAME : For 3-dimensional output fields, a character string giving the name of the vertical dimension or z-dimension. A continuous field may have multiple levels, and thus be a 3-dimensional field, and a categorical field may take the form of a 3-dimensional field if it is written out as fractional fields for each category. No default value.

Related to the GEOGRID.TBL are the index files that are associated with each static data set. An index file defines parameters specific to that data set, while the GEOGRID.TBL file describes how each of the data sets should be treated by geogrid. As with the GEOGRID.TBL file, specifications in an index file are of the form keyword=value. Below are possible keywords and their possible values.

1. PROJECTION : A character string specifying the projection of the data, which may be either 'lambert', 'polar', 'mercator', 'regular_ll', or 'polar_wgs84'. No default value.

2. TYPE : A character string, either categorical or continuous, that determines whether the data in the data files should be interpreted as a continuous field or as discrete indices. For categorical data represented by a fractional field for each possible category, type should be set to continuous. No default value.

3. SIGNED : Either yes or no, indicating whether the values in the data files (which are always represented as integers) are signed in two's complement form or not. Default value is no.

4. UNITS : A character string, enclosed in quotation marks ("), specifying the units of the interpolated field; the string will be written to the geogrid output files as a variable time-independent attribute. No default value.

5. DESCRIPTION : A character string, enclosed in quotation marks ("), giving a short description of the interpolated field; the string will be written to the geogrid output files as a variable time-independent attribute. No default value.

6. DX : A real value giving the grid spacing in the x-direction of the data set. If projection is one of 'lambert', 'polar', 'mercator', or 'polar_wgs84', dx gives the grid spacing in meters; if projection is 'regular_ll', dx gives the grid spacing in degrees. No default value.

7. DY : A real value giving the grid spacing in the y-direction of the data set. If projection is one of 'lambert', 'polar', 'mercator', or 'polar_wgs84', dy gives the grid spacing in meters; if projection is 'regular_ll', dy gives the grid spacing in degrees. No default value.

8. KNOWN_X : A real value specifying the i-coordinate of an (i,j) location corresponding to a (latitude, longitude) location that is known in the projection. Default value is 1.

9. KNOWN_Y : A real value specifying the j-coordinate of an (i,j) location corresponding to a (latitude, longitude) location that is known in the projection. Default value is 1.

10. KNOWN_LAT : A real value specifying the latitude of a (latitude, longitude) location that is known in the projection. No default value.

11. KNOWN_LON : A real value specifying the longitude of a (latitude, longitude) location that is known in the projection. No default value.

12. STDLON : A real value specifying the longitude that is parallel with the y-axis in conic and azimuthal projections. No default value.

13. TRUELAT1 : A real value specifying, the first true latitude for the Lambert conformal conic projection, or the true latitude for the polar stereographic projection. No default value.

14. TRUELAT2 : A real value specifying, the second true latitude for the Lambert conformal conic projection.. No default value.

15. WORDSIZE : An integer giving the number of bytes used to represent the value of each grid point in the data files. No default value.

16. TILE_X : An integer specifying the number of grid points in the x-direction, excluding any halo points, for a single tile of source data. No default value.

17. TILE_Y : An integer specifying the number of grid points in the y-direction, excluding any halo points, for a single tile of source data. No default value.

18. TILE_Z : An integer specifying the number of grid points in the z-direction for a single tile of source data; this keyword serves as an alternative to the pair of keywords tile_z_start and tile_z_end, and when this keyword is used, the starting z-index is assumed to be 1. No default value.

19. TILE_Z_START : An integer specifying the starting index in the z-direction of the array in the data files. If this keyword is used, tile_z_end must also be specified. No default value.

20. TILE_Z_END : An integer specifying the ending index in the z-direction of the array in the data files. If this keyword is used, tile_z_start must also be specified. No default value

21. CATEGORY_MIN : For categorical data (type=categorical), an integer specifying the minimum category index that is found in the data set. If this keyword is used, category_max must also be specified. No default value.

22. CATEGORY_MAX : For categorical data (type=categorical), an integer specifying the maximum category index that is found in the data set. If this keyword is used, category_min must also be specified. No default value.

23. TILE_BDR : An integer specifying the halo width, in grid points, for each tile of data. Default value is 0.

24. MISSING_VALUE : A real value that, when encountered in the data set, should be interpreted as missing data. No default value.

25. SCALE_FACTOR : A real value that data should be scaled by (through multiplication) after being read in as integers from tiles of the data set. Default value is 1.

26. ROW_ORDER : A character string, either 'bottom_top' or 'top_bottom', specifying whether the rows of the data set arrays were written proceeding from the lowest-index row to the highest ('bottom_top') or from highest to lowest ('top_bottom'). This keyword may be useful when utilizing some USGS data sets, which are provided in 'top_bottom' order. Default value is 'bottom_top'.

Description of METGRID.TBL Options

The METGRID.TBL file is a text file that defines parameters of each of the meteorological fields to be interpolated by metgrid. Parameters for each field are defined in a separate section, with sections being delimited by a line of equality signs (e.g., ‘==============’). Within each section, there are specifications, each of which has the form of keyword=value. Some keywords are required in a section, while others are optional; some keywords are mutually exclusive with other keywords. Below, the possible keywords and their expected range of values are described.

1. NAME : A character string giving the name of the meteorological field to which the containing section of the table pertains. The name should exactly match that of the field as given in the intermediate files (and, thus, the name given in the Vtable used in generating the intermediate files). This field is required. No default value.

2. OUTPUT : Either yes or no, indicating whether the field is to be written to the metgrid output files or not. Default value is yes.

3. MANDATORY : Either yes or no, indicating whether the field is required for successful completion of metgrid. Default value is no.

4. OUTPUT_NAME : A character string giving the name that the interpolated field should be output as. When a value is specified for output_name, the interpolation options from the table section pertaining to the field with the specified name are used. Thus, the effects of specifying output_name are two-fold: The interpolated field is assigned the specified name before being written out, and the interpolation methods are taken from the section pertaining to the field whose name matches the value assigned to the output_name keyword. No default value.

5. FROM_INPUT : A character string used to compare against the values in the fg_name namelist variable; if from_input is specified, the containing table section will only be used when the time-varying input source has a filename that contains the value of from_input as a substring. Thus, from_input may be used to specify different interpolation options for the same field, depending on which source of the field is being processed. No default value.

6. OUTPUT_STAGGER : The model grid staggering to which the field should be interpolated. For ARW, this must be one of U, V, and M; for NMM, this must be one of HH and VV. Default value for ARW is M; default value for NMM is HH.

7. IS_U_FIELD : Either yes or no, indicating whether the field is to be used as the wind U-component field. For ARW, the wind U-component field must be interpolated to the U staggering (output_stagger=U); for NMM, the wind U-component field must be interpolated to the V staggering (output_stagger=VV). Default value is no.

8. IS_V_FIELD : Either yes or no, indicating whether the field is to be used as the wind V-component field. For ARW, the wind V-component field must be interpolated to the V staggering (output_stagger=V); for NMM, the wind V-component field must be interpolated to the V staggering (output_stagger=VV).Default value is no.

9. INTERP_OPTION : A sequence of one or more names of interpolation methods to be used when horizontally interpolating the field. Available interpolation methods are: average_4pt, average_16pt, wt_average_4pt, wt_average_16pt, nearest_neighbor, four_pt, sixteen_pt, search, average_gcell(r); for the grid cell average method (average_gcell), the optional argument r specifies the minimum ratio of source data resolution to simulation grid resolution at which the method will be applied. When a sequence of two or more methods are given, the methods should be separated by a + sign. Default value is nearest_neighbor.

10. INTERP_MASK : The name of the field to be used as an interpolation mask, along with the value within that field which signals masked points. A specification takes the form field(maskval), where field is the name of the field and maskval is a real value. Default value is no mask.

11. INTERP_LAND_MASK : The name of the field to be used as an interpolation mask when interpolating to water points (determined by the static LANDMASK field), along with the value within that field which signals land points. A specification takes the form field(maskval), where field is the name of the field and maskval is a real value. Default value is no mask.

12. INTERP_WATER_MASK : The name of the field to be used as an interpolation mask when interpolating to land points (determined by the static LANDMASK field), along with the value within that field which signals water points. A specification takes the form field(maskval), where field is the name of the field and maskval is a real value. Default value is no mask.

13. FILL_MISSING : A real number specifying the value to be assigned to model grid points that received no interpolated value, for example, because of missing or incomplete meteorological data. Default value is 1.E20.

14. Z_DIM_NAME : For 3-dimensional meteorological fields, a character string giving the name of the vertical dimension to be used for the field on output. Default value is num_metgrid_levels.

15. DERIVED : Either yes or no, indicating whether the field is to be derived from other interpolated fields, rather than interpolated from an input field. Default value is no.

16. FILL_LEV : The fill_lev keyword (which may be specified multiple times within a table section) specifies how a level of the field should be filled if that level does not already exist. A generic value for the keyword takes the form DLEVEL:FIELD(SLEVEL), where DLEVEL specifies the level in the field to be filled, FIELD specifies the source field from which to copy levels, and SLEVEL specifies the level within the source field to use. DLEVEL may either be an integer or 'all'. FIELD may either be the name of another field, 'const', or 'vertical_index'; if FIELD is specified as 'const', then SLEVEL is a constant value that will be used to fill with; if FIELD is specified as 'vertical_index', then (SLEVEL) must not be specified, and the value of the vertical index of the source field is used; if DLEVEL is 'all', then all levels from the field specified by the level_template keyword are used to fill the corresponding levels in the field, one at a time. No default value.

17. LEVEL_TEMPLATE : A character string giving the name of a field from which a list of vertical levels should be obtained (and used as a template). This keyword is used in conjunction with a fill_lev specification that uses 'all' in the DLEVEL part of its specification. No default value.

18. MASKED : Either land or water, indicating whether the field is invalid over land or water, respectively. When a field is masked, or invalid, the static LANDMASK field will be used to determine which model grid points the field should be interpolated to; invalid points will be assigned the value given by the FILL_MSG keyword. Default value is null (i.e., the field is valid for both land and water points).

19. MISSING_VALUE : A real number giving the value in the input field that is assumed to represent missing data. No default value.

20. VERTICAL_INTERP_OPTION : A character string specifying the vertical interpolation method that should be used when vertically interpolating to missing points. Currently, this option is not implemented. No default value.

21. FLAG_IN_OUTPUT : A character string giving the name of a global attribute which will be assigned a value of 1 and written to the metgrid output if the interpolated field is to be output (output=yes). Default value is null (i.e., no flag will be written for the field).