VERSION 3 OF GRAPH PROGRAM (release 3-7)
(updated December 23, 2004)

This is the main directory of GRAPH program in MM5 modeling system 
Version 3. Everything a user needs to run the Graph program,
except for NCAR Graphics libraries, is contained in this directory.

Graph requires NCAR Graphics to run. NCAR Graphics is a licensed 
software, but part of it has become free. GRAPH only requires this
part of the NCAR Graphics to run.
For information on NCAR Graphics, please visit

    http://ngwww.ucar.edu/info/pricing.html

This version of Graph may be run on Cray, unix workstations, and
PC running Linux.

All fortran source code is located in directory src/. 

For bug fixes, please read file CHANGES.
For actual diff files, please see directory Diff.

For questions, please send emails to mesouser@ucar.edu

-----------------------------------------------------

What is in V3 GRAPH?

The major difference between this release and V2 is that
we have changed the MM5 internal data format, and the date 
representation in MM5 modeling system from 8-digit MDATE (YYMMDDHH)
to either 13 or 16 or 19 character string in the form of
CCYY-MM-DD_HH:MM:SS (the header actually carries 24 character
string date with .ffff at the end). This version of Graph can
also plot output data that contain land-surface model variables.

-----------------------------------------------------

***************************************************************
Also see the online self-tutorial at
http://www2.mmm.ucar.edu/mm5/mm5v3/tutorial/teachyourself.html
***************************************************************

=======================
NOTES FOR RUNNING GRAPH 
=======================

To run GRAPH on Cray or workstation, one needs to access the following files
from the mesouser directory:

cp /fs/othrorgs/home0/mesouser/MM5V3/GRAPH.TAR.gz .

Or obtain the tar file from NCAR's anonymous ftp site:

ftp://ftp.ucar.edu/mesouser/MM5V3/GRAPH.TAR.gz

Uncompress (or gunzip) and untar the file. You will find the following files:

CHANGES
Makefile
README
Templates/
g_color.tbl
g_defaults.nml
g_map.tbl
g_plots.tbl
graph.csh
src/

and the src directory contains all the graph source fortran and include files.

Take the following steps to compile and run graph:

1. Set environment variable NCARG_ROOT, either in .cshrc file to type it
   before you compile and run GRAPH:

   setenv NCARG_ROOT /usr/local/ncarg (or other directory name where NCAR
                                       Graphics is installed on your machine)

2. If your dataset dimensions are greater than 200x200x40, first edit src/data.incl,
   and src/scratch.incl to increase the dimensions.

3. Type 'make' in the top directory to create graph executable.

4. Edit g_plots.tbl to select fields, units and contour interval to be plotted. 
   If you don't know the unit for a field, use ?. If you don't know what contour
   interval is appropriate, you can use 0 - the NCAR Graphics will select an
   reasonable contour interval for the plot.
   You can also edit other g_* tables or namelist file g_defaults.nml, if necessary.

   For information how to modify g_plots.tbl file to obtain different plots,
   native coordinate plot, interpolated plots, skew-T plots or cross sections,
   please see the Graph chapter in the online Tutorial Notes.

5. Running graph by typing 

   ./graph.csh 1 1 mm5-modeling-system-file-name

6. The output from Graph job is a plot file called gmeta. Use NCAR Graphics viewing
   utility idt to look at the plots: idt gmeta


Notes:

1) This version of Graph works with either 13- or 16- or 19-character
date representation. The usage is the following: if you use 13-character
date representation, the number after BY in the top line of g_plots.tbl
is in hour, e.g. 

TIME LEVELS: FROM 1993-03-13_00 TO 1993-03-13_12 BY 6

If you use 16-character date representation, the number after BY is in minutes:
e.g.,

TIME LEVELS: FROM 1993-03-13_00:00 TO 1993-03-13_12:00 BY 360

If you use 19-character date representation, the number after BY is in seconds:
e.g.,

TIME LEVELS: FROM 1993-03-13_00:00:00 TO 1993-03-13_12:00:00 BY 10800

The code only works for Version 3 MM5 data.

2) If you are running on NCAR/SCD's Cray, and your dataset dimensions are
less than 200x200x40, you don't need to compile but copy an existing graph
executable from /fs/othrorgs/home0/mesouser/MM5V3/graph-run.tar.Z. 
This file contains all table files and shell script and executable you 
need to run GRAPH without recompilation.

3) On a Cray, you can also use graph.deck for running batch (as well as
interactive) job. The deck can be obtained by typing 'make graph.deck',
Or copying it from ~mesouser/MM5V3/graph.deck.cray.

4) To run GRAPH on a workstation, your input data need to be in IEEE format.
If you have run the model on a workstation, the data would be in IEEE format.
If the data are created on a Cray, use the conversion program under 
/fs/othrorgs/home0/mesouser/MM5V3/Util/ieeev3.csh on the Cray
to convert the data to IEEE format. To use ieeev3.csh, type

   ieeev3.csh mmout-file

5) To run GRAPH on Cray with a 32-bit IEEE dataset, edit graph.csh. Search
for the string 'assign', and replace 'ln -s' line with 'assign' line in each
of the three instances.

6) If one has a bigger dataset (when IX and JX exceed 200, or KX exceeds 40), 
one needs to modify the following two files in the src directory and recompile:

scratch.incl
data.incl

7) If you are interested in using US county maps or higher resolution China
coast as your map background, you can copy them from 
/fs/othrorgs/home0/mesouser/MM5V2/Graph, or obtain them via anonymous ftp
under /mesouser/MM5V2/Graph. The file names are us_county.ascii and china.ascii.
The *.ascii files contain high resolution coastline information 
(china.ascii) or US county border information. To use them, 
name the one you want to use with the name 'hipone.ascii', and 
set the last variable in 'g_defaults.nml', IHIRES = 1.

8) The output gmeta and gmeta.split1 are usually identical, unless you
have chosen to split the gmeta file by typing 

./graph.csh x 1 mm5-modeling-system-file-name

where x is greater or equal to 2. Then you x number of gmeta.splitn files.

9) To obtain a single listing of the source code, you will have to edit
a section near the bottom of the Makefile. Search for 'code' inside Makefile,
and change the definition for CPP and CPPFLAGS to those appropriate to your 
machine type. Then type

   make code
   mv src/graph.f graph.listing ; cat src/*.f >> graph.listing

-----------------------------------------------

IBM users:

- Graph now runs on IBM.

-----------------------------------------------


Additional fields that may be plotted by GRAPH:

From TERRAIN:
-------------------------------------------------------------------------------
PLOT | FIELD | UNITS |  CONTOUR | SMOOTH || OVERLAY | UNITS |  CONTOUR | SMOOTH
T/F  |       |       | INTERVAL | PASSES ||  FIELD  |       | INTERVAL | PASSES
-----|-------|-------|----------|--------||---------|-------|----------|-------
 T   |VEGFRC01|  %   |   10.    |   0    ||         |       |          |
...
 T   |VEGFRC12|  %   |   10.    |   0    ||         |       |          |
 T   |TEMPGRD|   K   |    5.    |   0    ||         |       |          |
 T   |SOILINDX|category|   2.   |   0    ||         |       |          |
 T   |LATITCRS|degree|   10.    |   0    ||         |       |          |
 T   |LONGICRS|degree|   10.    |   0    ||         |       |          |
 T   |LATITDOT|degree|   10.    |   0    ||         |       |          |
 T   |LONGIDOT|degree|   10.    |   0    ||         |       |          |
 T   |CORIOLIS| 1/s  |    0.    |   0    ||         |       |          |

From REGRID (if you SOIL Vtable, and get these fields):

 T   |SEAICE |category|   0.    |   0    ||         |       |          |
 T   | WEASD |category|   0.    |   0    ||         |       |          |
 T   |SOILT010|  K    |   4.    |   0    ||         |       |          |
 T   |SOILT200|  K    |   4.    |   0    ||         |       |          |
 T   |SOILM010|fraction|  .2    |   0    ||         |       |          |
 T   |SOILM200|fraction|  .2    |   0    ||         |       |          |

From MM5:

1) If using ISOIL=2 option:

 T   |SOIL T 1|  K    |   4.    |   0    ||         |       |          |
 T   |SOIL T 2|  K    |   4.    |   0    ||         |       |          |
 T   |SOIL T 3|  K    |   4.    |   0    ||         |       |          |
 T   |SOIL T 4|  K    |   4.    |   0    ||         |       |          |
 T   |SOIL M 1|fraction|  .2    |   0    ||         |       |          |
 T   |SOIL M 2|fraction|  .2    |   0    ||         |       |          |
 T   |SOIL M 3|fraction|  .2    |   0    ||         |       |          |
 T   |SOIL M 4|fraction|  .2    |   0    ||         |       |          |
 T   |SOIL W 1|m^3/m^3|   .2    |   0    ||         |       |          |
 T   |SOIL W 2|m^3/m^3|   .2    |   0    ||         |       |          |
 T   |SOIL W 3|m^3/m^3|   .2    |   0    ||         |       |          |
 T   |SOIL W 4|m^3/m^3|   .2    |   0    ||         |       |          |
 T   |SFCRNOFF|  mm   |   2.    |   0    ||         |       |          |
 T   |UGDRNOFF|  mm   |   2.    |   0    ||         |       |          |
 T   |CANOPYM |  m    |   2.    |   0    ||         |       |          |
 T   |SNOWH   |  m    |  0.001  |   0    ||         |       |          |
 T   |SEAICE |category|   0.    |   0    ||         |       |          |
 T   |ALB    |fraction|   0.    |   0    ||         |       |          |
 T   |ALBSNOMX|  %    |  10.    |   0    ||         |       |          |

2) If using IBLTYP=4 (ETA), or 5 (MRF) option:

 T   |T2M    |  C    |    2.    |   0    ||         |       |          |
 T   |TD2M   |  C    |    2.    |   0    ||         |       |          |
 T   |TDD2M  |  C    |    2.    |   0    ||         |       |          |
 T   |T2     |  C    |    2.    |   0    ||         |       |          |
 T   |Q2     |  g/kg |    2.    |   0    ||         |       |          |
 T   |U10    |  m/s  |    5.    |   0    ||         |       |          |
 T   |V10    |  m/s  |    5.    |   0    ||         |       |          |
 T   |WIND10M|  m/s  |    5.    |   0    ||  BARB10M|  m/s  |    1.    |    0
 T   |WIND10M|  m/s  |    5     |   0    ||  VECT10M|  m/s  |    1.    |    0
 T   |VESL10M|  m/s  |    5.    |   0    ||         |       |          |

 Here, T2,T2M:  2 m temperature
       Q2:      2 m mixing ratio
       TD2M:    2 m dew point temp
       TDD2M:   2 m dew point temp depression
       WIND10M: 10 m wind speed
       BARB10M: 10 m wind barb
       VECT10M: 10 m wind vector
       VESL10M: 10 m streamline

3) If using FRAD >= 2:

 T   |SWOUT  |  W/m^2|   50.    |   0    ||         |       |          |
 T   |LWOUT  |  W/m^2|   50.    |   0    ||         |       |          |

 Here, SWOUT: top outgoing shortwave radiation
       LWOUT: top outgoing longwave radiation

4) If using PX PBL (IBLTYP=7):

 T   |M-O LENG| m    |    0.    |   0    ||         |       |          |
 T   |NET RAD|  W/m^2|   50.    |   0    ||         |       |          |
 T   |GRNFLX |  W/m^2|   50.    |   0    ||         |       |          |
 T   |ALBEDO |fraction|   .2    |   0    ||         |       |          |
 T   |VEGFRG |fraction|   .2    |   0    ||         |       |          |
 T   |LAI    |area/arae|  0.    |   0    ||         |       |          |
 T   |RA     |  s/m  |    0.    |   0    ||         |       |          |
 T   |RS     |  s/m  |    0.    |   0    ||         |       |          |
 T   |ZNT    |   m   |    1.    |   0    ||         |       |          |
 T   |ISLTYP |category|   0.    |   0    ||         |       |          |