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

 

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

 

 

"Created with The GIMP"

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

 



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