HOPS Plotting Package: HOST: maelstrom.harvard.edu (128.103.2.50) TAR FILES: pub/HOPS/Plot/pltpack_3.5.tar.Z (310670:1233408 bytes) pub/HOPS/Plot/pltdat.tar.Z (154915:417792 bytes) pub/HOPS/Plot/palette.tar.Z (11026:49152 bytes) VERSION: 3.5 (January 5, 2000) ORIGIN: Harvard University, Cambridge Massachusetts Harvard Ocean Prediction System (HOPS) DEVELOPERS: Patrick J. Haley Jr. (haley@pacific.harvard.edu) Carlos J. Lozano (lozano@pacific.harvard.edu) LIBRARIES: (1) NCAR Graphics, version 3.01 University Corporation for Atmospheric Research http://www.scd.ucar.edu/ (2) NetCDF, version 2.3.3 University Corporation for Atmospheric Research/UNIDATA http://www.unidata.ucar.edu/ (3) GNUmake version 3.63 Free Software Foundation http://www.gnu.ai.mit.edu/ ============ INTRODUCTION ============ This directory contains the plotting package for HOPS. The HOPS data is stored in NetCDF format. This package uses NCAR's GKS utilities. This plotting package has five executable programs: (1) cnt_ncar horizontal contours, noncolor version. input script: pe_cnt.in or qg_cnt.in (2) ccnt_ncar horizontal contours, color version. input script: pe_ccnt.in or qg_ccnt.in (3) ccntmd_ncar horizontal contours, color version, multiple domains. input script: ccntmd_ncar.in (4) sec_ncar cross-section contours, noncolor version. input script: pe_sec.in or qg_sec.in (5) csec_ncar cross-section contours, color version. input script: pe_csec.in or qg_csec.in The prefixes "pe" and "qg" in these script file names indicate the type of field classification to use: either PE or QG field IDs. See files "pefldid.txt" and "qgfldid.txt" for the current field ID definitions. For convinience, these IDs are repeated at the bottom of these input script files. ============ Installation ============ This package is available over the INTERNET via anonymous FTP from maelstrom.harvard.edu (128.103.2.50). When connected, you will be in the FTP directory. To obtain this package, go to the directory "pub/HOPS/Plot" and get files: Readme.plot This file. pltpack_3.5.tar.Z Compressed tar file of the plotting package. pltdat.tar.Z Compressed tar file containing some coastline files and contour interval files that are used by this plotting package. palette.tar.Z Compressed tar file containing various color palettes that are used when plotting in color. To install this package, simply go to the directory in which you want to put the plotting programs and execute the following commands: zcat pltpack_3.5.tar.Z | tar -pxvf - zcat pltdat.tar.Z | tar -pxvf - zcat palette.tar.Z | tar -pxvf - The files in "pltdat.tar.Z" will be extracted in sub-directory "../data" whereas the files in "palette.tar.Z" will be extracted in sub-directory "../palette". The tar file plt_3.5.tar.Z contains the following files: ccnt_ncar.F ccntmd_ncar.F cnt_ncar.F csec_ncar.F sec_ncar.F all_lc.F areafill.F areamask.F arrow.F assem_unit.F barlab.F bes1d.F bes2d.F bes2de.F bilin.F blkdat.F book.F box.F caldate.F cell.F clrbox.F cmast_seal.F cnt_frame.F cntcolor.F cntint.F cntpack.F colorbar.F colram.F cpmpxy2d.F cpmpxz2d.F datestr.F day_code.F depth_lab.F dombox.F draw_line.F draw_user.F drawcl.F exitus.F external.F extrap.F fdiag.F fld_type.F flddif.F fldnam2id.F gcircle.F get_2dpos.F get_3dpos.F get_cdf2dat.F get_cdf3dat.F get_date.F get_ewpt.F get_pe2dat.F get_pe3dat.F get_pltday.F get_qg2dat.F get_qg3dat.F get_scoor.F gksinit.F great_int.F hbackground.F headln.F id2fldnam.F interp32.F intrpindx.F landmask.F length.F lintrp.F lintrp_sp.F ll2xy.F lnblk.F mapeod.F maptitles.F mskscl.F my_handler.F ncvget.F ncvget1.F opencdf.F pltvec.F psi2dynh.F readpal.F readtopo.F rmblklines.FF rotparm.F sac.F sea_elev.F sec_axis.F sec_frame.F set_units.F setcolpal.F sig_fig.F smooth_under.F smoother.F spline.F splint.F svan.F svel.F time_indx.F vbackground.F vecmag.F vel_nt.F velocity.F veritas.F vernum.F viewport.F what_flds.F xsection.F xtr_exp.F xtr_prefix.F xtr_units.F xy2ll.F book.h cdefs.h cntwkspa.h colpal.h domdat.h fdiagn.h fldpos.h fmask.h hybrid.h inpcdf.h maxdimen.h ndimen.h param.h pconst.h pefldid.h pltfld.h pltio.h pltlab.h pltncar.h qgfldid.h scales.h secpos.h veritas.h version.h zdat.h GNUmakefile.alpha GNUmakefile.cray GNUmakefile.iris GNUmakefile.rs6000 GNUmakefile.sun3 GNUmakefile.sun4 GNUmakefile.sun5 UPDATES VMSmakefile.com ccntmd_ncar.in compile.com pe_ccnt.in pe_cnt.in pe_csec.in pe_sec.in pefldid.txt qg_ccnt.in qg_cnt.in qg_csec.in qg_sec.in qgfldid.txt ============ The Makefile ============ Currently, there are seven different GNUmakefiles for seven different computer architectures: GNUmakefile.alpha GNUmakefile.cray GNUmakefile.iris GNUmakefile.rs6000 GNUmakefile.sun3 GNUmakefile.sun4 GNUmakefile.sun5 These makefiles are written for GNU Make, version 3.75 Free Software Foundation (617) 876-3296 675 Mass Ave. gnu@prep.ai.mit.edu Cambridge, MA 02139, USA http://www.gnu.ai.mit.edu/ They are NOT compatible with the standard UNIX Make. The GNU Makefiles have been designed to allow the user to compile the plotting source codes in a separate directory from that in which the source codes are located. The makefile searches for the code segments in the following alternate paths: source code: (1) the directory containing the GNUmakefile. (2) the directory specified by the macro SRCDIR include files: (1) the directory containing the GNUmakefile. (2) the directory specified by the macro PARAMDIR (3) the directory specified by the macro SRCDIR This provides the user with the flexibility for the following configurations: (1) The user needs only copies of this GNUmakefile, the parameter file "param.h" and a path to the source codes to produce a version of the plotting codes with the appropriate C-preprocessing and compilier options. (2) The user who is modifying the the plotting codes, can isolate those routines actually being changed with a copy of this GNUmakefile in a sub-directory. For VAX/VMS systems, two scripts are provided for C-preprocessing and compiling: VMSmakefile.com (driver script) compile.com These are simple scripts which assume everything is in one directory. They have not been tested in years, use with caution. ------------------------------------- GNUmakefile Tunable macro definitions ------------------------------------- The User needs to check and modify the following macro definitions in the appropriate GNUmakefile before compiling and linking the application code: ARFLAGS flags to the archive utility. BINDIR directory path for the executable code. CCNTBIN name for color horizontal contouring package CCNTMDBIN name for multiple domain version of CCNTBIN CNTBIN name for black & white horizontal contouring package CPPFLAGS C-preprocessing flags and options. CSECBIN name for color vertical contouring package FFLAGS flags to the fortran compiler. NCDIR directory path for NetCDF include files NGLIB name for an object library containing non-plotting routines PARAMDIR directory path for the include files. SECBIN name for black & white vertical contouring package SRCDIR directory path for the source code. ----------------------------------- GNUmakefile C-preprocessing Options ----------------------------------- The following C-preprocessing options are available and specified in macro definition CPPFLAGS: aixdate AIX intrinsic date routine (IBM RS6000). cmast Draw CMAST logo to right of header crap. craydate CRAY's intrinsic date routines. decdate DEC's intrinsic date routines. gendbg Generic Debugging: preserves intermediate files rmdocinc Remove documentation of include files. saclant Draw SACLANT logo to right of header crap. sundate SUN's intrinsic date routine. sunfpe SUN's floating point exception trap. medchr Use NCAR's medium quality character set. lowchr Use NCAR's low quality character set. natounc Print "NATO Unclassified" in upper left and lower right blckndwht Replace colors with "sensible" gray scales. whitelines Draw color separating contour lines in white. big_head Larger arrow heads cjtopo CJL's re-averaging of model topography diffsta Use different symbols for different data types. mediumfont Increase font sizes of some items no_xtrp Prevent averaging of filled points to fill active nodes no_cjl Testing simpler bes2d pe_xtrp Use PE pressure gradient extrapolation routine cnst_xtrp Use constant extrapolation in vertical pfjl_vper Use VPER for VMIN. ------------------------------- GNUmakefile Installation Issues ------------------------------- A number of internal macros are defined for the system commands used by the GNU makefiles. These will generally only have to be defined once, the first time the user installs the plotting package on a new system. RMBLKLINES The name given to executable code (provided with this package) to remove blank lines from the pre-processed code. This is provided only to avoid possible conflicts. SHELL The shell to be used by the makefile. RM The remove command. ECHO The echo command. LIB The netCDF library CPP The C Pre-Processor. AR The archive utility RANLIB Utility to convert archives to random libraries FC The FORTRAN compilier NCARFC NCAR's script for compiling FORTRAN codes with NCAR graphics. ===================== Compiling and Linking ===================== Once that the software has been installed and the Makefile has been selected and customized, the User needs to attend the following steps to compile and link the application code: (1) Customize the include parameter file "param.h". The User needs to set the following parameters: NH maximum number of horizontal points (product of x- and y-directions). NK maximum number of vertical levels (both for data and for vertical interpolation storage.) NMSK maximum number of points for storage array MASK. NV maximum number of volume points (product of x-, y-, and z-directions). NX maximum number of points in any of the two horizontal dimensions (NX=max(IM,JM)). It is recommended to set these values big, to avoid recompiling each time, for example: parameter (nh=80000,nk=10000,nmsk=100000,nv=500000,nx=10000) ================= Input Script File ================= There are several parameters that the User needs to determine and specify before running any of the plotting programs. These parameters are read from standard input. -------------------- Horizontal Contours: -------------------- For example, in order to run program "ccnt_ncar", the User needs to prescribe the following paremeters in input script "pe_ccnt.in" or "qg_ccnt.in": Card 1: IYEAR,YDAY Year (integer) and year-day (real) used to time stamp each plotted field. For example, if the input NetCDF file is a forecast file from PE or QG models, these values will the year and year-day that it assigned to forecast day zero. Set YDAY to a negative if no time stamp is desired. Card 2: PLTITLE(1) First plot header title (80 character string). Card 3: PLTITLE(2) Second plot header title (80 character string). Card 4: PLTITLE(3) Third plot header title (80 character string). Card 5: PLTITLE(4) Fourth plot header title (80 character string). If NFIELD>1 or NLEVELS>1, this title is over-written internally, and set to the field time-stamp. Card 6: CLASS1 Field ID classification to use in primary NetCDF file: [1] PE classification. [2] QG classification. Card 7: NFIELDS Number of fields to plot. Card 8: FLDID() ID of the field(s) to plot. NFIELDS IDs are expected here. Card 9: NLEVELS Number of field depth levels to plot. Card 10: FLDLEV() Field depth level to plot. NLEVELS values are expected here. If a negative value is entered, the field is interpolated to a depth of |FLDLEV|. Card 11: FRSTD First time of the time-series (in day units) to plot (real). If the input NetCDF file contains forecast fields, this value is in model days, for example, model day 0.0. However, if the input NetCDF file was generated by programs other than PE or QG models, this value is usually a modifiy Julian Day. Card 12: LASTD Last time of the time-series (in day units) to plot (real). Set LASTD to a large value, said 99999, to plot all the times found, starting from FRSTD. Card 13: DSKIP Plot each requested field every other DSKIP (real) days. Set DSKIP to zero or negative value, if the data are to be plotted at their own time frequency. If so, the User still needs to provide the values of FRSTD and LASTD described above. Card 14: PMIN Field minimum value for color palette. If PMIN=0.0 and PMAX=0.0, these programs would set PMIN internally to the field actual minimum value. Use this parameter to tune the color bar to the desired values. Card 15: PMIN Field maximum value for color palette. If PMAX=0.0 and PMIN=0.0, these programs would set PMAX internally to the field actual maximum value. Use this parameter to tune the color bar to the desired values. Card 16: ICNT Switch which activates the drawing of contours lines between the color bands: [0] no. [1] yes. Card 17: VSCLE Vector arrow length scale. If VSCLE=0.0, this scale is determined internally. Usually, it is the maximum vector magnitude associated with a fix value of plotter address units. Card 18: VLAT Latitude of the point where the vector arrow scale, if applicable, is to be drawn (south values are negative). Card 19: VLON Longitude of the point where the vector arrow scale, if applicable, is to be drawn (south values are negative). Card 20: IREF Switch to active the plotting of secondary or reference field: [0] No secondary or reference field to plot. [1] Plot field overlay from primary (Card 40) file. [2] Plot field overlay from secondary (Card 41) file. [3] Primary - Secondary file (field subtraction). [4] Day0 - DayN (field subtraction). Card 21: CLASS2 Field ID classification to use in secondary NetCDF file: [1] PE classification. [2] QG classification. Card 22: IDOVER ID of overlay field identification. This parameter is only used where IREF=1 or IREF=2. Card 23: LEVOVER Overlay field depth level to plot. Set LEVOVER=0, if the level to overlay is the same as the currente level in FLDLEV (described in Card 10). Card 24: RMIN Overlay field minimum value to consider. If RMIN=0.0 and RMAX=0.0, these programs would set RMIN internally to the overlay field actual minimum value. Card 25: RMAX Overlay field maximum value to consider. If RMAX=0.0 and RMIN=0.0, these programs would set RMAX internally to the overlay field actual minimum value. Card 26: IGRID Desired longitude/latitude map grid spacing (degrees, (integer). Card 27: IPROJ Map projection: [1] cylindrical equidistant. [2] Mercator. [3] Lambert conical. Card 28: LMSK Switch to activate color masking of land and islands: [0] no color masking. [1] dark brown (RGB=0.25,0.16,0.0). [2] brown (RGB=0.65,0.16,0.16). [3] tan (RGB=0.86,0.58,0.44). Card 29: NPAGE Number of plots per page. Currently, only 1, 2, or 4 plots per page are allowed. Card 30: PLTLOGO Logical (T/F) switch to activate the drawing of the Harvard Logo. Card 31: WRTHDR Logical (T/F) switch used to write out the plot header titles described in Cards 2-5. Card 32: WRTBLAB Logical (T/F) switch to write out the plot bottom title. If NFIELDS>1 or NLEVELS>1, the bottom title is the name and depth of the plotted field. Otherwise, the bottom title is the field time-stamp. Card 33: WRTRANG Logical (T/F) switch to write out the plotted data range values and, if applicable, and if the field is a scalar, to write out the contour interval. Card 34: WRTFNAM Logical (T/F) switch to write out input primary NetCDF file name label. Card 35: WRTDATE Logical (T/F) switch to write out current execution date/time label. Card 36: PBLAT,PTLAT Latitudes of the bottom and top map edges (real; south values are negative). Card 37: PLLON,PRLON Longitudes of the left and right map edges (real; west values are negative). Card 38: FNAME(1) Color palette input file name. Card 39: FNAME(2) Contour parameters input file name. Card 40: FNAME(3) Primary input data NetCDF file name. Card 41: FNAME(4) Secondary input data NetCDF file name. Card 42: CST Character switch (y/n or Y/N) to draw the coastlines and island data provided in Card 43. Card 43: FNAME(5) Coastlines and island input data file name. Card 44: BTH Character switch (y/n or Y/N) to draw isobath data provided in Card 45. Card 45: FNAME(6) Isobath data input file name. Card 46: GEO Character switch (y/n or Y/N) to draw GEOSAT or other track data provided in Card 47. Card 47: FNAME(7) Geosat or other track data input file name. Card 48: TRK Character switch (y/n or Y/N) to draw Lagrangian trajectory or hydrographic station from data provided in Card 49. Card 49: FNAME(8) Lagrangian tracjectoris or hydrographic stations input data file name. Card 50: RNG Character switch (y/n or Y/N) to write ring and other feature labels from dat provided in Card 51. Card 51: FNAME(9) Ring and other features input data file name. The input script to run the noncolor program "cnt_ncar" is similar to the above description, except that input Cards 14, 15, 16, 28, and 38 are omitted in files "pe_cnt.in" or "qg_cnt.in". The input script for the multiple domain, color contouring program, "ccntmd_ncar.in" is simply a list of "pe_ccnt.in" and/or "qg_ccnt.in" input scripts. The program CCNTMD_NCAR simply reads each input script and processes it as CCNT_NCAR. ------------------ Vertical Sections: ------------------ For example, in order to run program "csec_ncar", the User needs to prescribe the following paremeters in input script "pe_csec.in" or "qg_csec.in": Card 1: IYEAR,YDAY Year (integer) and year-day (real) used to time stamp each plotted field. For example, if the input NetCDF file is a forecast file from PE or QG models, these values will the year and year-day that it assigned to forecast day zero. Set YDAY to a negative if no time stamp is desired. Card 2: PLTITLE(1) First plot header title (80 character string). Card 3: PLTITLE(2) Second plot header title (80 character string). Card 4: PLTITLE(3) Third plot header title (80 character string). Card 5: PLTITLE(4) Fourth plot header title (80 character string). If NFIELD>1 or NLEVELS>1, this title is over-written internally, and set to the field time-stamp. Card 6: CLASS1 Field ID classification to use in primary NetCDF file: [1] PE classification. [2] QG classification. Card 7: NFIELDS Number of fields to plot. Card 8: FLDID() ID of the field(s) to plot. NFIELDS IDs are expected here. Card 9: FRSTD First time of the time-series (in day units) to plot (real). If the input NetCDF file contains forecast fields, this value is in model days, for example, model day 0.0. However, if the input NetCDF file was generated by programs other than PE or QG models, this value is usually a modifiy Julian Day. Card 10: LASTD Last time of the time-series (in day units) to plot. Set LASTD to a large value, said 99999, to plot all the times of the time-series found, starting from FRSTD. Card 11: DSKIP Plot each requested field every other DSKIP (real) days. Set DSKIP to zero or negative value, if the data are to be plotted at their own time frequency. If so, the User still needs to provide the values of FRSTD and LASTD described above. Card 12: SLON1 Starting section longitude (degrees, west values are negative). Card 13: SLAT1 Starting section latitude (degrees, south values are negative). Card 14: SLON2 Ending section longitude (degrees, west values are negative). Card 15: SLAT2 Ending section latitude (degrees, south values are negative). Card 16: DELS Section longitude/latitude grid spacing (degrees) used during interpolation. A 16-point Bessel interpolation is used to extract the section defined by the line between points (SLON1,SLAT1) and (SLON2,SLAT2) at DELS resolution. Card 17: SZTOP Shallowest section depth to consider (meters). Card 18: SZBOT Deepest section depth to consider (meters). Card 19: KMS Number of refiment section levels between SZTOP and SZBOT used during section extraction via interpolation. The intepolation scheme is that specified in VINTRP. Card 20: VINTRP Vertical interpolation: [0] linear. [1] cubic splines. Card 21: PMIN Field minimum value for color palette. If PMIN=0.0 and PMAX=0.0, these programs would set PMIN internally to the field actual minimum value. Use this parameter to tune the color bar to the desired values. Card 22: PMAX Field maximum value for color palette. If PMAX=0.0 and PMIN=0.0, these programs would set PMAX internally to the field actual maximum value. Use this parameter to tune the color bar to the desired values. Card 23: ICNT Switch which activates the drawing of contours lines between the color bands: [0] no. [1] yes. Card 24: IREF Switch to active the plotting of secondary or reference field: [0] No secondary or reference field to plot. [1] Plot field overlay from primary (Card 40) file. [2] Plot field overlay from secondary (Card 41) file. [3] Primary - Secondary file (field subtraction). [4] Day0 - DayN (field subtraction). Card 25: CLASS2 Field ID classification to use in secondary NetCDF file: [1] PE classification. [2] QG classification. Card 26: IDOVER ID of overlay field identification. This parameter is only used where IREF=1 or IREF=2. Card 27: RMIN Overlay field minimum value to consider. If RMIN=0.0 and RMAX=0.0, these programs would set RMIN internally to the overlay field actual minimum value. Card 28: RMAX Overlay field maximum value to consider. If RMAX=0.0 and RMIN=0.0, these programs would set RMAX internally to the overlay field actual minimum value. Card 29: NPAGE Number of plots per page. Currently, only 1, 2, or 4 plots per page are allow. Card 30: IFILL Switch to activate masking below the water column: [0] no, [1] yes. Card 31: ITOPO Type of provided bathymetry to use for masking (Card 42) [0] none [1] model [2] raw [3] target. Card 32: PLTLOGO Logical (T/F) switch to activate the drawing of the Harvard Logo. Card 33: WRTHDR Logical (T/F) switch to write out the plot header titles described in Cards 2-5. Card 34: WRTBLAB Logical (T/F) switch to write out the plot bottom title. If NFIELDS>1 or NLEVELS>1, the bottom title is the name and depth of the plotted field. Otherwise, the bottom title is the field time-stamp. Card 35: WRTRANG Logical (T/F) switch to write out the plotted data range values and, if applicable and the field is a scalar, the contour interval. Card 36: WRTFNAM Logical (T/F) switch to write out input primary NetCDF file name label. Card 37: WRTDATE Logical (T/F) switch to write out current execution date/time label. Card 38: FNAME(1) Color palette input file name. Card 39: FNAME(2) Contour parameters input file name. Card 40: FNAME(3) Primary data input NetCDF file name. Card 41: FNAME(4) Secondary data input NetCDF file name. Card 42: FNAME(5) GRIDS NetCDF file name for bottom topography. The input script to run the noncolor program "sec_ncar" is similar to the above description, except that input Cards 21, 22, 23, and 38 are omitted in files "pe_sec.in" or "qg_sec.in". =================================== Coastline and Contour Interval data =================================== The coastline file data is from the CIA database. All the coastline segments have been concatenated to form a long and continuous line in a such way that LAND is to the right when looking from the position of the first point toward the second point of the line. The data is an ASCII file with two columns containing the latitude and the longitude of the points. A longitude and latitude value of 999.0000 is used to indicate "pen-up", that is, to separate coastal segments from islands. West logitudes and south latitudes are negative. The following coastlines files are included in tar file "pltdat.tar": gap_cst.dat Iceland and Faeroes Islands. gulf_cst.dat East coast of North America. med_cst.dat Mediterranean Sea. The contour interval file is used by the plotting package to get the contour interval of each fields at every level and the parameters associated with the drawing of arrows. See the bottom of these files for more documentation. It is recommended to create one contour interval file for each working geographical area. The following contour interval files are included in tar file "pltdat.tar": plot_pe.dat parameters for fields with PE ID. plot_qg.dat parameters for fields with QG ID. ============== Color Palettes ============== The color palette file is very simple ASCII file containing the colors for the background (usually white), foreground (usually black), and NCL color bands. The color bands are specified in term of R,G,B triplets. The User can modify this files or create their own color palette file. See documentation at the bottom of each palette file for more information. The following color palette files are included in tar file "palette.tar": emed1.pal.black 20 colors, black background, white foreground emed1.pal.white 20 colors, white background, black foreground grey1.pal.white 20 greys, white background, black foreground grey2.pal.white 20 greys, white background, black foreground gs1.pal.black 20 colors, black background, white foreground gs1.pal.white 20 colors, white background, black foreground gs2.pal.white 20 colors, white background, black foreground gs3.pal.white 20 colors, white background, black foreground ncar1.pal 14 colors, black background, white foreground topo1.pal 32 colors, black background, white foreground topo2.pal 25 colors, black background, white foreground