A Users' Guide to RIP Version 4.4:
A Program for Visualizing
Mesoscale Model Output

Mark T. Stoelinga
University of Washington

May 2008



Table of Contents

  1. Introduction
  2. Setting up RIP on your system
  3. Preparing data with RIPDP
  4. The RIP user input file
  5. Running RIP
  6. Calculating and plotting trajectories
  7. Creating a data set for Vis5D
  8. Other special situations

Appendix A. Keywords
Appendix B. Available fields for plotting
Appendix C. Format of RIP data files
 

1. Introduction

RIP (which stands for Read/Interpolate/Plot) is a Fortran program that invokes NCAR Graphics routines for the purpose of visualizing output from gridded meteorological data sets, primarily from mesoscale numerical models._ It was originally designed for sigma-coordinate-level output from the PSU/NCAR Mesoscale Model (MM4/MM5), but was generalized in April 2003 to handle data sets with any vertical coordinate, and in particular, output from the Weather Research and Forecast (WRF) modeling system. It can also be used to visualize model input or analyses on model grids. It has been under continuous development since 1991, primarily by Mark Stoelinga at both NCAR and the University of Washington. RIP is an officially supported component of the WRF modeling system, but could potentially be used with output from any mesoscale model.

The program is designed to be portable to any UNIX system that has a Fortran 77 or Fortran 90 compiler and the NCAR Graphics library. The UNIX operating system is not necessarily a requirement, but this document is written with the assumption that you are working on a UNIX system. The author has not given a considerable amount of thought to problems that may arise on another operating system.

RIP can be described as "quasi-interactive". You specify the desired plots by editing a formatted text file. The program is executed, and an NCAR Graphics output file is created. The plots can be modified, or new plots created, by changing the user input file and re-executing RIP. Some of the basic features of the program are outlined below:


 

2. Setting up RIP on your system

a. Obtaining and unpacking the code and related files

The most recent version of the code can be downloaded from NCAR's WRF ARW download web page (registration required), or from NCAR's PSU/NCAR Mesoscale Model ftp site. Download the compressed tar file, RIP4.TAR.gz, to your local machine, and uncompress the file (i.e., gunzip RIP4.TAR.gz). The tar file contains a top-level directory called RIP, in which all the RIP-related files reside. Unpacking the tar file (i.e., running tar xf RIP4.TAR) will create a RIP directory, as a subdirectory of your current working directory, and will place all the RIP-related files in that new RIP directory. Thus, before unpacking the RIP tar file, you should first change to a directory that you want to be the parent directory of your RIP directory. This would commonly be your home directory. The tar file contains the following directories and files:

b. The RIP_ROOT environment variable

An important environment variable for the RIP system is RIP_ROOT._ RIP_ROOT should be assigned the path name of the directory where all your RIP program and utility files (color.tbl, stationlist, lookup tables, etc.) reside. If you unpacked the RIP tar file in your home directory, then the natural choice for your RIP_ROOT directory is the RIP subdirectory that was created when you unpacked the RIP tar file.

For simplicity, you should define RIP_ROOT in one of your UNIX start-up files. For example, if you use c-shell, and you have unpacked your RIP files into a directory called /users/johndoe/RIP, and that is where you intend to have the code and utility files reside, you should include in your .login or .cshrc file the line

setenv RIP_ROOT /users/johndoe/RIP

RIP uses the system call getenv to retrieve the value of RIP_ROOT from within the program. If your system's Fortran does not support the system call getenv, you can use instead the variable rip_root in the &userin namelist in the RIP user input file (UIF) to tell RIP where to find the utility files. This is described in more detail in Chapter 4 of the Users' Guide.

In general, the utility files mentioned above require no editing or user input. The exceptions to this are the color table file, color.tbl, which allows you to define colors that will be used by RIP, and the observing station listing file, stationlist, which provides location information for observing stations that may be referenced in various aspects of the plot request._ These are described below.

c. Changing the color table file

As you become more familiar with how RIP uses colors, you may want to customize color.tbl to suit your own preferences. In the color table, colors are defined according to fractions of red, green, and blue, with each fraction being a number from 0.0 to 1.0. Each color is given a name. You can define up to 256 different colors, but RIP will warn you if you define more than 200, because RIP also needs to make use of the 256 available color slots to define color shades for color-filled contour plots. The basic structure of the table is as follows. The first four lines are ignored – they are simply a banner that says that this is the color table. The first two colors should always be given the names def.background and def.foreground, in that order. However, their color fractions can be changed if desired. def.background is the color used by NCAR Graphics for any regions where no plotting instructions have been given (i.e. the default background color). def.foreground is the color used by NCAR Graphics for any plotting instructions in which you did not explicitly ask for a particular color (i.e. the default foreground color). Usually these are either black and white, or white and black, but the fractions can be changed to make them different colors, as already mentioned above. It is recommended that, regardless of the colors you use for def.foreground and def.background, you also have those colors defined with their appropriate names somewhere else in the table. For example, even if color indices 0 and 1 are given the fractions 0.0,0.0,0.0 and 1.0,1.0,1.0, there should also be colors named black and white with the same fractions somewhere else in the table. The explicitly named black or white should be used when you want things to be black or white. That way, if you change def.foreground or def.background to something else, the things that should remain black and white won't change color. The table should end with a line that contains several consecutive minus signs.

To give the user added flexibility, and for compatibility with previous versions of RIP, the user can place a color table (like the one that appears in color.tbl) directly into a RIP user input file (UIF). This allows the user to define different color tables that are unique to a particular UIF. The color table should be placed between the namelist section and the plot specification table in the UIF. If you run RIP with a UIF that contains a color table, RIP will recognize that color table and read it instead of (NOT in addition to) the color table in your RIP_ROOT directory.

Finally, there are a few important things that you should be aware of if you will be translating your CGM plots to postscript:

d. Changing or adding station listings in the stationlist file

Any number of additional stations can be added to the station listing. The important thing is to keep the station information properly lined up in the appropriate columns. The important pieces of information to enter are the verbal description of the location (under column "Location"), the ICAO four-letter code identifying the station (under column "ICAO"), the latitude and longitude (under columns "Lat" and "Lon"), and the WMO number of the station (under column "WMO#"). The other information is not read by RIP. Elevation should be entered if you have it, because it may be used in the future. The author is unsure of the meaning of the information in the third column. If the WMO number is unknown or the station has no WMO number, enter "00000" in that column.

e. Compiling RIP and associated programs

RIP should be compiled with the UNIX make utility. There is a top-level make file, called Makefile, in the RIP/ directory, as well as a secondary Makefile in the RIP/src/ directory, that are used for "making" RIP.  The make command should be executed from within the RIP/ directory.  First, you should run the command make without any options, which will show a brief help listing on how to run make to compile RIP on your particular platform.  You should choose the option that will most likely work on your platform, and then run the make command with that option.  For example, if you are on a LINUX system, type

make linux >&! make.out &

The redirecting of make print output to the file make.out is optional.  A successful compilation will probably take several minutes. If you have a multiprocessor machine, you may want to find out how to run make so that the machine compiles on all processors at the same time, as this may significantly speed up the compilation wall clock time.

If the compiling of RIP fails, it is likely that the top-level make file needs to be customized for your particular platform.  This involves editing Makefile so that the compile and link commands and options are correctly configured for the particular system you are running on. There are several sections of code in the makefile that pertain do different machines.  One of these sections needs to changed, or a new one created.  The important features that need to be adjusted are the compiler flags (FFLAGS), link flags (LDFLAGS), and libraries (LIBS).  The libraries should include NCAR Graphics libraries--make sure you have the correct location for the NCAR Graphics libraries on your system.  In some cases, you may be able to use ncargf77 as the compiler (i.e., set the CF variable to ncargf77) and not worry about specifying all the specific libraries that are required for NCAR Graphics. Regardless of how you accomplish the linking with NCAR Graphics, it should be pointed out that the author has found some minor problems with RIP that occur if you use a version of NCAR Graphics that is older than 4.0. Therefore, you should try to link with NCAR Graphics 4.0 (or later) if you have it. It should also be noted that the RANGS/GSHHS high-resolution map background capability is only functional if you have NCAR Graphics 4.3 (or later). RANGS/GSHHS is not the most commonly used map background outline set, so this does not represent a significant loss of functionality if you cannot use it.

The two versions of RIPDP for the WRF modeling system, ripdp_wrfarw and ripdp_wrfnmm, need to link to the NetCDF library. This library of routines is used for I/O with files in the “Network Common Data Fromat” or NetCDF, which WRF uses. The only thing the user needs to be concerned about is that the variables NETCDFLIB and NETCDFINC in the secondary Makefile in the RIP/src/ directory are set properly for the path names of the directories where the NetCDF library file and include files reside, respectively.

A successful compilation will result in the creation of several object and executable files in the RIP/src/ directory.  The make file is also set up to create symbolic links in the RIP/ directory to the actual executables in the RIP/src/ directory.  In UNIX, the best way to make the RIP program and other associated executables accessible to you, regardless of your current working directory, is to add the path name of your RIP directory to your executable path list (e.g., the path shell variable in c-shell). For example, if the above-mentioned symbolic links to the RIP executables reside in the directory ~johndoe/RIP, and you use the c-shell in UNIX, then you should add the following line in your .cshrc file:

set path = ($path ~johndoe/RIP)

With the RIP directory in your executable path, the RIP program (and other associated utilities like ripdp) can be accessed easily without having to put the executables in your working directory or having to specify full path names for the executables.

f. Notes on nonstandard Fortran 77

In general, the author has attempted to adhere to Fortran 77 standards as much as possible in writing the code. However, a few nonstandard features have been included, which are still available in most f77 and f90 compiling systems.

&samplenlist
beatles='John','Paul','George','Ringo',
(or with Sun f90, beatles(1)='John',beatles(2)='Paul',etc.)
primenumbers=1,2,3,5,7,11,13, flag=.true.,
&end

Not all the variables that are defined as part of the namelist in the Fortran program need to be given values in the namelist file that is read. Typically, all the namelist variables are assigned default values in the program prior to the reading of the namelist file, so that they will retain those default values if they are omitted from the namelist file.

 

3. Preparing data with RIPDP

RIP does not ingest model output files directly. First, a preprocessing step must be executed that converts the model output data files to RIP-format data files. The primary difference between these two types of files is that model output data files typically contain all times and all variables in a single file (or a few files), whereas RIP data has each variable at each time in a separate file. The preprocessing step involves use of the program RIPDP (which stands for RIP Data Preparation). RIPDP reads in a model output file (or files), and separates out each variable at each time. There are several basic variables that RIPDP expects to find, and these are written out to files with names that are chosen by RIPDP (such as uuu, vvv, prs, etc.). These are the variable names that RIP users are familiar with. However, RIPDP can also process unexpected variables that it encounters in model output data files, creating RIP data file names for these variables from the variable name that is stored in the model output file metadata.

When you run make, it should produce executable programs called ripdp_mm5, ripdp_wrfarw, and ripdp_wrfnmm. Although these are three separate programs (one for use with MM5 model system, one for WRF-ARW, and one for WRF-NMM), they serve the same purpose, and will be referred to collectively as ripdp. Also, the two WRF versions of ripdp may be referred to collectively as ripdp_wrf, without the arw or nmm specification.

a. Running RIPDP

The program has the following usage:

ripdp_XXX [-n namelist_file] model-data-set-name [basic|all] data_file_1 data_file_2 data_file_3 ...

In the above, the "XXX" refers to either "mm5", "wrfarw", or "wrfnmm". The argument model-data-set-name can be any string you choose, that uniquely defines this model output data set. It will be used in the file names of all the new RIP data files that are created. data-file-1, data-file-2, ... are the path names (either full or relative to the current working directory) of the model data set files, in chronological order. When the program is finished, a large number of files will have been created that will reside in the current working directory. This is the RIP data that will be accessed by RIP to produce plots._ See Appendix C for a description of how these files are named and the the format of their contents.

RIPDP is flexible in that it processes any variables it encounters in the model output file, even those it is not expecting, and produces files for those variables, using the variable name provided in the model output to create the file name. Any such variables can be plotted with RIP--see the description of the feld keyword in Appendix A.

The "basic|all" option is available only for ripdp_wrf. basic causes ripdp_wrf to process only the basic variables that RIP requires, whereas all causes ripdp_wrf to process all variables encountered (as in ripdp_mm5)._ If all is specified, the discard variable can be used in the ripdp namelist to prevent processing of unwanted variables, as with ripdp_mm5._ However, if basic is specified, the user can request particular other fields (besides the basic fields) to be processed by setting a retain variable in the ripdp namelist instead of the discard variable._ retain is set in the same manner as discard, i.e., you assign it one or more variable names in single quotes separated by commas.

To provide more user control over the processing of data, a namelist can be specified by means of the "-n" option, with namelist-file specifying the path name of the file containing the namelist, on the ripdp_wrf command line. Namelists are a special type of Fortran input structure that is described in Chapter 2.

The namelist file for ripdp_wrf should contain the namelist &userin. Examples of a namelist input files for ripdp_wrfarw and ripdp_wrfnmm, called ripdp_wrfarw_sample.in and ripdp_wrfnmm_sample.in, respectively, are provided in the RIP tar file in the sample_infiles directory. The &userin namelist in that file is shown below, followed by a description of the variables it sets. Each variable has a default value (shown in parentheses), which is the value this variable will take if its specification is omitted from the namelist.

&userin
ptimes=0,-72,1, ptimeunits='h', tacc=90., discard='LANDMASK','H2SO4', iexpandedout=1
&end

 
Note: If you want RIPDP to simply process all times encountered, you can indicate this in one of several ways. If both ptimes and iptimes are omitted from the namelist (and thus retain their default values) or are both assigned their default values, RIPDP will process all encountered times. Or, if the first (or only) value of either ptimes or iptimes is negative, RIPDP will process all encountered times.

Note: With some compilers such as Sun's Fortran 90, when assigning values to an array in a namelist, each array element must be separately referenced with its index in parentheses.  This would apply to the ptimes, iptimes, and discard arrays described above.  Thus, in this situation, the above namelist would appear as

&userin
ptimes(1)=0,ptimes(2)=-72,ptimes(3)=1, ptimeunits='h', tacc=90., discard(1)='LANDMASK',discard(2)='H2SO4', iexpandedout=1
&end

b. Special considerations for running RIPDP for WRF-NMM

The WRF-NMM model has a unique map background and grid structure, both of which introduce special challenges for processing and plotting WRF-NMM data. The map background is what can be referred to as a "stretched rotated cylindrical equidistant", or SRCE, projection. RIPDP and RIP have been made fully capable of handling this projection. The grid staggering in WRF-NMM, however, presents more complications. The staggering pattern is known as the "E-grid", which is essentially a B-grid (as used in MM5) rotated by 45 degrees.

Because of its developmental history with the MM5 model, RIP is inextricably linked with an assumed B-grid staggering system. Therefore, the easiest way to deal with E-grid data is to make it look like B-grid data. This can be done in two ways, either of which the user can choose. In the first method, we define a B-grid in which its mass ("cross or C") points collocate with all the H and V points in the E-grid, and the B-grid's velocity ("dot or D") points are staggered in the usual B-grid way. The RIPDP-created data files retain only the E-grid data, but then when they are ingested into RIP, the E-grid H-point data are transferred directly to overlapping B-grid cross points, and non-overlapping B-grid cross points and all dot points are interpolated from the E-grid's H and V points. This is the best way to retain as much of the exact original data as possible, but effectively doubles the number of horizontal grid points in RIP, which can be undesirable. The second method is to define a completely new B-grid that has no relation to the E-grid points, possibly (or even preferably) including a different map background, but presumably with substantial overlap between the two grids, and a horizontal resolution similar to the effective resolution of the E-grid. The E-grid data is then bilinearly interpolated to the new B-grid in RIPDP and the new B-grid data is then written out to the RIPDP output data files. With this method, the fact that the original data was on the E-grid is completely transparent to the RIP plotting program.

To specify which choice to make, and to define the new map background and grid if choice 2 is made, several additional parameters need to be defined in the &userin namelist. An example of a full &userin namelist for use with ripdp_wrfnmm is shown below:

&userin
ptimes=0,-72,1,ptimeunits='h',tacc=90.,discard='LANDMASK', iinterp=1,dskmcib=50.,miycorsib=100,mjxcorsib=100,nprojib=1, xlatcib=30.,xloncib=-95.,truelat1ib=30.,truelat2ib=48., miyib=500,mjxib=500,yicornib=46.5509,xjcornib=40.0999,dskmib=5.

The additional parameters are described below:

It should be noted that, if iinterp=1, grid points in the new domain that are outside the original E-grid domain will be assigned a "missing value" by RIPDP. RIP (the plotting program) handles "missing value" data inconsistently--some parts of the code are designed to deal with it gracefully, and other parts are not. Therefore, it is best to make sure that the new domain is entirely contained within the original E-grid domain. Unfortunately, there is no easy way to do this. RIPDP does not warn you when your new domain contains points outside the original E-grid. The best way to go about it is by trial and error: define an interpolation domain, run RIPDP, then plot a 2-D dot-point field such as map factor on dot points (feld=dmap) in color contours and see if any points do not get plotted. If any are missing, adjust the parameters for the interpolation domain and try again.

4. The RIP user input file

Once the RIP data has been created with RIPDP, the next step is to prepare the user input file (UIF) for RIP. This file is a text file, which tells RIP what plots you want and how they should be plotted. A sample UIF, called rip_sample.in, is provided in the RIP tar file. This sample can serve as a template for the many UIFs that you will eventually create.

A UIF is divided into two main sections. The first section specifies various general parameters about the set up of RIP, in a namelist format. The second section is the plot specification section, which is used to specify what plots will be generated.

a. The namelist section

Namelists are a special type of Fortran input structure that is described in Chapter 2. The first namelist in the UIF is called &userin. An example of a &userin namelist for RIP, which is also found in the sample UIF rip_sample.in, is shown below, followed by a description of the variables contains. Each variable has a default value (shown in parentheses), which is the value this variable will take if its specification is omitted from the namelist.

&userin

idotitle=1,titlecolor='def.foreground',

ptimes=0,6,12,

ptimeunits='h',tacc=120,timezone=-7,iusdaylightrule=1,

iinittime=1,ifcsttime=1,ivalidtime=1,inearesth=0,

flmin=.09, frmax=.92, fbmin=.10, ftmax=.85,

ntextq=0,ntextcd=0,fcoffset=0.0,idotser=0,

idescriptive=1,icgmsplit=0,maxfld=10,itrajcalc=0,imakev5d=0

&end

Some background on the RIP frame title lines: The standard title at the top of the RIP frame has up to two lines, depending on what information is requested, as described below._ . The first shows and an initial time. The second line shows the forecast hour, and the valid time in both UTC and local time.

Note: If you want RIP to simply plot all times available, you can indicate this in one of several ways. If both ptimes and iptimes are omitted from the namelist (and thus retain their default values) or are both assigned their default values, RIP will plot all available times. Or, if the first (or only) value of either ptimes or iptimes is negative, RIP will plot all available times.

Notes on ntextq and ntextcd:

Note: With some compilers such as Sun's Fortran 90, when assigning values to an array in a namelist, each array element must be separately referenced with its index in parentheses.  This would apply to the ptimes and iptimes arrays described above.  Thus, in this situation, the specification of ptimes in the above sample &userin namelist would appear as

ptimes(1)=0,ptimes(2)=6,ptimes(3)=12,

The second namelist in the UIF is called &trajcalc. This section is ignored by RIP if itrajcalc=0. Trajectory calculation mode and use of the &trajcalc namelist are described in Chapter 6.

b. The plot specification table

The plot specification table (PST) provides all of the user control over particular aspects of individual frames and overlays. The basic structure of the PST is as follows. The first line of the PST is a line of consecutive equal signs. This line, as well as the next two lines, is ignored–they are simply a banner that says that this is the PST. After that are several groups of one or more lines separated by a full line of equal signs. Each group of lines is a frame specification group (FSG), because it describes what will appear in a frame. A frame is defined as one frame of metacode. Each FSG must be ended with a full line of equal signs–that is how RIP knows that it has reached the end of the FSG. (Actually, RIP only looks for four consecutive equal signs, but the equal signs are continued to the end of the line for cosmetic purposes.) Each line within the FSG is a plot specification line (PSL), because it describes what will appear in a plot. A plot is defined as one call to a major plotting routine (e.g. a contour plot, a vector plot, a map background, etc.). Hence, a FSG that has three PSLs in it will result in a frame that has three overlaid plots.

Each PSL contains several plot specification settings (PSSs), of the form

keyword = value [,value,value,...]

where keyword is a 4-character code word that refers to a specific aspect of the plot. Some keywords need one value, some need two, and some need an arbitrary number of values. Keywords that require more than one value should have those values separated by commas. Semicolons must separate all the PSSs within a PSL, but the final PSS in a PSL must have no semicolon after it–this is how RIP identifies the end of the PSL. Any amount of white space (i.e., blanks or tabs) is allowed anywhere in a PSS or PSL, because all white space will be removed after the line is read into RIP. The use of white space can help make your PST more readable. The order of the PSSs in a PSL does not matter, though the common convention is to first specify the feld keyword, then the ptyp keyword, and then other keywords in no particular order. A PSL may be as long as 240 characters, including spaces. However, if you want to keep all your text within the width of your computer screen, then a "greater than" symbol (>) at the end of the line can be used to indicate that the PSL will continue onto the next line. You may continue to the next line as many times as you want for a PSL, but the total length of the PSL, including spaces, cannot exceed 240 characters.

Any line in the PST can be commented out, simply by putting a pound sign (#) anywhere in the line (at the beginning makes the most sense). Note that the pound sign only comments out the line, which is not necessarily the same as the PSL. If the PSL is continued onto another line, both lines must be commented out in order to comment out the entire PSL. A partial PSL will likely cause a painful error in RIP. If all the PSLs in a FSG are commented out, then the line of equal signs at the end of the FSG should also be commented out.

There is a special keyword, incl, which allows the user to tell RIP to insert (at run time) additional information from another file into the plot specification table. This capability makes it easier to repeat large sections of plot specification information in a single input file, or to maintain a library of "canned" plot specifications that can be easily included in different input files. The incl keyword is described in more detail in Appendix A.

Each keyword has associated with it a variable in the program, and this variable may be integer, real, character, or logical. It also may be an array. The keywords that are associated with a real variable expect values that are of Fortran floating-point format. All of the following are examples of valid values:

1, 2, 1., 2., 1.23, 34565, -1e-13, -1.01e+16, 6.52349, -5

The keywords that are associated with an integer variable also expect values that are of Fortran floating point format. That is because they are initially read in as a floating-point number, and then rounded (not truncated) to the nearest integer. Hence, all of the above examples of numbers would also be valid for keywords that are associated with an integer variable (except the 8th number, which would be out of range for a 32-bit integer). The fifth and ninth values would be rounded to 1 and 7, respectively.

The keywords that are associated with a character variable expect values that are character strings. They should NOT be in single quotes, and should also not have any blank characters, commas,