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
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
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.
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.
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.
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 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.
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.
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.
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.
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).
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 degrees (where delta X in degrees = delta
X
kilometers multiplied by 0.00650 and delta Y in 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.
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.
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.
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.
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.
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 or 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.
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.
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.
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).
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.
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).
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.
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 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.
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.
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:
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.
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).