* README.v1.8.doc *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX DESCRIPTION of GrADS *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX The Grid Analysis and Display System (GrADS) is an interactive tool for accessing, manipulating, and displaying data on a variety of computer platforms. GrADS assumes a 4-Dimensional space, (usually longitude, latitude, level, and time). Each input gridded (or station) data set in binary or GRIB format is located within this 4-Dimensional space through a data description file. Ingestion of NetCDF data is available. Mathematical operations may be performed on the data interactively, by entering FORTRAN-like expressions at the command line. Many built-in functions are provided; and users may add their own functions as external routines. Once the data have been accessed and manipulated, they may be displayed using a variety of graphical output techniques, including contours, shading, vectors, scatter plots and geography. Graphics may be output in PostScript. The GrADS scripting language can be used to automate complex multi-step calculations or displays. GrADS can also be run in a batch mode. The scripting language supports flow control, defined variables, and access to GrADS command output. Widgets (buttons and pull down menus) may be drawn that allow a "point and click" GUI between the Grads user and the GrADS scripting language. Users may write their own GrADS functions, e.g., grid interpolation functions, in the computer language of their choice, to generate an expression, which can be accessed via the GrADS display command. Also, Freud or VCS can be used to plot data stored in GrADS-compatible format. * ........................................................................... *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX PLUSES *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX * Quick, interactive access, mathematical manipulation or display of any desired 1-D or 2-D sections or time loops of the latter. * User may customize display options. * Batch mode capbility. * Powerful scripting language. * Generates good qualtiy postscript files. * Interface for GRIB data. * Interfaces for NetCDF-formatted data. * DODS enabled, beginning with version 1.8. * Reads and plots station data. * Has the capability for users to implement their own GUI. * ........................................................................... *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX MINUSES *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX * One-of-a-kind native GrADS data format is supported by a very limited number of packages, (although the netCDF data format is supported by many packages). * GrADS handles only one horizontal grid (i.e., no staggered grids), and one vertical grid per file, even if the input data is written as a netCDF file. Therefore, GrADS has limited ability to handle staggered grid data. A user defined interpolation function must be employed to plot the difference of a variable "var" from two different data sets, which do NOT reside on the same grid. * GrADS lacks a 3-D visualization capability. * ........................................................................... *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX GrADS Executables for running GrADS in linux work station windows or in HPCS ac1, ac2 or lsc1 windows: *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX GrADS version 1.8 executables were installed during January 2002 in /usr/local/grads of the appropriate computer platform, i.e. a linux version for the linux work stations, and an irix 6.5 version for the HPCS ac1, ac2 and lsc1 computer platforms. Thus, which excutable you access depends on what type of window you run GrADS in. The byte swapping option must be included in description files, when running GrADS on your LINUX work station and excluded when running GrADS on UNIX platforms such as the HPCS AC1 or AC2, due to the Endian-ness problem. Similarly, view a GrADS metafile and/or transform it into another file format such as postscript, in an AC window (a work station window), if the metafiles were previously created using the UNIX-based (LINUX-based) GrADS executable. *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX HOW TO INVOKE GrADS *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX *oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo **** Preliminaries **** *oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo The GrADS executable grads is symbollically linked to "gradsdods", a version capable of handling NetCDF input files, programming of GUIs and DODS-enabled. Generally speaking, this is the GrADS executable of choice. To execute the earlier, classic, pre-NetCDF version, invoke gradsc. To execute a version capable of handling input data written in the netCDF format self-descripting format, but not DODS-enabled, invoke gradsnc. To execute a version capable of handling input data written in the hdf format self-descripting format, invoke gradshdf. *oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo Before invoking the current version of GrADS (version 1.8): * 1. Set three environmental variables, GADDIR and GAUDFT and GASCRP. This may be done in your GrADS command window, i.e., the workstation window from which you will run GrADS). However, it is more convenient to set the above environmental variables in your customized ".login-sgi-" dot file, so that they will be automatically set whenever you log in. setenv GADDIR /usr/local/grads/dat setenv GASCRP /usr/local/grads/lib.gs setenv GAUDFT /usr/local/grads/udf/udft GADDIR refers to the directory which contains auxiliary data sets, such as fonts, employed by the grads executable. GAUDFT is the file name of the table of user defined functions. GASCRP is a subdirectory containing several GrADS scripts obtained from GrADS developers. * ........................................................................... * 2. Add the basic GrADS directory and the subdirectory containing the GRADS executables to your path: set path = ($path /usr/local/grads /usr/local/grads/bin) Note: For convenience, reset your path, as shown above, in your customized ".login-linux-" or .login-irix- dot file, so that it will be automatically accessible whenever you log in. Note: Add to your path any subdirectory where you wish to store your own GrADS scripts. * ........................................................................... * 3. Write your input data files in 32 bit ieee byte-stream format, or GRIB format, and create a "description file" (see User's Guide, below); or write your data in the self-documenting netCDF file format. *oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo **** Starting Up a GrADS Session **** *oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo * 1. Type: "grads [cr]" in the GrADS command window, where "[cr]" denotes carriage return or "Enter" key. * 2. Type "[cr]" for landscape; "no" for portrait, when the prompt "Landscape mode? (no for portrait):" appears. A landscape or portrait- shaped GrADS display window will pop up. Click the mouse to secure its position. * 3. Type "open ", to access each binary data file or type "sdfopen " to access each NetCDF data file (GrADS 1.6 or later versions). * 4. Manipulate, display, and or print plots of the data. * 5. To finish the GrADS session, type: "quit". * ........................................................................... *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Hints *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX * Try to avoid repeated transfers of data across the network. * GrADS will run more efficiently, by defining the result of mathematical manipulations (and inputs to the calculations) before displaying them, to circumvent the GrADS I/O and minimize cross-network data transfers. * To build a repetoire of GrADS commands, copy the GrADS script log.gs into the directory GrADS is launched from, and type "run log.gs.doc.txt". An unedited file of GrADS commands you type will be created until you type "stop". * Sign up for GrADS Users Group List Server to receive email on questions and responses concerning GrADS, broadcast by members of the international community of GrADS users, or to pose your own GrADS questions. (For signup instructions, read how_to_join_gradsusr_email_list.doc.txt or browse the www GrADS Home Page http://grads.iges.org/grads. * The features of the GrADS scripting language can be utilized only by writing and running GrADS scripts, and cannot be accessed by typing GrADS commands. ............................................................................. *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Brief Description of Exec and Run Script files *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX * ........................................................................... You can create an exec file as a sequence of GrADS commands, which will be executed sequentially. Up to 9 arguments are allowed. The syntax for executing an exec file is: "exec {optional arguments}". * ........................................................................... You can create GrADS scripts. They allow for variables. Any text between single quotes (' '), e.g., basic GrADS commands is taken literally, whereas any text not inscribed by single quotes is a variable. See grads.doc for further details. But two powerful script commands that can be used ONLY IN SCRIPTS are: "say" and "pull". "say" enables a message to be printed on the screen, whereas "pull" enables users to type in the value of a variable. These two commands are not inscribed by single quotes in run scripts, since they are not GrADS commands. For example, say 'Enter variable name: T, u, v, or q.' pull var say 'var = 'var'.' where what you type for the pull command is inscribed by < >, will produce: Enter variable name: T, u, v, or q. var = T. The GrADS scripting language incorporates several other useful constructs, including if - endif and while - endwhile, etc. The syntax for running a GrADS run script is: run . Incidentally, a sub-directory "optional_scripts" has been reserved for GrADS scripts created by GFDL users such as yourself, which would be useful to the GFDL GrADS community. New contributions will be passed on to the Systems Group, a few times per year. However, these scripts will neither be verified nor officially supported. Users interested in participating should include some documentation within each script. * ........................................................................... *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX User Defined Functions *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX /usr/local/grads/udf/user_defined_function.doc: Explains how to generate user defined functions whose output can be used in GrADS expressions. A table of current user defined functions (see user_defined_function.doc) is located in directory /usr/local/grads/udf/udft. We have included one user define function so far, i.e., regrid2beta. This user defined function allows one to interpolate from one horizontal grid to another. The execuatable, documentation and auxilliary files are located in directory /usr/local/grads/udf/regrid2. Documentation for regrid2, "cd /usr/local/grads/udf/regrid2/regrid2.doc" Note that we shall maintain a single udf table, called /usr/local/grads/udf/udft, for all user defined functions, including regrid2beta, as discussed above, and each user defined function executable will reside in its own, appropriately named sub-directory off of /usr/local/grads/udf. For example regrid2beta resides in the directory /usr/local/grads/udf/regrid2. Currently, regrid2 is the only user-defined file available at GFDL. But other user defined functions may be added later on, if there is sufficient interest amongst GFDL and AOS users. GrADS users at GFDL are encouraged to email Tony.Gordon@noaa.gov, describing any new user defined function,they have created or downloaded, and tested, which they believe to be of general interest to the GrADS community at GFDL. Please include a description and documentation. New contributions will be passed on to the Systems Group, a few times per year. Each new user defined function that is accepted will be stored in its own sub-directory off of /usr/local/grads/udf. However, these udf's will neither be verified nor officially supported. Before attempting to create or use udf's, please be sure to add a "setenv GAUDFT /usr/local/grads/udft" command to your customized .login-sgi- file, as mentioned earlier in this document. * ........................................................................... *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX GrADS script log.gs *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX * This GrADS script is very useful for generating new GrADS scripts. Its purpose is to create a a log of GrADS commands, by typing GrADS commands during an interactive GrADS session, until the command "stop" is encountered. * The log will be saved as a script file called grads.log or another name of your choice. * The GrADS command "rc = write (filename,cmd2)"in the log.gs script will write each command to the file called "filename". A pre-existing file of the same name will be overwritten. The script variable "r" is given the return code (an integer, which is not displayed since no "say result" command immediately follows in the script. * The log file should be edited later to weed out any invalid GrADS commands which the user has typed. * The information within a consecutive pair of single quotation marks is interpreted literally, i.e., does not contain any explicit variables. * Also, commands such as say, pull, if - endif, etc., which are available only in the scripting language and cannot be typed interactively have to be added to the log file by editing it. Similarly, explicit variables must be incorporated by editing the log file. (See documentation on the scripting language to learn about variables and special scripting language commands). * To use log.gs, cp /usr/local/grads/log.gs to the directory where you will run GrADS, or else refer to its explicit path. * ..................................................................... *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Tutorial on GrADS fonts, subscripts and superscripts *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX * ..................................................................... * Below is a brief tutorial to familiarize you in using the fonts * supported by grads version 1.5.1, as well as its subscript- * superscript capability. * ..................................................................... * To see a sampler of the various fonts available under grads version 1.5.1 * appear in a grads graphics window, type the following grads command: run font_sampler.gs * ..................................................................... * The following fonts are supported by grads version 1.5.1: * 0 = helvetica font * 1 = roman font * 2 = italics roman font * 3 = symbols font * 4 = bold helvetica font * 5 = bold roman * To view a complete font table for font type # in a grads graphics window, * type the following grads command: run font.gs # * where the argument # = 0, 1, 2, 3, 4 or 5, run the grads script font.gs. * Type the literal value of #. If you omit the argument, a font table will * be generated for the helvetica font. * For example, run font.gs * or run font.gs 0 * will generate a helvetica font table, while run font.gs 3 * will generate a symbol font table. * Note: the grads scripts font_demo.gs and font.gs are located in * /home/tg/gradsv1.5.1 during test mode, and will be located in * /usr/local/grads, when the new version of grads is officially installed. * Note: As of June 12, 1995, you should run grads in landscape mode to see * a font table. Otherwise, the rightmost portion of the font table will be * truncated. * ..................................................................... * Sample grads commands fonts and sub/superscripts. * You may invoke a change of font, or subscripts and superscripts * in conjunction with grads commands such as * draw title , * draw string <horiz char size> <vert char size> <x pos> <y pos> <string> * draw xlab <xlab> * draw ylab <ylab> * where <title> is the title, <string> is the character string, * <xlab> is the x-axis label, <ylab> is the y-axis label, etc. * To change the font, type a backwards single quote, i.e., `, * followed by 0, 1, 2, 3, 4 or 5 as part of <title>, <string>, <xlab> or * <ylab>: * `0 = change to helvetica font * `1 = change to roman font * `2 = change to italics roman font * `3 = change to symbols font * `4 = change to bold helvetica font * `5 = change to bold roman font * To do subscripts or superscripts or return to normal mode, type a backwards * single quote, i.e., `, followed by b, a or a, respectively: * `b = below (precedes your subscript character string) * `n = return to normal (precedes your normal character string) * `a = above (precedes your superscript character string) * ..................................................................... * Examples * First, suppose that you wish to make use of the new fonts in interactive * mode, without having to write a grads script. * In this case, do not define any variables and remove the single quotes * surrounding the literals. Incorporate the font instructions directly into * the grads command: set display grey white clear * To produce the character string Srefl (Wm-2), in the current font, * where "refl" is a subscript and "-2" is a superscript: * title for an existing contour plot or line plot draw title S`brefl`n (Wm`a-2`n) * y axis label draw ylab Wm`a-2`n * To produce the character string S0 = 1365 Wm-2, in the current font, * (1/2" size, at x=3",y=7"), * where "0" is a subscript and "-2" is a superscript: set strsiz .50 .50 draw string 3 7 S`b0`n = 1365 Wm`a-2`n * To produce the character string 235 deg K, (1/4" size, at x=3",y=4"), * where "235" is written in Roman font, "." is the degree symbol * in symbol font, i.e., font 3, and " K" is written in helvetica: set strsiz .25 .25 draw string 3 4 `1235`3.`0 K * xxxxxxxxxxxxxxxxxxx * Copy and paste the above commands into your grads command window, * to see what effect they have. * Then try to draw your own title or character string, amking use of the fonts * and the grads sub/superscript capability. * ..................................................................... * Next, suppose that you are writing a grads script. * For those unfamiliar with grads scripts, * an "*" in column one indicates a comment, and blank lines are OK. * Also, any valid command or other literals appear within single * quotation marks, whereas anything outside of the single quotes is * regarded as a variable whose value should be defined. * The value of any undefined variable will be the literal name of the * variable. Variable names may contain up to 8 characters (perhaps more). * To produce the above character strings, * first define the variables tit, yl,solcon and temp; * Then remember to enclose literals, including grads commands * in single quotes, while variables including those appering as arguments * in grads commands should be unquoted. tit = 'S`b0`n (Wm`a-2`n)' yl = 'Wm`a-2`n' solcon = 'S`b0`n = 1365 Wm`a-2`n' temp = '`1235`3.`0 K' 'set display grey white' 'clear' 'draw title 'tit 'draw ylab 'yl 'set strsiz .50 .50' 'draw string 3 7 'solcon 'set strsiz .25 .25' 'draw string 3 4 'temp * ..................................................................... * See grads.doc for more information on the grads scripts, as well as the * grads display, string and strsiz commands. * ..................................................................... *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX GrADS ON-LINE Documentation: *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Go to the GrADS Web Site Home Page http://grads.iges.org/grads for on-line documentation or to download hard copy documentation. * ...........................................................................