*WRFSI GUI User's Guide 2.1*

USERS GUIDE TO THE GRAPHICAL USER INTERFACE TO PREPARE THE

STANDARD INITIALIZATION FOR WRF VERSION 2.1

September 2005

Paula T. McCaslin\*, John R. Smart\*\*, and Brent Shaw\*\*\*

NOAA Research - Forecast Systems Laboratory\
Boulder, Colorado

**1. INTRODUCTION**

[^1]

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, and choosing data sources, etc. to meet
their modeling needs. The WRF modeling system includes two dynamic
cores: the Advanced Research WRF (ARW) developed by NCAR/MMM (formerly
referred to as the Eulerian Mass core) and the Nonhydrostatic Mesoscale
Model (NMM) developed by NOAA/NCEP. Each dynamic core currently has a
separate SI package and GUI. Options unique to each package are noted in
this document.

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 for the appropriate
dynamic core from the WRF SI web site: <http://wrfsi.noaa.gov/>,
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 the user would like to also install the GUI. Answer "Yes."

**2.1 *Selecting Perl/Tk***

Perl is the language used to configure WRF SI 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 that 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 Perl/Tk is not already available on your system, it is
recommended that your system administrator install Perl/Tk. See
[www.wrf-model.org/gui/faq](http://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 that 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 directory
structure is implemented using environment variables where the source
software directory is called SOURCE_ROOT, the executable 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 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. This important capability is allowed because 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 and 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.

![](media/image1.wmf){width="6.680555555555555in"
height="4.847222222222222in"}

**Figure 1. Display of WRF GUI application at start up.**

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 under 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.

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 completing
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 that can then be edited.

![](media/image2.wmf){width="6.652777777777778in"
height="4.458333333333333in"}

**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, shows an area encompassing Australia
with *Australia* entered as its domain name. In this case, since the
DATAROOT is */home/wrf/wrfsi/domains,* the MOAD_DATAROOT becomes
*/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.

![](media/image3.wmf){width="6.611111111111111in"
height="4.083333333333333in"}

**Figure 3. Display of Domain panel in the "Load existing domain" mode.
Notice that there is a preview image of the selected domain.**

![](media/image4.wmf){width="6.694444444444445in"
height="4.097222222222222in"}

**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 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 initial global map image 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 located above the upper left
corner of the map image. 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.

![](media/image5.png){width="6.495833333333334in"
height="4.711111111111111in"}**Figure 5.** **Display of Horizontal Grid
editor's main panel.**

Initially, only the global 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. The total number of X grid points for a new domain is
100 for ARW and 51 for NMM. Y is calculated as a function of X and the
surface area covered by the domain-bounding box. These area calculations
also determine an initial value for grid spacing. 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 the domain bounding box display will update to match these
specifications.

The WRF-ARW SI satisfies global domain localizations for three commonly
used map projections: Lambert Conformal (both tangent and secant),
Mercator, and Polar Stereographic. The WRF-NMM SI uses a rotated
latitude longitude projection. Basic understanding of map projections is
valuable but not mandatory, because the GUI has built-in criteria to
suggest to the ARW 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 for 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, which in this case, is
Lambert Conformal.

![](media/image6.png){width="6.492361111111111in"
height="4.909027777777778in"}

**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 & Projection 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. Note: For
WRF-NMM, the center point latitude and longitude must always coincide
with the true latitude and standard longitude, respectively. Hence the
NMM user is only allowed to edit the standard longitude and true
latitude.

![](media/image7.png){width="6.492361111111111in"
height="4.696527777777778in"}

**Figure 7.** **Display of Horizontal Grid panel with "Grid & Projection
Values" selected as the method to fine-tune the domain.**

There are several background maps available for use with the WRF SI GUI
(Fig. 8). Most of the files cover the US and originate with NWS 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 (Fig 9). Note: Be sure to double check
the standard latitude/longitude values when changing the center point
latitude/longitude values.

![](media/image8.wmf){width="6.5in" height="1.7361111111111112in"}

**Figure 8. "Map File" map background choices, with sample of US Lakes
in Texas and Oklahoma (pink).**

![](media/image9.png){width="4.757638888888889in"
height="1.2909722222222222in"}

**Figure 9. Illustration of colors used to indicate that the center
latitude value has changed (yellow).**

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.

**&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 10a.** **INSTALLROOT/templates/Australia/wrfsi.nl namelist
showing the ARW definition of MOAD domain.**

When the user is satisfied with the domain they have created, they
proceed to the *Vertical Grid* panel by pressing **Next\>**. By pressing
this button, the application both advances to the next panel as well as
writes a series of files after making a directory, if necessary. The
files that are written to this directory location are the wrfsi.nl file
(see Fig. 10a and b) and two GUI information files dataroot.txt and
domain.gif. In this example, the files are written to the directory
INSTALLROOT/templates/Australia. For the ARW core, the user is able to
create nest domains within this *Horizontal Grid* panel (see section
3.2.2.2). Nesting is not currently available for the NMM core.

The SI namelist, wrfsi.nl, contains the same list of parameters for both
WRF cores, except for an additional projection parameter MOAD_KNOWN_LOC
for the NMM core, which is always set to 'center'. For a given domain,
the value of XDIM for the NMM core is roughly half the value of XDIM for
the ARW core. The value of YDIM for the NMM core must be an odd number
value. For the ARW, both MOAD_DELTA_X and MOAD_DELTA_Y are written in
kilometers, whereas for the NMM, these parameters are written in radian
degrees (where delta X in radian degrees = delta X kilometers multiplied
by 0.00650 and delta Y in radian degrees = delta Y kilometers multiplied
by 0.00604).

**&hgridspec**

1.  **NUM_DOMAINS = 1**

2.  **XDIM = 51**

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 = 51**

9.  **DOMAIN_ORIGIN_URJ = 75**

10. **MAP_PROJ_NAME = 'rotlat'**

11. **MOAD_KNOWN_LAT = -27**

12. **MOAD_KNOWN_LON = 133**

13. **MOAD_KNOWN_LOC = 'center'**

14. **MOAD_STAND_LATS = -27, -27**

15. **MOAD_STAND_LONS = 133**

16. **MOAD_DELTA_X = 0.325**

17. **MOAD_DELTA_Y = 0.302**

**Figure 10b.** **INSTALLROOT/templates/Australia/wrfsi.nl namelist
showing the NMM definition of MOAD domain.**

**3.2.2.2 *Nest Domain Panel (for ARW core only)***

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. Nesting
applies for the ARW core only.

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 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.

![](media/image10.png){width="6.492361111111111in"
height="4.7034722222222225in"}

**Figure 11.** **Display of Horizontal Grid panel "Nest Domain" user
interface selected showing three subnests.**

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.

![](media/image11.wmf){width="3.7777777777777777in"
height="1.7777777777777777in"}

**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
included is a much-needed Nest Domain **Restore All Nests** button that
loads all nests previously written to disk. If you change a nest value
and it has been written to disk, then pressing this button reloads the
nest(s) to its previous values.

![](media/image12.png){width="4.104166666666667in"
height="0.5729166666666666in"}

**Figure 13. Nest Action buttons to delete, erase and restore 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.**

![](media/image13.wmf){width="6.138888888888889in"
height="1.9305555555555556in"}

**Figure 15. Files are 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 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 evaluating sigma level
minimum and maximum thickness values.

![](media/image14.png){width="6.492361111111111in"
height="4.7034722222222225in"}

**Figure 16. Display of Vertical Grid panel with sigma levels displayed
in Log Pressure.**

![](media/image15.png){width="6.496527777777778in" height="2.2375in"}

**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 or
earlier versions, it is required to have one sigma value per line.

![](media/image16.wmf){width="5.375in" height="1.2777777777777777in"}

**Figure 18. Choose what you want to do to generate sigma levels.**

![](media/image17.wmf){width="5.375in" height="1.5972222222222223in"}

**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.

The Localization Panel contains two sections: Horizontal Grid Spec and
Static Geographical Data Files (Fig. 20). Most of the parameters listed
in the Localization Parms section are based on the user's selections up
to this point. The only parameters in this section that can be modified
via this panel are SILAVWT_PARM_WRF and TOPTWVL_PARM_WRF. To modify the
other parameters, return to the appropriate prior panel. The Static
Geographical Data Files section allows the user to modify the path to
the surface geography files.

![](media/image18.wmf){width="6.472222222222222in"
height="4.708333333333333in"}

**Figure 20.** **Display of Localization Parameters panel for ARW. For
the NMM core, we see an additional projection parameter, MOAD_KNOWN_LOC
= 'center'.**

**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 for the
ARW and MOAD_DATAROOT/static/static.wrfsi.rotlat for the NMM. 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.

The following is a list of the window_domain_rt.pl command line options
and explanations:

\-**w** Mandatory input. Set to \'laps\', \'wrfsi\', or 'wrfsi.rotlat'
(for the LAPS model, WRF-ARW core and WRF-NMM core, respectively.

\-**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.

![](media/image19.wmf){width="6.472222222222222in"
height="4.680555555555555in"}

**Figure 21.** **Display of Localize Domain panel for ARW, for the NMM
core, -w wrfsi.rotlat would be used.**

**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).

![](media/image20.wmf){width="6.486111111111111in"
height="4.347222222222222in"}

**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. The following is an example of how to set these
variables, including 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.

![](media/image21.wmf){width="6.5in"
height="3.0in"}![](media/image22.wmf){width="6.5in"
height="2.8333333333333335in"}![](media/image23.wmf){width="6.5in"
height="3.0in"}

**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. For this step, 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 the 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).

![](media/image24.wmf){width="2.138888888888889in"
height="2.4027777777777777in"}

**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, located in EXT_DATAROOT/static
controls the execution of the grib_prep executable. The *Sources* panel
interface (Fig. 30) allows users to add (GRIB formatted) models that are
available on 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 updates the grib_prep.nl namelist file to reflect the user's
entries and updates the user interface pull-down menu list of model
**Data Sources** located on the *Script* panel (Fig. 31). This panel
makes it easy for the user to specify the Data Sources information
needed for running 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 the command line 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**. One 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.

![](media/image25.wmf){width="5.444444444444445in"
height="3.6666666666666665in"}

**Figure 30. Initial Data Interface--Sources panel. Used to create the
grib_prep.nl file.**

![](media/image26.wmf){width="5.458333333333333in"
height="3.6805555555555554in"}

**Figure 31. Initial Data Interface--Scripts panel. Used to create
grib_prep.pl with command line arguments.**

The list of command line options 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.

The following is an explanation of 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). The products of grib_prep are decoded model data files
that reside in EXT_DATAROOT/extprd.

\-**f** RUN_LENGTH (in hours)

If not set, the program assumes a 24-h forecast period

**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.

![](media/image27.png){width="5.445833333333334in"
height="3.7194444444444446in"}

**Figure 32.** **Interpolate Data Interface--Controls panel (shown for
ARW) edits wrfsi.nl's &interp_controls section containing parameters
that apply to wrfprep.pl.**

**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.

**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 that were 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:

![](media/image28.wmf){width="5.416666666666667in"
height="3.7083333333333335in"}

**Figure 33.** **Interpolate Data interface--Script panel. Used to
create wrfprep.pl with command line arguments.**

Once the user has edited the wrfprep.pl command line to reflect their
configuration, 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, the user would press **Run** to interpolate background
data to the *Australia* domain, completing the final step in the
illustrative example. The products of wrfprep.pl are found in
MOAD_DATAROOT/siprd. If the process is successful, the user should find
the following types of files in this directory:

hinterp.d01.yyyy-mm-dd_hh:mm:ss

wrf_real_input(\_nm).d01. yyyy-mm-dd_hh:mm:ss

where the hinterp files are output from the horizontal interpolation
process and wrf_real_input files are the output from the vertical
interpolation process. The wrf_real_input files are the files used to
generate the initial and boundary condition files used to run WRF. Note
that the wrf_real_input files have an additional "nm" identifier in
their name.

**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 paths to
external and geographical data that are different from what 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 different directory locations.

![](media/image29.wmf){width="5.416666666666667in"
height="2.6527777777777777in"}

**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 originate 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**

There are plans to unify the SI package for the two dynamic cores. This
effort is being considered by NCAR, who is further developing the SI
software to optimize and parallelize several components of the package.

Because the SI package is different for the two cores, the GUI currently
works with either the ARW or NMM by setting a software flag prior to
starting the GUI application. (The flag, **nmm** set to 0 or 1, is
located in SOURCEROOT/gui/guiTk/ui_system_tool.pl.) The WRF GUI is not a
finished product, and there are plans for upgrades and additional
capabilities. Important in keeping the GUI current with the NCAR revised
software, there are also plans to update the GUI as the SI evolves. We
also envision a 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.

**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 2500 users have downloaded the latest SI
versions 2.X 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. Thanks to Louisa Nance for reviewing this
paper.

**7. REFERENCES**

Lidie, S., and N. Walsh. *Mastering Perl/Tk*. Sebastoopol (CA): O'Reilly
& Associates, 2002.

NOAA Forecast Systems Laboratory, 2005, WRFSI Software,
(<http://wrfsi.noaa.gov/>).

NOAA Forecast Systems Laboratory, 2005, WRFSI Users Guide,
(<http://wrfsi.noaa.gov/gui>).

National Center for Atmospheric Research, 2005, WRF homepage,
([http://wrf-model.org](http://wrf-model.org/)).

[^1]: *\*Corresponding author address:*  Paula McCaslin, NOAA/FSL R/FS1,
    325 Broadway, Boulder, CO 80305-3328; e-mail:
    <Paula.McCaslin@noaa.gov>

    \*\*SRG, Boulder, Colorado, \*\*\*Weather News, Norman Oklahoma.