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

Mark T. Stoelinga
University of Washington

1 December 2006

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. 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. The writing of this version of the RIP Users' Guide coincides with the development of the generalized version (version 4) of RIP by Mark Stoelinga and the NCAR MM5 Group. RIP is an officially supported component of NCAR's MM5 modeling system, and the generalization of vertical coordinate has also been undertaken to make RIP compatible with output from the Weather Research and Forecast Model (WRF), and potentially, 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 CGM file is created, which can be viewed with any one of several different metacode translator applications. 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:

• uses a preprocessing program (called RIPDP) which reads model output, and converts this data into standard RIP format data files that can be ingested by RIP. Two versions of RIPDP are provided: one for output from all components of the MM5 Modeling System, and one for output from the mass-coordinate version of the WRF model. Other versions of RIPDP could be constructed to ingest output from other mesoscale models.
• makes Lambert Conformal, Polar Stereographic, or Mercator map backgrounds, with any standard parallels.
• makes horizontal plots of contours, color-filled contours, vectors, streamlines, or characters.
• makes horizontal plots on model vertical levels, as well as on pressure, height, potential temperature, equivalent potential temperature, or potential vorticity surfaces.
• makes vertical cross sections of contours, color-filled contours, full vectors, or horizontal wind vectors.
• makes vertical cross sections using vertical level index, pressure, log pressure, Exner function, height, potential temperature, equivalent potential temperature, or potential vorticity as the vertical coordinate.
• makes skew-T/log p soundings at points specified as grid coordinates, lat/lon coordinates, or station locations, with options to plot a hodograph or print sounding-derived quantities.
• calculates backward or forward trajectories, including hydrometeor trajectories, and calculates diagnostic quantities along trajectories.
• plots trajectories in plan view or vertical cross sections.
• makes a data set for use in the Vis5D visualization software package
• allows for complete user control over the appearance (color, line style, labeling, etc.) of all aspects of the plots

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 the PSU/NCAR Mesoscale Model ftp site at NCAR. 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:

• CHANGES, a text file that logs changes to the RIP tar file
• Diff/, a directory that contains files with actual differences (generated with "diff") between different releases of RIP Version 3
• Doc/, a directory that contains documentation of RIP, most notably the HTML version of the Users' Guide that you are now reading (ripug.htm).
• Makefile, the top-level make file used to compile and link RIP
• README, a text file containing basic information on running RIP
• color.tbl, a file that contains a table defining the colors you want to have available for RIP plots
• psadilookup.dat, a file that contains "look-up" table data for obtaining temperature on a pseudoadiabat
• ripdp_sample.in, rip_sample.in, and tabdiag_sample.in, sample input files for programs RIPDP, RIP, and TABDIAG
• src/, a directory that contains all of the source code files for RIP, RIPDP, and several other utility programs. Most of these are Fortran 77 source code files with extension .f.  In addition, there are:
• .h and .c files, which are C source code files
• comconst and comvctran, include files that contain common blocks that are used in several routines in RIP
• pointers, an include file that contains pointer declarations used in some of the routines in RIP
• Makefile, a secondary make file used to compile and link RIP
• stationlist, a file containing observing station location information
• tserstn.dat, a sample list of locations for time series output

Also on the MM5 anonymous ftp site, there are a few examples of special map background definition files, of the form xxxx.ascii and xxxx.bin. These are large files, and therefore were not included in the RIP tar file. If you are going to use such files, you should download them (or create your own) and place them in your RIP directory.  The use of these files is discussed further in Appendix A, "Keywords", under the description of the outy keyword.

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, .ascii files, psadilookup.dat) 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.

There are a few important things that you should be aware of if you will be translating your plots to postscript:

• Postscript has no concept of "background color". Hence, regardless of what your index 0 color is, translation to postscript (either mono or color) will result in a blank or white background. If this is a problem, it can be circumvented by using the -simulatebg option on the ctrans command line.
• If you translate to mono postscript, all plotting instructions, regardless of the color used (black, white, red, blue, etc.), will come out black. This means any filled areas, regardless of color or color index used, will waste large amounts of toner when printed out.
• If you translate to color postscript, some monochromatic printers have the nice feature that they convert all colors to halftone gray shades.

Finally, for experienced users of RIP Version 2, you've probably noticed that the implementation of the color table has changed with RIP Version 3, in that the color table is no longer embedded within the UIF. The single color table file in your RIP_ROOT directory should makes life easier, because you'll be assured that any color that you've defined in the past (by adding it to you color.tbl file) will be accessible to you, regardless of how old your UIF is (or the file from which you copied it). Nevertheless, if you prefer to have color tables in your UIFs (between the namelist section and the plot specification table) as was done with RIP 2.0, you can continue to put them there. 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.

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 version of RIPDP for WRF model system output, ripdp_wrf, needs 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.

• Namelists: For some I/O, RIP and RIPDP use a nonstandard feature known as a namelist. A namelist is a Fortran input file structure that is not officially standard to Fortran 77, but which is available in most Fortran 77 compilers. Namelists are placed in text files that are opened and read by the Fortran program. The basic structure of a namelist is, on the first line, the name of the namelist (preceded by an ampersand), and then on subsequent lines a series of "variable = value" constructs, each separated by commas, blank spaces, or a new line. (On some machines, commas are required, so it's safest to always use them.) The final line ends the namelist should contain the single word end preceded by an ampersand. Each variable is an actual variable that is declared in a special namelist statement inside the Fortran program. The variables can be of any type. The value of a character variable should be enclosed in single quotes, although it doesn't have to be if all the characters in the string are alpha-numeric. The value of a logical variable should be ".true." or ".false.". Arrays can be assigned multiple values separated by commas (although it has come to the author's attention that with some compilers such as Sun's Fortran 90, each array element must be separately referenced with its index in parentheses). Here is a general example of a namelist:

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

• System calls: RIP uses the following system calls: getenv (for retrieving the value of a UNIX environment variable from within a program), iargc (for retrieving the number of command line arguments), and getarg (for retrieving command line arguments). These system calls are quite common, and should be available in the f77 and f90 compilers from Cray, Sun, SGI, DEC, and IBM.

There are also calls (commented out in the standard release) to the system routine flush (for flushing the standard output buffer, so that the progress of the program can be easily monitored when standard output is being sent to a file). These were commented out because they caused problems on some compilers, but you are free to reinstate them.

• An early version of RIP required the changing of parameter values in the code and recompiling of the program for each different sized domain that was to be analyzed. In versions 2 and 3, this complication has been eliminated. However, in order to do so, the program has been set up in a manner that requires adjustable dimensioning of local (non-argument) arrays in subroutine driver and a few other routines in RIP, and in subroutine process in RIPDP. In other words, in subroutine driver, for example, several arrays that are not in the subroutine argument list are dimensioned with integer variables that are in the argument list. This is technically illegal in Fortran 77, but many compilers support it because it makes dynamic memory allocation possible. It is standard in Fortran 90. Therefore, if you do not have a Fortran 90 compiler, or your Fortran 77 compiler doesn't support adjustable dimensioning of local (non-argument) arrays, you will (unfortunately) have to make some minor changes to subroutines driver, qgomg, and saweli in RIP, and process in RIPDP, and recompile RIPDP and RIP (i.e. re-run make) for each different size domain that you analyze. See the instructions at the top of subroutine process in RIPDP, and at the top of subroutine driver in RIP, if you need to do this.
• Versions 2 and 3 of RIP use Cray pointers. This is nonstandard Fortran 77, but is supported by most Fortran 77 and Fortran 90 compilers.

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 and ripdp_wrf. Although these are two separate prgrams (one for use with MM5 model system output and one for use with WRF mass-coordinate model output), they serve the same purpose, and will be referred to collectively as ripdp.

a. Running RIPDP

The program has the following usage:

ripdp_mm5 [-n namelist-file] model-data-set-name data-file-1 data-file-2 data-file-3 ...

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

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.

To provide more user control over the processing of the 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. Namelists are a special type of Fortran input structure that is described in chapter 2.

The namelist file for ripdp should contain the namelist &userin. An example of a namelist input file for ripdp, called ripdp_sample.in, is provided in the RIP tar file. 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

• ptimes (real array, def.=9.0E+09), ptimeunits (character variable, def.='h'): ptimes specifies the desired times for ripdp to process. A value of 9.0E+09 indicates to RIPDP that you are using iptimes (see below) instead of ptimes to specify desired times. You can specify particular times to be processed, separated by commas. The units are determined by the value of ptimeunits, which can be either 'h' (for hours), 'm' (for minutes), or 's' (for seconds). You can also specify a series of times in the form A,-B,C, which is interpreted as "times from hour A to hour B, every C hours" (assuming ptimeunits='h'). Thus, in the example above, you want RIPDP to process times from hour 0 through hour 72, every hour (assuming they are encountered in the data). Individual times can be intermixed with series specifications. Thus, ptimes=0,1,3,-18,3,24 would cause RIPDP to process data at hours 0,1,3,6,9,12,15,18, and 24 (assuming those times are encountered).
• iptimes (not shown in the above example, integer array, def.=99999999): This is an integer array that also specifies desired times for RIPDP to process, but in the form of 8-digit "mdate" times (i.e. YYMMDDHH). A value of 99999999 indicates to RIPDP that you are using ptimes (see above) instead of iptimes to specify desired times. Either one or the other of ptimes or iptimes can be used, but not both. ptimeunits has no effect on the meaning of the values given for iptimes. iptimes can also include series specifications. For example, iptimes=99063012,99063018,-99070103,3,99070112 would cause RIPDP to process data at times 99063012, 99063018, 99063021, 99070100, 99070103, and 99070112.

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.

• tacc (real variable, def.=1.0): This specifies a time tolerance, in seconds, for the values assigned to ptimes or iptimes. In other words, any times encountered in the model output that are within tacc seconds of one of the times specified in ptimes or iptimes will be processed.
• discard (character array, def.=' '): This specifies the names of variables that, if encountered in the model data file, will not be processed. The default value (blank) implies that all encountered fields should be processed. Do not discard any of the basic variables, such as temperature, winds, water vapor, pressure perturbation, etc. If you do, you will run into trouble when you attempt to run RIP with your data set.  It is also important to note that the names assigned to the discard variable are compared against the variable names in the model output metadata. Therefore, you should be careful to assign names to discard as they appear in the model output metadata, NOT as they appear at the ends of the the names of the RIP data files. One thing to be particularly careful about is the use of blanks versus underscores. Variable names in the model output metadata may contain blanks. When RIP uses these names to build RIP data file names for unexpected variables, it converts blanks to underscores. For example, the MM5 output variable "SOIL T 6" at hour 12 will result in the creation of a RIP data file called something like mycase_012.00000_SOIL_T_6. If you want to discard "SOIL T 6", you should use discard='SOIL T 6', not discard='SOIL_T_6'.
• iexpandedout (integer variable, def.=0): This integer flag is relevant only to TERRAIN or REGRID output in the MM5V3 system. If the output from one of these two programs is on an expanded domain, iexpandedout determines whether the expanded domain will be processed (1) or the standard (unexpanded) domain will be processed (0).

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

Additional capabilities of ripdp_wrf:

ripdp_wrf permits additional control over the fields that get processed. On the command line, after model-data-set-name, the user should specify either basic or all. 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.

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.

• idotitle (integer variable, def.=1) and title (not shown above, character variable, def.= 'auto'): These control the first part of the first title line. If idotitle=1 and title='auto', you'll get automatically generated information on the data set name (i.e., the root part of the RIP data file names for the data set being plotted) and the UIF file name (excluding the .in extension). If you set title to something else, that string will get used for the first part of the first title line instead of the automatically generated information. If idotitle=0, no title will be printed.
• titlecolor (character variable, def.='def.foreground'): This specifies the color to use for the text in the title line(s). It should be chosen from the available colors listed in the utility file color.tbl, described in chapter 2.
• iinittime (integer variable, def.=1): If this flag is set to 1, the initial date and time (in UTC) will be printed in one of the two title lines.
• ifcsttime (integer variable, def.=1): If this flag is set to 1, the forecast lead time (in hours) will be printed in one of the two title lines.
• ivalidtime (integer variable, def.=1): If this flag is set to 1, the valid date and time (in both UTC and local time) will be printed in one of the two title lines.
• inearesth (integer, def.=0): This flag allows you to have the hour portion of the initial and valid time be specified with two digits, rounded to the nearest hour, rather than the standard 4-digit HHMM specification.
• timezone (real variable, def: -7.0): This specifies the offset from Greenwich time (UTC) for the local time zone, and is required for the correct display of local time specification of the valid time. RIP will recognize familiar time zones of N. America (-8,-7,-6,-5) and show, for example, "MST" or "EDT". For unfamiliar time zones, it will show "LST" or "LDT".
• iusdaylightrule (integer variable, def.=1): This flag determines whether the U.S. daylight saving rule (i.e., daylight saving in effect between 1st Sunday in April and last Sunday in October) should be applied (1) or not (0) in displaying the local time specification of valid time.
• ptimes (real array, def.=9.0E+09), ptimeunits (character variable, def.='h'): ptimes specifies the desired times for RIP to plot. A value of 9.0E+09 indicates to RIP that you are using iptimes (see below) instead of ptimes to specify desired times. You can specify particular times to be plotted, separated by commas. The units are determined by the value of ptimeunits, which can be either 'h' (for hours), 'm' (for minutes), or 's' (for seconds). You can also specify a series of times in the form A,-B,C, which is interpreted as "times from hour A to hour B, every C hours" (assuming ptimeunits='h'). Individual times can be intermixed with series specifications. Thus, ptimes=0,1,3,-18,3,24 would cause RIP to plot data at hours 0,1,3,6,9,12,15,18, and 24 (assuming those times are available).
• iptimes (not shown in the above example, integer array, def.=99999999): This is an integer array that also specifies desired times for RIP to plot, but in the form of 8-digit "mdate" times (i.e. YYMMDDHH). A value of 99999999 indicates to RIP that you are using ptimes (see above) instead of iptimes to specify desired times. Either one or the other of ptimes or iptimes can be used, but not both. ptimeunits has no effect on the meaning of the values given for iptimes. iptimes can also include series specifications. For example, iptimes=99063012,99063018,-99070103,3,99070112 would cause RIP to plot data at times 99063012, 99063018, 99063021, 99070100, 99070103, and 99070112.

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.

• tacc (real variable, def.=1.0): This specifies a time tolerance, in seconds, for the values assigned to ptimes or iptimes. In other words, any available times in the data that are within tacc seconds of one of the times specified in ptimes or iptimes will be plotted. This value should be increased if, for example, your "hourly" output is not exactly on the hour. It should be decreased if you have saved consecutive time steps and need to pin point one of those time steps.
• flmin, frmax, fbmin, and ftmax (real variables, def.=.05,.95,.10,.90, respectively): These specify the left frame limit, the right frame limit, the bottom frame limit, and the top frame limit, respectively. The size of all plots will be adjusted to be the maximum that can fit in this box. The box is defined in terms of the fractional coordinate system, i.e. all four values should be between 0.0 and 1.0
• ntextq (integer variable, def.=0): This is the text quality specifier ( 0=high; 1=medium; 2=low ).
• ntextcd (integer variable, def.=0): This is the text font specifier [ 0=complex (Times); 1=duplex (Helvetica) ].

Notes on ntextq and ntextcd:

1. ntextcd only applies to high quality characters.
2. Low and medium quality characters look identical except that the medium quality zero is unslashed.
3. Medium quality characters are drawn with polylines so their size is independent of the local translator being used. The same is not true of low quality characters, which use the GKS primitive character set, whose size can vary from one system to another.
4. Any messages that involve units will always use high quality, in order to make use of superscripting for exponents.
• fcoffset (real variable, def.=0.0): This is an optional parameter you can use to "tell" RIP that you consider the start of the forecast to be different from what is indicated by the forecast time recorded in the model output. It serves the same purpose as the now defunct mdatebf, but is specified as a relative time (in hours, + or -) rather than an absolute YYMMDDHH format, so it is more useful for automated real-time applications. A non-zero fcoffset causes RIP to adjust the displayed initial and forecast times to match what you consider to be the beginning of the forecast. Examples: fcoffset=12 means you consider hour 12 in the model output to be the beginning of the true forecast (you might use this for a run with a 12-h dynamic initialization period); fcoffset=-12 means you consider model output time 0 to be the true forecast hour 12 (you might use this if a high-resolution domain is initialized from the hour-12 output from a low-resolution domain).
• idotser (integer variable, def.=0): This flag means "do time series". By setting this flag to "1", you can print out time series of any RIP variable at any station location in the model domain. In order to do this, you must also do two other things. First, you must create a simple text file with a list of locations, one per line. Locations are specified in the same manner as cross section endpoints. See the description of keyword crsa in Appendix A for more information on how to specify locations. The file must be called tserstn.dat and should reside in your current working directory. A sample version of this file is provided in the RIP tar file. Then, you must request plots of the desired fields using the plot specification table. Any field for which ptyp=hc is specified will be included in the time series that is created. You can plot all the fields in one frame or in separate frames. You can request any of the RIP vertical coordinates, and multiple levels, just as you would if you were generating plots. In fact, when you run RIP, it will generate the plots asked for, but in addition, it will create an ascii file with time series data at the requested stations for any fields that were plotted with ptyp=hc. The name of the ascii file that is created will be rip-execution-name.tser.
• idescriptive (integer variable, def.=1): This flag can be set to 1 to turn on the printing of more descriptive plot titles instead of the traditional, more cryptic and technical titles.
• icgmsplit (integer variable, def.=0): Setting this to 1 causes each time level of plots to be in a separate metacode file. A value of 0 causes all times to be in a single metacode file.
• maxfld (integer variable, def.=10): This is a parameter that is used to reserve memory for RIP. It is typically set between 10 and 15, depending on how much scratch space is needed to calculate some diagnostic fields, and how many fields are plotted in a single frame. If it is set too low, RIP will simply tell you to increase it and re-run the program.
• itrajcalc (integer variable, def.=0): This is a switch which turns on (1) or off (0) trajectory calculation mode. Whenever you are making plots (even trajectory plots), it should be zero. It should only be set to 1 when you are calculating trajectories. See chapter 6 for more details.
• imakev5d (integer variable, def.=0): This is a switch which turns on (1) or off (0) the Vis5D data set creation mode. Whenever you are making plots, it should be zero. It should only be set to 1 when you are producing Vis5D data. See chapter 7 for more details.
• rip_root (not shown in above example, character variable, def.='/dev/null'): If for some reason RIP cannot access the path name that is stored in your UNIX environment variable RIP_ROOT (specifying where your RIP utility files are located), or you want to over-ride the path name specified in RIP_ROOT for a particular execution of RIP, you can specify a path name in the variable rip_root in the &userin namelist in your UIF. The default value of '/dev/null' causes RIP to try to access the path name from the environment variable RIP_ROOT, instead of trying to over-ride it.

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, are 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. All the PSSs within a PSL must be separated by semicolons, 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, or semicolons in them.

The keywords that are associated with a logical variable should not have any value. They are set as .FALSE. by default, and simply the fact that the keyword appears will cause the associated variable to be set to .TRUE..

The keywords that are associated with an array (of any type) may expect more than one value. In this case, the values should be separated by commas, as mentioned above.

As an example, here is a typical PSL:

feld= uuu,vvv; ptyp=hv; vcor =p; levs=1000.,850,700, 500.; vmax=15; colr=>
sky.blue; nmsg; smth= 4

In this example, feld is a keyword that has two character values, ptyp has one character value, vcor has one character value, levs has four real values, vmax has one real value, colr has one character value, nmsg is a logical flag that will cause the associated logical variable to be set to .true., and smth has one integer value. Note the continuation character (>) at the end of the first line, indicating that the PSL continues onto the next line. There should be no semicolon at the end of the last PSS. Also in this example, a somewhat sloppy placement of blank spaces was purposefully done to demonstrate that blanks or tabs can be harmlessly placed anywhere in the PSL.

All the keywords are set to a default value prior to the reading of the plot specification table. With regard to the default setting of keywords, there are two basic types of keywords: those that "remember" their values, and those that "forget" their values. The type that remembers its value (which will subsequently be referred to as type R) is set to its default value only at the outset, and then it simply retains its value from one PSL to the next (and even from one FSG to the next) unless it is explicitly changed by a PSS. The type that forgets its value (which will subsequently be referred to as type F) is reset to its default value after every PSL. Type R keywords are primarily those that deal with location (e.g. the subdomain for horizontal plots, the vertical coordinate and levels for horizontal plots, cross section end points, etc.).

This chapter has described the basic rules to follow in creating the PST. Appendix A provides a description of all of the available keywords, in alphabetical order.

5. Running RIP

Each execution of RIP requires three basic things: a RIP executable, a model data set and a user input file (UIF). Assuming you have followed the procedures outlined in the previous chapters, you should have all of these. The UIF should have a name of the form rip-execution-name.in, where rip-execution-name is a name that uniquely defines the UIF and the set of plots it will generate. The syntax for the executable, rip, is as follows:

rip [-f] model-data-set-name rip-execution-name

In the above, model-data-set-name is the same model-data-set-name that was used in creating the RIP data set with the program ripdp. model-data-set-name may also include a path name relative to the directory you are working in, if the data files are not in your present working directory. rip-execution-name is the unique name for this RIP execution, and it also defines the name of the UIF that RIP will look for. The intended syntax is to exclude the ".in" extension in rip-execution-name. However, if you include it by mistake, RIP will recognize it and proceed without trouble. The –f option causes the standard output (i.e., the textual print out) from RIP to be written to a file called rip-execution-name.out. Without the –f option, the standard output is sent to the screen. The standard output from RIP is a somewhat cryptic sequence of messages that shows what is happening in the program execution.

As RIP executes, it creates either a single metacode file or a series of metacode files, depending on whether or not icgmsplit was set to 0 or 1 in the &userin namelist. If only one file was requested, the name of that metacode file is rip-execution-name.cgm. If separate files were requested for each plot time, they are named rip-execution-name.cgmA, rip-execution-name.cgmB, etc.

A common arrangement is to work in a directory that you've set up for a particular data set, with your UIFs and plot files (".cgm" files) in that directory, and a subdirectory called data that contains the large number of RIP data files. So, for example, if your data set was called "superstorm" and you had an input file called sfcfields.in, you would invoke RIP in the following manner:

rip data/superstorm sfcfields

RIP prints to information to the screen as it runs, and then after it has completed execution, you will see a new file in your present working directory, sfcfields.cgm. This is a metacode file containing the plots you requested.

You could also have the standard print out sent to the file sfcfields.out and run RIP in the background:

rip -f data/superstorm sfcfields &

In this case, after RIP has completed execution, you will see two new files in your present working directory. The file sfcfields.out contains print out from the RIP execution. The file sfcfields.cgm is a metacode file containing the plots you requested.

Although the metacode file has a .cgm suffix, it is not a standard computer graphics metacode (CGM) file. It is an NCAR CGM file that is created by the NCAR Graphics plotting package. It can be viewed with any of the standard NCAR CGM translators, such as ctrans, ictrans, or idt.

6. Calculating and plotting trajectories

Because trajectories are a unique feature of RIP and require special instructions to create, this chapter is devoted to a general explanation of the trajectory calculating and plotting utility. RIP deals with trajectories in two separate steps, each of which requires a separate execution of the program.

a. Trajectory calculation

The first step is trajectory calculation, which is controlled exclusively through the namelist. No plots are generated in a trajectory calculation run. In order to run RIP in trajectory calculation mode, the variable itrajcalc must be set to 1 in the &userin namelist. All other variables in the &userin part of the namelist are ignored. The &trajcalc part of the namelist contains all the information necessary to set up the trajectory calculation run. The following is a description of the variables that need to be set in the &trajcalc section:

• rtim: the release time (in forecast hours) for the trajectories.
• ctim: the completion time (in forecast hours) for the trajectories.

Note: the direction of the trajectory calculation (forward or backward) is determined by rtim and ctim. If rtim<ctim, trajectories are forward. If rtim>ctim, trajectories are backward.

• dtfile: the time increment (in seconds) between data files.
• dttraj: the time step (in seconds) for trajectory calculation. If this is set to a smaller value than dtfile, then velocity data are linearly interpolated in time to the trajectory time steps. Believe it or not, this actually does improve the accuracy of the trajectories. For hourly data, a ten minute (600 s) trajectory time step is often used.
• vctraj: the vertical coordinate of values specified for zktraj. vctraj is specified as a single character in single quotes:

‘s’: zktraj values are model vertical level indices
‘p’: zktraj values are pressure values, in mb
‘z’: zktraj values are height values, in km
‘m’: zktraj values are temperature values, in ºC
‘t’: zktraj values are potential temperature values, in K
‘e’: zktraj values are equivalent potential temperature values, in K

• ihydrometeor: a flag which, if set to 1, causes the trajectory calculation algorithm to use the hydrometeor fall speed (an average fall speed weighted by the mixing ratios of the different precipitation types) instead of the vertical air velocity. The purpose of this flag is to produce hydrometeor trajectories instead of air parcel trajectories.
• xjtraj,yitraj: real arrays contain