| WRF EMS User's Guide Chapter 6: Using wrf_prep.pl |
Table of Contents
6.1 Introduction
6.2 A summary of wrf_prep.pl features
6.3 wrf_prep.pl configuration files
6.4 Initialization data sets
6.5 Adding new initialization data sets
6.6 Running wrf_prep.pl from the command line
6.7 A few wrf_prep.pl examples
The primary purpose of the wrf_prep.pl script is to identify, acquire, and process the external data sets for use as initial and boundary condition information in the WRF EMS. The wrf_prep.pl script is the most complex of the run-time scripts as it must sort though a myriad of user options to determine which data to download, where to obtain the files, how to process the files, and then complete the horizontal and vertical interpolation to the user's computational domain. The final output files from wrf_prep.pl are in netCDF format and serve as the input to the WRF real.exe program, which is run by the wrf_run.pl script. More information about wrf_run.pl is provided in Chapter 7.
6.2 A summary of wrf_prep.pl features
To summarize, the wrf_prep.pl routine:
• Handles the acquisition and processing of data sets for use as model initial and boundary conditions;
• Supports multiple file formats including GRIB 1, GRIB 2, and NWS LAPS;
• Supports the use of different data sets for initial and boundary conditions;
• Allows for the inclusion of multiple static surface data sets, such as high resolution sea surface temperature (SST);
• Allows for the inclusion of additional dynamic land surface model (LSM) data sets;
• Supports NCEP 12 and 32-km NAM tiled data sets in GRIB 1 format;
• Supports the automated request and acquisition of NAM and GFS "personal tiles" from the NCEP and NCDC real-time and archive data servers;
• Supports data automated transfers via copy (NFS), FTP, and HTTP;
• Searches multiple FTP and HTTP servers for requested data sets;
• Supports input files with up to 1-minute temporal frequency;
• Determines which data sets from various model runs are available for ingestion at a given time, and;
• Initialization may be accomplished with configuration files or through command-line options.
6.3 wrf_prep.pl configuration files
The wrf_prep.pl script along with the ancillary Fortran and C programs rely on various configuration files and tables to complete the task of preparing your data for a model run. Some of these files provide the default wrf_prep.pl options that may be overridden by command line arguments to wrf_prep and may be edited to meet the needs of the user. Other files contain critical information and data needed by the program, which should not be edited unless you really know what you are doing.
6.3.1 The wrf_prep.conf and prep_wrfsi.conf files
Master configuration files for wrf_prep.pl are located in the wrf/data/conf/config/wrf_prep directory. Each time a computational domain is created using the WRF SI GUI, local copies of these files are placed in the <domain>/conf/wrf_prep directory.
The wrf_prep.conf file contains some user-configurable options but for the most part, you will not need to edit this file since it is already configured for typical use.
The prep_wrfsi.conf file contains information about the user's model domain used by the Fortran programs to accomplish the horizontal and vertical interpolation of the initial and boundary condition data sets to the model domain. The wrf_prepsi.conf file should not be directly edited by the user.
6.3.2 The _gribinfo.conf files
The wrf/data/conf/gribinfo directory contains information files on all the data sets available to initialize your WRF EMS model runs. Whenever you run wrf_prep.pl, the data set(s) that you provide must have a companion <data set>_gribinfo.conf file in this directory. Each configuration file contains a description of the data set and default settings that may be overridden by the user from the command line. Information on modifying these files and adding new data sets is provided in appendix A.
6.3.3 The Vtable files
The wrf/data/conf/tables directory contains a Vtable file for various GRIB 1 and 2 data sets used to initialize a model run. Each Vtable.<NAME> file describes the fields and levels that are contained in a GRIB file; referencing to a specific Vtable at the bottom of the <data set>_gribinfo.conf files. Note that multiple data sets may use the same Vtable, generally a user does not need to edit the Vtable files.
As stated in section 6.3.2 , there are numerous data sets that may be used to initialize a model run. A list and brief description of the available data set may be obtained by passing the "--dslist" flag to wrf_prep:
% wrf_prep --dslist
(Lots of data set information printed out)
Even though there are many data sets from which to choose, chances are that you will quickly settle on 1 or 2 data sets to initialize your simulation. If you want more information about a specific data set and the contents of the <data set>_gribinfo.conf file you can use the "--query <data set> option. For example:
% wrf_prep --query gfsptile
Default settings from the gfsptile grib information file: gfsptile_gribinfo.conf
GFS Model 0.5 degree personal tile - Isobaric coordinate - 3hourly
Model Group Name : GFS
Default initial forecast hour : 00
Default final forecast hour : 24
Default BC frequency : 03
Available Cycles : 00 06 12 18
Post Processing Delay : 05 Hour(s)
Local grib filename : YYMMDDCC.gfs.tCCz.pgrbfFF
NFS grib file location : /incoming/data/YYYYMMDD/grib/gfs/grib.tCCz/gfs.tCCz.pgrbfFF
Vtable grid information file : Vtable.GFS
Available HTTP Server(s) Directory/Filename
NOMAD5 - /cgi-bin/ftp2u_gfs_master.sh?gfs.tCCz.master.grbfFF
NOMAD6 - /cgi-bin/ftp2u_gfs0.5.sh?gfs.tCCz.master.grbfFF
NOMAD3 - /cgi-bin/ftp2u_gfs0.5.sh?gfs.tCCz.master.grbfFFNaming convention keys:
YYYYMMDD - 2-digit Year, Month, Day (Ex: 050230)
YYMMDD - 4-digit Year, Month, Day (Ex: 20050230)
YYYY - 4-digit Year
YY - 2-digit Year
MM - 2-digit Month
DD - 2-digit Day
CC - Cycle Hour
FF - Forecast Hour
TT - Tile NumberFiles can be found in the /usr1/wrf/data/conf/gribinfo directory.
6.5 Adding new initialization data sets
There are times when you want to modify the information contained in one of the <data set>_gribinfo.conf files or create a new file for a data set you wish to add. To add a new data set, simply copy an existing file and edit the information as needed. For assistance you can refer to documentation in each of the files, although a comprehensive summary of the parameters is provided in Appendix A.
The master wrf_prep.pl file resides in the wrf/strc ($WRF_STRC) directory. Users do not run the wrf_prep.pl script directly from this directory, but rather, will execute "wrf_prep" from one of the domain directories in wrf/runs. The wrf_prep file located in a domain directory is a link to the master wrf_prep.pl file in the strc directory, therefore, any changes made to the local file is made to the master file as well.
The "wrf_prep" script does the following when executed from a domain directory:
1. Determines the list of initialization and boundary condition files being requested by the user,
2. Attempts to acquire the requested data files,
3. Subsets the data into the user's computational domain,
4. Horizontally interpolates the grids to the computational domain grid spacing,
5. Vertically interpolates the grids to computational domain levels, and
6. Outputs the files in netCDF format for use by the model.
As with all of the WRF EMS run-time scripts, wrf_prep has a built in help menu and user's guide. The help menu provides a brief summary of all the options available to wrf_prep. To view the brief help menu:
% wrf_prep --help
And for a much more verbose user's guide:
% wrf_prep --guide
6.7 A few wrf_prep.pl examples
There are many command line options that you can pass to wrf_prep, but only one mandatory argument, which is the data set(s) you wish to use for initial and boundary conditions. So, if you are a minimalist type of person, you might run:
% wrf_prep --dset nam212
following which wrf_prep will attempt to use the NAM 212 grid for model initialization and boundary conditions. In the absence of any other options, wrf_prep will default to the settings in the nam212_gribinfo.conf file. Because no method of acquisition is specified (nfs, ftp, or http), wrf_prep assumes that the initialization files already reside in the <domain>/grib directory and have the default naming convention specified by the LOCLFIL parameter. If you have placed your grib files in the <domain>/grib directory but wrf_prep fails to find them, the most likely problem is that you are not using the proper filenames. Look at the wrf_prep error messages for more information.
Fortunately, there are many command line options available to wrf_prep that may be used to override the default settings. If the minimalist approach is not for you, then feel free to read the information provided by the "guide" option and experiment (with the options).
The best way of demonstrating some of the wrf_prep functionality is through examples, lots and lots of examples. A few examples are presented below; however, an alphabet's worth of possibilities is waiting for you in Appendix B . For those who can't wait, here are a few tempting morsels of wrf_prep wizardry:
% wrf_prep --dset nam212 --ftp
In the above example, the user is requesting the most recent NAM 40km 212 grid forecast GRIB files for initial and boundary conditions. The wrf_prep script uses the initial forecast hour, final forecast hour, and boundary condition frequency defined in the nam212_gribinfo.conf file by the INITFH, FINLFH, and FREQFH respectively. It will search for the data set on the available FTP servers listed in the nam212_gribinfo.conf configuration file. The script will check each FTP server for the requested files until all of them have been downloaded to the local machine and renamed to the file naming convention defined by LOCLFIL. Note that if the FTP server is not anonymous then you MUST have the user name and password information in your ~/.netrc file. Also note that all files are placed in the <domain>/grib directory.
Again, this time with feeling:
% wrf_prep --dset nam212 --ftp --cycle 12:06:30:06
Similar to the above example, except it specifies the cycle time (12 UTC), initialization forecast hour (06), final forecast hour (30), and boundary condition frequency (06). The forecast length is 24 hours (30 - 06). If the current cycle run of the initialization is 00Z, that run will be ignored in favor of the early 12Z run. Note in the absence of the specified cycle time, wrf_prep will figure out the most recent run from which data are available. Yes, it's magic.
Ok, more magic:
% wrf_prep --dset nam212 --cycle 12 -date 20050230
Similar to the example above except using the NAM 212 grid files from the 12 UTC cycle run on 30 February 2005. You must already have the files located in your <domain>/grib directory with the appropriate naming convention since no method of acquisition is specified (http, ftp, or nfs). You might use this example for running case studies.
This time, something really interesting:
% wrf_prep --dset namptile --http --cycle CYCLE:06
Use the 12km NAM personal tiles available from NOMADS http server beginning with the 06 hour forecast from the most recent run of the NAM . The "CYCLE" is a placeholder for the current cycle run and must be used if you are overriding the default initial forecast hour (INITFH) value in namptile_gribinfo.conf. When using the namptile data set, wrf_prep will request a subset of the full resolution (12km) operational NAM domain from the NOMADS http server. This subset will be tailored to your computational domain and a bespoke data set is a good data set.
Let's get small:
% wrf_prep --dset namptile%gfsptile --http nomad3 --http nomad5 --cycle CYCLE:84 --length 48 --sfcdset ssthr --sftp
Use the 12km NAM personal tiles (namptile) available from NOMAD3 http server (--http nomad3) beginning with an 84-hour forecast from the most recent run (--cycle CYCLE:84) of the NAM for the initial conditions. Use the GFS 0.5 degree personal tiles (gfsptile), also from the NOMADS server (NOMAD5; --http nomad2). Note that the first --http in the command line refers to the initialization data set while the second refers to the boundary condition dataset. Total run length will be 48 hours (--length 48). Also get via FTP (--sftp) the 8.3km high resolution SST data set (--sfcdset ssthr). Note that wrf_prep will download the appropriate GFS files from the most recent GFS run. If the GFS run is 6 hours older than the NAM the forecast times will be adjusted accordingly. That's not magic, that's VooDoo.
Back to some easy stuff:
% wrf_prep --dset nam212 --nfs /incoming/NAM.tCCz.awip3dFF
The above example is similar to the initial example except it accesses the data set via the copy (cp) command on a local drive (--nfs), overriding the default location of the file on the local system (/incoming/NAM.tCCz.awip3dFF). Note that you must include the path and appropriate file naming convention. See the <data set>_gribinfo.conf file for an explanation of the filename place holders, i.e, [YY]YY, MM, DD, HH, CC, FF, TT.
Hey I do the North American Regional Reanalysis (NARR) data set:
% wrf_prep --dset narr --date 841214 -cycle 12 --nfs -length 12
The above example will use 12 hours of the NARR dataset from 12 UTC 14 December through 00 UTC 15 December 1984. Files will be obtained via nfs.
A few comments on using the NARR data set:
• NARR data files in grib format are available from NCDC. Additional information can be found at:
• The standard NARR grib files are missing the landmask field necessary for running the WRF. The WRF EMS package includes static surface fields, including a landmask, for use with the NARR data set. The fields are contained in a grib file (narr_sfc.grb) located in the wrf/data/conf/tables directory and are automatically included in your run.
Again, for more examples, please see Appendix B. Become one with Appendix B.