WRFSI GUI User’s Guide 2.0.1
USERS GUIDE
TO THE GRAPHICAL USER INTERFACE TO PREPARE THE
STANDARD INITIALIZATION FOR
WRF VERSION 2.0.1
January 2005
Paula T. McCaslin*, John R.
Smart**, and Brent Shaw***
NOAA Research - Forecast Systems
Laboratory
Boulder, Colorado
1. INTRODUCTION
The Weather
Research and Forecasting (WRF) model is slated to be the next operational
meso-scale weather forecast model for the United States. The Forecast Systems
Laboratory (FSL) has developed the WRF Standard Initialization (SI), an
important and necessary first step in setting up WRF. The SI provides three
mandatory functions: 1) to define and localize a three-dimensional grid, 2) to
specify the ‘static’ surface characteristics of land, water, and vegetation,
and 3) to provide the initial and lateral boundary condition files by
interpolating larger scale model data to the domain. Through the use of a
graphical interface (GUI), these complicated processes have been greatly
simplified.
The GUI
allows the user to run all SI processes to generate domains, process initial
and lateral boundary condition data, and create display graphics.
Traditionally, experts in numerical weather models with degrees in meteorology
set up model configurations. With the use of this tool anyone can set up model
configurations. This involves defining a grid spatially and temporally,
choosing data sources, etc. to meet their modeling needs.
The
objective of this users guide is to describe the WRF GUI and provide an
understanding of its functionality. Details of the GUI software and directory
structure are presented in section 2. Section 3 describes the design and layout
and gives an example for setting up and localizing a domain over Australia,
including a discussion about creating initial and lateral boundary condition
data. Future work is discussed in section 4. A brief summary is found in
section 5.
The design
of this GUI was influenced by various applications that FSL evaluated during
this development, including the Air Force Weather Agency (AFWA) System GUI and
the National Center for Atmospheric Research (NCAR/ARMY) MM5 GUI.
2. SOFTWARE
To build the
WRF GUI, download the WRF SI tar file via the WRF web site: http://wrf-model.org/si, compile, and
install. Installation is accomplished by manually running a script that is
provided. The installation requires some understanding of the SI system design
that is detailed in the information file called README found in the tar file.
When installing WRF SI the command prompt will ask if you would like to also
install the GUI. Answer “Yes.”
2.1 Selecting Perl/Tk
Perl is the
language used to configure WRFSI and WRF scripts. Configuration requires that
environment and file variables are set prior to being run, and many
command-line arguments need to be set as well. Since the process of setting all
these parameters can be a complex task a GUI was developed to assist the user.
Many languages and tools were evaluated and considered to create the GUI.
Perl/Tk was
the tool selected because of its:
•
compatibility with
the existing SI Perl scripts
•
portability to Unix
and Windows platforms
•
ease in building the
GUI using a rich widget set
•
ability to work with
web language (CGI, etc.)
•
availability as open
source and it is well supported.
2.2 Required Software
The software
required for the GUI is C, Perl, Perl/Tk, and (optionally) NCAR Graphics. The
projection mapping software, key to determining a model domain, is written in
C. The C-compiled software allows for faster code than would be possible in
Perl since it, generally, is interpreted code.
The Tk
extension to Perl does not come with the standard Perl distribution. If this is
not already on your system, it is recommended that your system administrator
install Perl/Tk. See www.wrf-model.org/gui/faq
for installation questions and current release recommendations.
The system
software installations required for the SI (run by the GUI) are Fortran, C, and
Perl. The SI software is written in Fortran, Fortran90, and C. It is fully
dynamic by virtue of the Fortran namelist files containing variables such as
entries for domain size, etc. Much of the software comes from the FSL Local
Analysis and Prediction System (LAPS). In existence for many years LAPS has a
robust grid localization software which is used by many researchers and
operational weather centers. It has been tested on numerous computer platforms
and tested for domains that cover the poles and cross the dateline. NCAR/MMM
has also been a source of much of the SI software, including grib_prep, etc.
2.3 Directory Structure
The SI is
designed to allow significant flexibility achieved using three primary
directory structures: one for the source software, one for the installed
executables, and one for the output data. This is implemented using environment
variables where the source software directory is called SOURCE_ROOT, the
executable files directory is called INSTALLROOT, and the setup data directory
is called DATAROOT. In a typical SI implementation, the SOURCE_ROOT and
INSTALLROOT share the same directory. Users should ensure that there is ample
disk space in DATAROOT to accommodate localization output, which can be quite
large.
3. GUI
LAYOUT AND DESIGN
The GUI
described here is customized for WRF, and a banner image is displayed upon
start up, as shown in Fig. 1. The GUI automatically determines a WRF
implementation through a simple evaluation of the system. We allow this
important capability since other weather analysis and forecasting systems can
use this GUI to configure and localize domains (e.g. LAPS).
3.1 Application Layout
The overall
GUI design includes suppressing detail and complexity until the user needs such
information. As such, some controls are disabled and others are not displayed
until they are relevant to the user accomplishing a particular task. Tool tips,
small information boxes, (Fig. 8) are also displayed when the user places the
cursor on certain widgets within the application.
Displaying a
lot of information in a small space is a big challenge in a GUI application.
The notebook-type tabbed panel approach, where tabs are located across the top
of each panel, simplifies the overall layout. It allows the application to have
many panels of information, but allows only one to be shown at a time. An
additional advantage of the tabbed panel approach is sequential navigation
through the tool. The GUI is designed to present graphical tools that can
completely run all of the SI processes in a robust manner that makes sense to
the users of the application. Users can bypass very complicated procedures,
especially for those unfamiliar with scripting. The GUI provides a set of
default values to simplify the user interaction. Users can get useful results
setting up WRF without otherwise knowing how to proceed from the computer
system command prompt.
The
application’s GUI window layout consists of process buttons from the tool
selector to the left of the window and a display containing the editing
tool interface to the right of the window. Always present in the GUI window
is the standard menu bar at the top of the window. The user can exit the
application or query the help pages and version information by selecting
options found on the File and Help buttons of the menu bar,
respectively. At the bottom of the GUI window a User Hints & Information
text area (Fig. 1) sometimes suggests steps to be taken, and at other times
summarizes the success status of the step that has recently been completed.
Figure 1.
Display of WRF GUI application at start up.
The SI is
composed of several components, necessitating a specific sequence of steps that
need to take place. The tool selector buttons with arrows (Figs. 1 and 29)
direct the user in moving through these steps. The steps are Domain
Selection, Initial Data, and Interpolate Data. When a user
presses a button from the tool selector, a corresponding editing tool
interface is displayed (to the right).
Domain
localization and creation of the static surface characteristics file are
accomplished in the Domain Selection editing tool interface (sec. 3.2).
The creation of initial and lateral boundary condition files is achieved in a
two-part task; the first part, acquiring data, is accomplished with the Initial
Data editing tool interface (sec. 3.3), and the second part, interpolating
data to the domain, is accomplished with the Interpolate Data editing
tool interface (sec. 3.4).
3.2 Domain Selection Interface
The phrase domain
localization with respect to WRF SI means to complete the following tasks:
•
Prepare the directory
structure where the SI data will be written.
•
Choose a rectangular
domain on earth, with a fixed center point and projection type.
•
Edit the domain
specifications for the number of grid points, grid spacing, standard latitude
and standard longitude, and to ensure that the resulting map covers the desired
area with this set of parameters.
•
Determine the
vertical grid and the distribution of vertical levels.
•
Set the directory
paths to access geography datasets including: terrain, land-use, greenness
fraction, albedo, top and bottom layer soil types, deep soil mean temperature,
maximum snow albedo, and terrain slope index.
•
Run the localization
scripts.
•
Generate latitude and
longitude pairs for all grid points and process the geography data onto the
domain grid.
•
Verify that the
localization is correct.
The Domain
Selection editing tool interface has the following six panels: Domain,
Horizontal Grid, Vertical Grid, Localization Parameters, Localize Domain, and
Domain Graphics (Figs. 2–22). The order in which the panels appear reflect
the order in which the steps of localization need to be performed, starting
from the left and proceeding right. Below the panels are two control buttons: <Back
and Next> for the user to navigate step-by-step through an otherwise
complicated process with instructions and choices specified as needed.
3.2.1 Domain Panel
The Domain
panel (Figs. 2–4) initiates the first part of the domain localization process.
Users must choose from four options on the pull-down menu under the instruction
“Choose what you want to do”. These options allow the user to
create, load, copy, or delete a domain. After a domain is created, only then
can it be edited, copied, or deleted.
To serve as
a learning tool for a new user, the SI installation automatically creates a
demonstration domain, called default. By loading the default
domain into the GUI, a user can learn about the steps of domain localization by
advancing through the Domain Selection interface. Note the default
domain cannot be modified or deleted; however, it can be copied to a new domain
which can then be edited.
Figure 2.
Display of Domain panel in the Domain Selection Tool.
Within the Domain
panel are four entry box fields for entering information. They are: 1) the
domain name, 2) the path to your data, called DATAROOT (with a file Browser
widget), 3) a description of the simulation, and 4) a user description. The
primary purpose of the Domain panel when creating or editing a domain is
to set key WRF SI environment variables, specifically the MOAD_DATAROOT, a
domain identifier that is used in many of the SI scripts. This variable is
actually a directory that is created by appending the DATAROOT with the domain
name. Fig. 5, for example, will show an area encompassing Australia with Australia
entered as its domain name. In this case, since the DATAROOT is /home/wrf/wrfsi/domains,
then the MOAD_DATAROOT would become /home/wrf/wrfsi/domains/Australia.
To edit an
existing domain, choose the “Load” option from the pull-down menu shown
on the Domain panel (Fig. 3) under the instruction Choose what you
want to do. Then, choose a domain of interest from the list of
available domains. This loads an existing domain into the GUI. Everything about
an existing domain can be modified–except for its name.
To create a
new domain from an existing domain, choose “Copy” from the list of
pull-down menu options. Then choose a domain from a list that will appear. A
name for this copied domain is automatically created from the original name, by
appending a case number. For example, if Australia were selected by the
user to be copied, its automatic domain name would be Australia_001,
with a limit of 999 cases. The user is free to edit any parameter for this
domain–including its name.
To delete a
domain, choose “Delete” from the list of pull-down menu options (Fig.
4). Subsequently, choosing a domain of interest will highlight the domain
selection in red, then ask the user to confirm this action before “remove” is
performed.
Figure 3.
Display of Domain panel in the “Load existing domain” mode. Notice that there
is a preview image of the selected domain.
Figure 4.
Display of Domain panel in the “Delete existing domain” mode.
3.2.2 Horizontal Grid Panel
The
Horizontal Grid panel interface (Fig. 5) allows the user to define a model
domain including nests by drawing a bounding box on a map (left side) and
editing map projection variables (right side). A WRF SI software developer
coined the term “mother-of-all-domains”, known as MOAD, where this term is used
to denote the top-level domain.
3.2.2.1 MOAD
Domain Panel
The global
map image initially shows a Cylindrical Equidistant projection of the world
centered at Latitude 0 and Longitude 0. The entire global map is not displayed
all at once, but the panel has sliding scroll bars on the bottom and right
sides to reposition the image within the panel. The map image can be increased
or decreased in size by pressing the appropriate zoom-in or zoom-out buttons.
The map projection’s interface (the right side of Figs. 5–8) is used to select
the political background map, projection type, and center point values.
Figure
5. Display of Horizontal Grid editor’s main panel.
Initially,
only the map is active at this step; all other interface buttons are disabled.
As the user presses mouse button 1 on the global map and drags the mouse to a
new location, a white domain-bounding box will be drawn that specifies a
domain. Qualitative status information will be displayed in the User Hints
& Information panel, specifically, the lower left (LL) and upper right
(UR) corner latitudes and longitudes and the total number of X, Y grid points
in the selected domain.
As the
domain bounding box is moved and resized, the map projection values update.
Likewise, the user can type in the map projection center point values or grid
size value and, conversely, the domain bounding box display will update.
The SI
satisfies global domain localizations for three commonly used map projections:
Lambert Conformal (both tangent and secant), Mercator, and Polar Stereographic.
Basic understanding of map projections is valuable but not mandatory, because
the GUI has built-in criteria to suggest to the user a projection type based on
the domain’s center point latitude value. For example, the Map Projection
label (Fig. 6) suggests using Lambert Conformal based on a center latitude of
63 degrees, but Polar Stereographic could be chosen instead, if desired.
Validation
checks of user-entered values are integral to the GUI. If errors are detected,
a warning dialog box will appear suggesting steps for the user to take. A
button that is colored light yellow (Figs. 5–7) indicates that this button
needs to be pressed before continuing.
When the
user presses Update Map, both the map and map-editing interface of the
Horizontal Grid editor are updated. The map is now displayed in projection
space based on user-selected information (as seen in the changes between Figs.
5 and 6). The lower left, LL, and upper right, UR, corner point values change
slightly due to the transformation from a map projection in the global
Cylindrical Equidistant to the gridded map projection in, this case, Lambert
Conformal.
Figure 6. Display
of Horizontal Grid panel after the user invokes Update Map.
Users are
able to adjust the domain until they are satisfied with the area it covers and
its grid description values. There are two approaches to fine scale edit a
chosen domain, either move the bounding box or edit its values. Pressing the Domain
Bounding Box button (Fig. 6) selects the mode that allows the user to
interactively manipulate the domain using the mouse cursor to resize or reshape
the box, while the center point and grid spacing values remain fixed (and are
disabled). Pressing the Grid Values button (Fig. 7) selects the
mode to allow the user to adjust the domain bounding box grid values, but it
will prevent the user from editing the box graphically. It is an either/or
choice, but feel free to switch between the two.
Figure 7. Display
of Horizontal Grid panel with “Grid Values” selected as the method to fine-tune
the domain.
There are
several background maps available for use with the WRFSI GUI (Fig. 8). Most of
the files cover the US and originate with WNS AWIPS D2D workstation maps. If desired,
the user is free to add additional map files to the database. Once a map file
is created, it needs to be located in the INSTALLROOT/gui/map directory in
order for the GUI to automatically add this new choice to the list of map
background files found under the pull-down list on the Map Files section
of MOAD Domain panel. The software for creating map background files
originates from the NWS AWIPS use of ARCINFO shapefiles. There is a web link to
the mapping software and a readme information file with instructions on how to
create a custom map background file for use with the WRF SI GUI (see http://www.wrf-model.org/gui/map/ and
http://www.wrf-model.org/gui/map/readme_file.txt).
When
changing the value of the center latitude or longitude, the GUI colors the box
yellow to indicate that the Update Map button needs to be pressed to
draw a new map. If the value is 5 degrees or more than the current value, then
the color of the box turns red indicating a significant value change (Fig 9).
Note: be sure to double check the standard latitude/longitude values if you
change the center point latitude/longitude values.
Figure 8.
“Map File” map background choices, with sample of US Lakes in Texas and
Oklahoma (pink).
Figure 9.
Illustration of colors used to indicate that the center latitude value has
changed (yellow) and when the value has changed more than 5 degrees (red).
At the
bottom of the map projection’s interface are four action buttons: Clear,
Start Over, Reset Values, and Update Map. The Update Map
button will draw a map from a domain-bounding box and grid values. The Start
Over button will undo all commands that updated the originally drawn
domain-bounding box into a domain map. The Clear button erases the
domain-bounding box, returns to the global map and resets all widget values.
The user can fine-tune the domain bounding box and, again, press Update Map
to commit these changes or press Reset Values to cancel the pending
changes.
When the
user is satisfied with the domain without creating nest domain(s), they can
proceed to the Vertical Grid panel by pressing Next>. By
pressing this button, the application both advances to the next panel as well
as creates a directory and writes the wrfsi.nl file (Fig. 10) and two GUI
information files dataroot.txt and domain.gif to directory
INSTALLROOT/templates/Australia.
&hgridspec
1. NUM_DOMAINS
= 1
2. XDIM = 100
3. YDIM = 75
4. PARENT_ID =
1
5. RATIO_TO_PARENT
= 1
6.
DOMAIN_ORIGIN_LLI = 1
7.
DOMAIN_ORIGIN_LLJ = 1
8.
DOMAIN_ORIGIN_URI = 100
9.
DOMAIN_ORIGIN_URJ = 75
10.
MAP_PROJ_NAME = ’lambert’
11.
MOAD_KNOWN_LAT = -27
12.
MOAD_KNOWN_LON = 133
13.
MOAD_STAND_LATS = -27, -27
14.
MOAD_STAND_LONS = 133
15. MOAD_DELTA_X
= 50000
16. MOAD_DELTA_Y
= 50000
Figure 10. INSTALROOT/templates/Australia/wrfsi.nl
namelist showing the definition of MOAD domain.
3.2.2.2 Nest
Domain Panel
The notebook
tab called Nest Domain (seen on the Horizontal Grid panel) is
used to access the nesting graphical interface for users who opt to create one,
or more, subnest. Please keep in mind that a nest domain is completely defined
as a function of its parent domain.
Users will
be able to draw a nest domain, within the GUI, only after they have decided the
values for the three specific parameters (Fig. 11). Keep in mind that a nest is
defined as a function of the values of the parent domain. As such, first,
select a nest Domain ID. Second, select a parent (Parent ID) for
the nest, from a list of choices, corresponding to where the nest is located
(if the default value is not satisfactory). Third, select a Grid Spacing
Ratio to Parent value from a list of choices, again if the default value is
not satisfactory. Once these values are chosen, the graphical interface will
allow the user to draw
Figure 11. Display
of Horizontal Grid panel “Nest Domain” user interface selected showing three
subnests.
a nest
domain using the mouse cursor. A nest must be at least 5 grid points inside the
parent’s grid boundary - the GUI will ensure that this limit is not exceeded.
Each nest is constrained to have its corner points coincident with grid points
of its parent domain. The GUI will ensure this too. The corner point grid
values of the nest are displayed in the entry boxes for the Lower Left I, J,
and Upper Right I, J. As with any domain, users can adjust the nest until
they are satisfied with the area that it covers. The nest can be fine-tuned
either by manually editing the text values, or interactively using the mouse cursor
to change the nest’s size and shape. Status information will be displayed in
the User Hints & Information panel, specifically, the lower left
(LL) and upper right (UR) corner latitudes and longitudes and the total number
of X, Y grid points in the selected domain.
The top
level Domain ID, also called MOAD, is labeled d01, the first nest
Domain ID would be labeled d02, the second nest, if created,
would be labeled d03, and so on. The Parent ID selector allows
the nest to have a choice of parents, with d01 always available, and
initially the only choice available. Subsequently, each time a nest is created
it also becomes an element in the Parent ID selector list and is able to
have a child domain. Said another way, the more nests that are created, the more
choices there are in the Parent ID pull-down list.
The user
does not need any additional nest namelist entries for variables like the X
dimension, Y dimension, or Number of grid points because these are calculated
as a function of the few required values mentioned above and the parent domain
values. Although these nest specification values (X dim, etc.) are displayed
for the user in the Summary of Domains table in the Nest
Domains panel, they are not written to the namelist. The nests center point
is also displayed for the users information and will, most likely, have a
different center point from the parent.
The
highlighted yellow parent box and the highlighted yellow nest box are
indicators to assist the user to identify which nest domain is selected and its
parent (Fig. 12). Changing any parameter on a nest that is a parent mandates
that all the children domains be deleted, although the user is asked before
this action is taken.
Figure 12.
Selected nest, d04 (solid yellow box) with associated parent domain, d03
(dashed yellow box).
Note: If the
GUI will not create the nest you are trying to draw, then look for important
information in the User Hints & Information panel. You just may be
trying to create a child nest completely outside of the (selected) Parent ID
domain. This is a common mistake.
Pressing Delete
Nest (Fig. 13) deletes all information about the nest, its bounding box and
all parameters used, to describe the nest, including the Domain ID.
Pressing Erase Box clears the nest bounding box in order for the user to
redraw it without having to redefine its Parent ID and Grid Spacing
Ratio to Parent. The next release of the WRF SI GUI will include a much
needed Nest Domain Undo button.
Figure 13.
Nest Action buttons to delete and erase nests.
The namelist
in our example (seen graphically in Fig. 11, and as text in Fig. 14.) has a
total of four domains: a parent domain, called MOAD, and three subnests, thus
NUM_DOMAINS=4. The first subnest, called d02, always has d01 as its
parent, where Parent ID =1. The second subnest, called d03, has the same
parent, where Parent ID =1. The third subnest, d04, is a child of d03
and has a Parent ID =3. This is condensed into one argument within the
namelist (seen below), where PARENT_ID =1,1,1,3.
The Grid
Spacing Ratio is an integer value used to determine the number of x/y grid
points and grid spacing of the nest relative to the mother. If
RATIO_TO_PARENT=3 and Delta_X=50, the grid_spacing_x is 16.667 =50/3.
The SI software allows up to 99 nests for one
model domain. The current version of the GUI allows only 9, but this value will
be increased to 99 with the next WRF SI GUI software release.
Note that
the nest naming convention used in the WRFSI and GUI (d01, d02, etc.) coincides
with the naming convention for nest used within WRF. The descriptive NetCDF cdl
files needed to create the nest static files are created by the script
localize_domain.pl. Continuing our Australia example, these important files
would be called wrfsi.cdl, wrfsi.d02.cdl, wrfsi.d03.cdl, and wrfsi.d04.cdl.
Further, the results of running the Fortran executable, gridgen_model, would
generate static.wrfsi, static.wrfsi.d02, static.wrfsi.d03, and static.wrfsi.d04
located in DATATROOT subdirectory domains/Australia/static.
When the user
is satisfied with the domain, and if created nest domain(s), they can proceed
to the Vertical Grid panel by pressing Next>. By pressing this
button, the application both advances to the next panel as well as creates a
directory and writes the wrfsi.nl file (Fig. 14) and three GUI information
files dataroot.txt, domain.gif, and nest_info.txt (Fig. 15) to directory
INSTALLROOT/templates/Australia.
&hgridspec
1. NUM_DOMAINS = 4
2. XDIM = 100
3. YDIM = 75
4. PARENT_ID = 1, 1, 1, 3
5. RATIO_TO_PARENT = 1, 3, 3, 3
6. DOMAIN_ORIGIN_LLI = 1, 8, 54, 20
7. DOMAIN_ORIGIN_LLJ = 1, 14, 5, 16
8. DOMAIN_ORIGIN_URI = 100, 47, 92, 98
9. DOMAIN_ORIGIN_URJ = 75, 69, 71, 73
10. MAP_PROJ_NAME = ’lambert’
11. MOAD_KNOWN_LAT = -27
12. MOAD_KNOWN_LON = 133
13. MOAD_STAND_LATS = -27, -27
14. MOAD_STAND_LONS = 133
15. MOAD_DELTA_X = 50000
16. MOAD_DELTA_Y = 50000
Figure 14. Australia/wrfsi.nl
template namelist showing definition of parent domain with three subnests.
Figure 15.
Files written to INSTALLROOT/templates/Australia when advancing GUI to the
Vertical Grid.
3.2.3 Vertical Grid Panel
The Vertical
Grid panel (Figs. 16 and 17) allows the user to view sigma levels (left
side) and edit these levels (right side). The term “Representative” used in the
label on this panel indicates that the parameter, though valid, is not written
to the wrfsi.nl. They appear only in the GUI as additional information for the
user in determining useful sigma level values.
Figure 16.
Display of Vertical Grid panel with sigma levels displayed in Log Pressure.
Figure 17.
Display of Vertical Grid panel with sigma levels displayed.
Included are
several options to edit the sigma levels. One option allows the user to enter
the number of levels, and then choose one of three sigma level schemes (Fig.
18) to automatically generate the selected number of levels. The options for
schemes are to calculate linear levels in sigma, to calculate square root
levels in sigma, or to calculate the top one-third of the requested levels in
linear and the lower two-thirds of the requested levels in square root in
sigma. A second option is to load an existing file of sigma levels (Fig 19). In
version 2.0.1, earlier versions, it is required to have one sigma value per
line.
Figure 18.
Choose what you want to do to generate sigma levels.
Figure 19.
Read in sigma levels, but make sure there are greater than 14 levels.
A third
option allows the user to add or remove sigma levels via a text-editing window.
Pressing View Levels (found below the text editing window, Figs. 16 and
17) processes user input and displays the sigma values. A quality control
filter eliminates values greater than 1.0 and less than 0.0, as well as
duplicated and non-numerical values. Status information sent to the User
Hints & Information panel contains the minimum and maximum sigma height
distance values. Vertical sigma levels can be displayed in log pressure (Fig.
16), or not (Fig. 17), with the press of a button.
3.2.4 Localization Parameters Panel
From the
beginning of the editing session, the user’s selections modify the variables in
the domain’s wrfsi.nl namelist, including the paths to surface geography files
(Fig. 20). When the user is satisfied with the values thus far, they advance to
the Localize Domain panel.
Figure 20. Display
of Localization Parameters panel.
3.2.5 Localize Domain Panel
At this
point the user is ready to run the Perl scripts and Fortran programs to
localize the domain. The window_domain_rt.pl command with command line
arguments are shown in the (noneditable) text window (Fig. 21). To run this
process, press Localize. Depending on the grid size and grid spacing of
the configured domain, this process can take seconds to several minutes to run
to completion. Status output from the process is sent to the same window.
If a failure
occurs, potentially important log information will be written to this same text
window. The first place to look for the source of a localization failure
problem is to confirm that the directory path to geographical data is correct
and valid. The path to geographical data can be modified, and see Path
Preferences (section 3.5, Fig. 34) for more information on this topic. Note
that for the domain localization process, the GUI forks a process enabling the
text window to receive status information during localization. All other
external processes (grib_prep.pl, etc.) will disable the GUI until the process
terminates.
The product
of domain localization is a defined, localized two-dimensional grid. Of
specific interest is a NetCDF (network Common Data Format) file called
MOAD_DATAROOT/static/static.wrfsi.d01. This static file contains all
nonvarying information required for the WRF model, including terrain, land-use,
latitudes and longitudes, map factor, and several other parameters.
This a list of the
window_domain_rt.pl command line options and explanations:
-w Mandatory input. Set to 'laps' or 'wrfsi'.
-s Use to override the Source Root
environment variable if set.
-i Use to override the Install Root
environment variable if set.
-d Use to override the Data Root environment
variable if set.
-t Path to template - a subset of namelist
variables specific to the domain.
-c Switch to control complete removal of Data
Root. Use with caution.
Figure 21. Display
of Localize Domain panel.
3.2.6 Domain Graphics [Optional]
The user can
create and view graphic images (Figs. 22) to see the results of a WRF SI domain
localization, and specifically create and view images of the static land
characteristic files. To do this, both NCAR Graphics 4.2.0 (or higher) and NCL
must be installed and the NCAR Graphics environment variables NCARG_ROOT and
NCL_COMMAND must be set. Six sample images of graphics output from the Australia
localization are created with this method from the GUI (Figs. 23–28).
Figure 22. Display
of Domain Graphics panel. This user has NCAR Graphics Command Line (NCL)
available and is able to create and view geographical images from output from
the domain localization.
It is not
necessary to use the GUI to run NCL, but again, NCAR Graphics with NCL must be
installed and their environment variables set. The GUI will suppress the Domain
Graphics user interface option if these two variables are not set.
Following is an example of how to set these variables and includes NCAR_RANGS:
setenv NCARG_ROOT
/usr/local/ncarg-4.3.0
setenv NCL_COMMAND
/usr/local/ncarg-4.3.0/bin/ncl (must
include ncl)
setenv NCARG_RANGS
/data/ncl/rangs (optional high
resolution coastline data)
To create
graphics plots of the WRF SI static fields outside of the GUI, just cd to
INSTALLROOT/graphics/ncl/ and run the perl script generate_images.pl. For
example:
cd INSTALLROOT/graphics/ncl
setenv MOAD_DATAROOT
/wrfsi/domains/Australia
generate_images.pl
Or,
cd INSTALLROOT/graphics/ncl
generate_images.pl
-domain=/wrfsi/domains/Australia
See additional usage information for
generate_images.pl by using the “--help” command line flag.
3.3 Initial Data Interface
In addition
to domain localizations, the SI prepares large-scale model data for WRF model
initialization and lateral boundary condition requirements. The Initial
Data interface (Figs. 30-31) performs the first of a two-part task to
provide the initial and lateral boundary condition data files. Here the user
interface runs the Perl script, grib_prep.pl, which acquires background model
data, and then uses specified directories to decode and store this data.
To continue
with an illustrative example, once the Australia domain has been
localized, press the Initial Data button from the tool
selector (Fig. 29) and the Initial Data editing tool interface will
display (Fig. 30).
Figure 29.
Process buttons from the tool selector.
3.3.1 Sources Panel
The
grib_prep Fortran executable is responsible for decoding GRIB files. The grib_prep.nl
namelist file controls the execution of the grib_prep executable. This Source
panel interface (Fig. 30) allows users to add (GRIB formatted) models that are
available to their computer system, to initialize WRF by creating WRF lateral
and boundary condition datasets. An entry line, one for each model, is
separated into five columns of important information that needs to be closely
configured. Note: an orange colored value indicates an invalid directory path
to the data (Fig. 30). Pressing the Save button both writes the
grib_prep.nl namelist file and updates the user interface pull-down menu list
of model Data Sources located on the Script panel (Fig. 31). This
makes it easy for the user to run grib_prep.pl.
3.3.2 Script Panel
The Scripts
panel interface assists users in configuring their Perl grib_prep.pl
script, which runs the Fortran executable grib_prep (which in turn reads the
file grib_prep.nl).
First, the Script
panel assists the user in composing command line arguments for grib_prep.pl.
By choosing a Data Source from a pull-down menu, for example AVN, the
grib_prep.pl command is composed and displayed in a text window. A list of
command line options is also shown. Second, the user can run this command by
pressing Run, or save the command to a script file with Save. A
reason to save this command would be to run the command in a job scheduling
process (like cron) in order to run the model daily or operationally, for
example.
Figure 30.
Initial Data Interface–Sources panel. Used to create the grib_prep.nl file.
Figure 31.
Initial Data Interface–Scripts panel. Used to create grib_prep.pl with command
line arguments.
The list of
data files can help a user correctly set command line options such as setting
the forecast time interval (-t) equal to 3 hours and likewise setting the
forecast length (-l) equal to 36 hours. This is an explanation of the some of
the grib_prep.pl command line arguments:
-l Forecast length in hours.
Set the
number of forecast hours the data should span.
If not set, this will default to 36 hours.
-s YYYYMMDDHH
Cycle time
to use for initial time. If not set, the script uses the real-time clock in
conjunction with variables in the grib_prep.nl file to determine this time.
-t hours
Desired
interval between output files. The
default if not set is 3-hourly output.
As shown in
the illustrative example of setting up WRF for a model run over Australia,
press Run to acquire background data (Fig. 31), after filling in the
model data sources that are available on your system (Fig. 30).
3.4 Interpolate Data Interface
The Interpolate
Data editing tool interface (Figs. 32 and 33) performs the second of a
two-part task in providing the initial and lateral boundary condition data
files. Here the user interface runs the script wrfprep.pl, which interpolates
background model data to a specific domain. Note that this interface is
disabled unless the selected domain has been localized, and necessary
localization files are present.
3.4.1 Controls Panel
The Controls
panel (Fig. 32) contains parameters to interpolate initial and lateral boundary
condition files to the domain. These values are written to the namelist, wrfsi.nl,
and are used by Perl scripts to interpolate the initial and lateral boundary
files discussed in section 3.3 Initial Data interface.
Figure 32. Interpolate
Data Interface–Controls panel. Used to update wrfsi.nl with respect to
parameters that apply for use with wrfprep.
3.4.2 Script Panel
The
Interpolate Data Interface Scripts panel (Fig. 33) assists the user in
configuring the wrfprep.pl command with a list of command line
options listed in a text window. A text window labeled ‘Data files’ will list
the data files found on the system, created by running grib_prep.pl in the
first part of this two-part task. The list of data files can help a user
correctly set command line options such as setting the forecast length
interval:
-f RUN_LENGTH (in hours)
If not set,
the program assumes a 24-h forecast period
Figure 33. Interpolate
Data interface–Script panel. Used to create wrfprep.pl with command line
arguments.
The user is
able to immediately run this command by pressing Run, or to save the
script to a file with Save. In the example case, you would press Run
to interpolate background data to the Australia domain, completing the
final step in the illustrative example.
3.5 Path Preferences
The Path
Preferences menu button to display the Path Preferences
interface is found under the menu bar’s Edit pull-down menu (Fig. 34).
The ability
to edit path preferences allows users to enter new paths specifically to
external and geographical data from the values that were defined when the
install script (install_wrfsi.pl) ran. A user may want to change these if, say,
a group of modelers are using the same software and preferred to locate their
datasets in a different directory locations.
Figure 34. Display
of Path Preferences panel. Used to edit environment variables.
3.6. Source
of the Terrain and Surface files for WRF
WRF's static
datasets came from the following sources:
elevation: USGS 30 sec
tiles
vegetation/landuse: USGS Version
2 landcover data
soil
category: United Nation FAO 5 min global data combined with 30 sec
STATSGO North America
vegetation
fraction: NCEP
monthly
albedo/max snow albedo: NCEP
greenness
fraction: NESDIS
1-degree
deep soil: based on ECMWF surface air temp corrected to sea
level
1-degree
slope data: NCEP
4. FUTURE WORK
The WRF GUI
is not a finished product, and there are plans for upgrades and additional
capabilities. We envision the GUI capable of assisting the user with many other
tasks associated with WRF system setup, running, and evaluation.
4.1 Model Setup
The GUI does
not yet allow the user to interact with the WRF model namelist file, wrf.nl,
though this has been discussed. Plans to incorporate the nesting functionality
are in progress and should be available by Spring 2004.
4.2 Graphics Displaying SI Meteorology
Because the
SI generates the initial and lateral boundary condition files for WRF, it is
important that users evaluate this data. Currently there is no method for
displaying the meteorology in these interpolated data files. We expect to use
existing graphics packages similar to those already used in the GUI to generate
such graphics.
5. SUMMARY
The Forecast
System Laboratory has created a graphical user interface capable of
accommodating researcher and forecasting needs when using the SI. Since the SI
is a necessary first step when using the WRF model, the GUI provides an easy
method to prepare an otherwise quite complicated system. Currently more than
600 users have downloaded the latest SI version 2.0.1 containing the GUI. Some valuable feedback has been obtained
from the users. We plan to update the version frequently to keep up with users’
needs and the latest software.
6. ACKNOWLEDGMENTS
The authors
are very grateful to the staff in FSL’s LAPS Branch and the many discussions
with them during the GUI development including software assistance from Phil
McDonald, Linda Wharton and Thomas Helman. Thanks to Mark Govett for reviewing
this paper.
7. REFERENCES
Lidie, S., and N. Walsh. Mastering
Perl/Tk. Sebastoopol (CA): O’Reilly & Associates, 2002.
NOAA Forecast Systems
Laboratory, 2004, WRFSI Software, (http://wrf-model.org/si).
NOAA Forecast Systems
Laboratory, 2004, WRFSI Users Guide, (http://wrf-model.org/gui).
National Center for Atmospheric Research, 2004, WRF homepage, (http://wrf-model.org).