[Tgcmgroup] tgcmproc IDL

[Ben Foster]

Dear tgcm group:

I have put a new version of the tgcmproc IDL processor on the hao 
network, and on the scd machines dave (IBM) and dataproc (SGI).

To set up and run this IDL GUI application, take the following steps:

  1. Add the following directory to your PATH environment variable 
     on the appropriate machine (add in your .cshrc file on that system).

       a. At hao:      /home/tgcm/bin
       b. On dave:     /home/foster/bin
       c. On dataproc: /home/foster/bin

     Then source your .cshrc file, and give the command "rehash".
     There is a "tgcmproc" run script in each of these directories.
     The command "which tgcmproc" should indicate the appropriate
     directory.

  2. Cd to a directory containing the tiegcm or time-gcm netcdf 
     history files you wish to examine. You can rcp these from other 
     machines, or msrcp from the mss. Files currently in use are
     often in the following directories:

       a. At hao:      /vishnu/e/foster/tgcmproc
       b. On dave:     /ptmp/tgcm
       c. On dataproc: /ptmp/tgcm

  3. On dave and dataproc, set your DISPLAY environment variable:
     "setenv DISPLAY mymachine.hao:0". Then on your home workstation,
     give the command "xhost +". This allows dave or dataproc to
     X-display on your home workstation.

  4. Give the command "tgcmproc". This should start an IDL session, 
     and open an instance of the application. You should get a new
     X-window labeled "tgcmproc", with a "File" menu. Open a file
     from this menu, then use the "Plot" menu to make maps or
     longitude slices.  

!-----------------------------------------------------------------------

Features and usage tips:

There are 2 main plot types available from the "Plot" menu: maps and
longitude slices.  Each plot type opens a new window with its own menus. 
You can have as many of these open simultaneously as you need.

1. Maps: lat vs longitude at selected zp pressures.

   a. Cylindrical Equidistant and Polar Stereographic projections.
   b. Select zp pressure and perimeter latitudes via slider widgets.
   c. Animation in time or pressure (from "Animate" menu).
   d. PlotOptions menu offers color tables, and continental outlines.

2. Longitude slices: zp pressure vs latitude at selected longitudes 
   or local times.

   a. Select longitude or local time from slider widgets.
   b. Animate in time (ut), at fixed longitude.
   c. Animate in time (ut), at fixed local time.
   d. Animate in longitude, at fixed ut.
   e. PlotOptions menu offers color tables, and log10 options.


Both maps and lon slices have the following capabilities:

1. Plotting fields from the file that are on either geographic or magnetic 
   grids.

2. Saving postscript or bitmap images (PNG, GIF, BMP, JPEG, TIFF)
   of the current frame.

3. Select Field and ModelTime from menus.

4. This application will read both model history files and f90 tgcmproc
   output netcdf files. In the case of model files, it will "process"
   the fields, i.e., convert from half to full zp levels, change units,
   etc., just like the fortran tgcmproc. If it reads a tgcmproc output
   file, it assumes this processing already took place in the fortran code.

5. FYI, the IDL source code is at the following locations.
   (A copy of this document is at /home/tgcm/tgcmproc/idl/tgcmproc2.announce)

   At hao:      /home/tgcm/tgcmproc/idl
   On dave:     /fs/othrorgs/home0/foster/tgcmproc/idl
   On dataproc: /fs/othrorgs/home0/foster/tgcmproc/idl


!-----------------------------------------------------------------------

Comments and Warnings:

1. Avoid clicking ahead, especially when the cursor is in hourglass mode
   (i.e., intially reading a file, reading a variable from the file,
   loading an animation, etc)

2. You can have only one file open at a time in a single instance of the
   application. However, you can run multiple instances of the application 
   by giving the tgcmproc command at the IDL prompt (the application does
   not block the IDL prompt). This works until you start making animations,
   because the animation widget *does* block the IDL prompt. So start all
   instances of the app you need before you start making animations.

3. Note that when you open a new file, all instances of lons, maps, and
   animate windows are destroyed before opening the new file. 

4. If you are running on an hao workstation with less than 640M of memory,
   the machine may start paging in virtual memory, and become very slow,
   especially after reading several variables. Try running on dave or dataproc,
   and request more memory for your machine!

5. This application is designed to use an 8-bit depth pseudocolor display.
   (it sets device,decomposed=0).
   On the Suns, you can switch from 24-bit to 8-bit with the command:
   "/usr/sbin/m64config -depth 8" 
   After issuing this command, log out and back in again. Then check your
   display with the command "/usr/sbin/m64config -prconf". You can obtain
   information about your current display with the command "xdpyinfo".

6. Since hao is still running idl 5.3, the animation widget is capable
   of saving MPEG movies. However, IDL is having licensing problems with
   MPEG, so this is not available on dave and dataproc, which have higher
   versions of IDL. I am working on alternatives for saving the animations. 

7. If IDL stops execution with a traceback, kill the IDL session (cntrl-d)
   and restart the application with the tgcmproc command. If you can
   reproduce the circumstances that produced the error, please let me know.

8. After exiting the application, you can exit the IDL session with cntrl-d.


This application is a work in progress. Please report problems or bugs 
to me.  I am continuing development with new plot types and options. 
Your suggestions and requests are welcome. Here are a few things on my 
ToDo list:

  a. Provide option to limit x and y axes of both plot types (maps and
      longitude slices).

  b. Provide option to specify min,max of the field to be plotted.

  c. Currently, only raster images are displayed. Provide options for
     contour plots (monochrome or color fill) and contours over the images.

  d. Time-dependent plots (ut on the x-axis, e.g., zp vs ut and lat vs ut).

  e. Velocity vector overlays.

  f. Interpolation to height surfaces.

  g. Some level of customization for plot labeling. 


-----------------------------------------------------------------------
Ben Foster		      	High Altitude Observatory (HAO)
foster@ucar.edu			phone: 303-497-1595  fax: 303-497-1589  
Nat. Center for Atmos. Res.     P.O. Box 3000 Boulder CO 80307 USA
-----------------------------------------------------------------------