HOPS GRIDS Generation Package: HOST: maelstrom.harvard.edu (128.103.2.50) TAR FILES: pub/HOPS/Grids/grids_7.2.tar.Z (212641:995840 bytes) pub/HOPS/Grids/grids.ps.gz (2422796:11270708 bytes) pub/HOPS/Grids/Ex_grids_7.2.tar.gz (1064737:2673664 bytes) VERSION: 7.2 (January 16, 2001) ORIGIN: Harvard University, Cambridge Massachusetts Harvard Ocean Prediction System (HOPS) DEVELOPER: Patrick J. Haley (haley@pacific.harvard.edu) LIBRARIES: (1) NetCDF, version 3.3.1 University Corporation for Atmospheric Research/UNIDATA http://www.unidata.ucar.edu/ (2) GNUmake, version 3.75 Free Software Foundation http://www.gnu.ai.mit.edu/ (3) NCAR Graphics, version 4.0 University Corporation for Atmospheric Research http://www.scd.ucar.edu/ ============ INTRODUCTION ============ This directory contains HOPS's grid generation package. This package sets up User's (longitude,latitude) grid and extracts and manipulates its associated bathymetry. GRIDS has several filters to smooth, manipulate, and condition the bathymetry. It uses, as input, the topography NetCDF files which can be found in directory "pub/HOPS/Atlas". It also sets all relevant parameters for the terrain-following vertical coordinate transformation used in the PE model. The final result is the generation of the GRIDS NetCDF file which is used by some of the HOPS software. For more details, refer to included User's guide. The GRIDS package consists of three programs grids - performs the previously described tasks crs2fne - Utility to aid in the design of collocated sub-domains. extract_grids - Utility to align topography and land masks between collocated nested domains. ============ 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/Grids" and get files: Readme.grids This file. grids_7.2.tar.Z Compressed tar file of the GRIDS package. grids.ps.gz Compressed User's guide postscript file. Ex_grids_7.2.tar.gz Compressed tar file of the GRIDS Examples. To install this package, simply go to the directory in which you want to put the GRIDS package and execute the following commands: zcat grids_7.2.tar.Z | tar -pxvf - gzip -dc Ex_grids_7.2.tar.gz | tar -pxvf - The tar file grids_7.2.tar.Z contains the following files: grids.F crs2fne.F extract_grids.F align_mask.F align_topo.F all_lc.F auto_iface.F blkdat.F c2f_dat.F c2f_write.F cf_blkdat.F cf_exit.F chk_cdf.F chk_lev.F chk_pwndo.F chk_tfile.F cntr_lbl.F comp_fne.F cont_data.F cpmpxy.F cpp_tell.F day_code.F defcdf.F depth.F depth_init.F draw_map.F eqvec.F errio.F f_fz.F fill_map.F filt_step.F flat_top.F gcircle.F get_curr_filt.F get_data.F get_date.F get_dom.F get_ewpt.F get_sigma.F get_slope.F get_vert.F getsquare.F gr_exit.F great_int.F hcf_key.F hcf_stat.F hcntr_lbl.F headln.F heap_sort.F hinit_cpack.F hyb_sys.F ibox_load_vec.F icond_rep.F iinsert.F ilocal_mean.F ilocal_median.F init_cpack.F interface.F least_int.F length.F ll2xy.F massage_topo.F max_sigma.F max_slope.F my_handler.F new_depth.F newton.F no_digit.F opn_tfile.F pe_grid.F plot_cst.F plt_clos.F plt_grid.F plt_hcf.F plt_init.F plt_invalid.F plt_step.F plt_topo.F pos_inq.F prv_depth.F rbox_load_vec.F rcond_rep.F read_grids.F rescale_thick.F rinsert.F rlocal_median.F rmblklines.FF rotangle.F rotparm.F set60dvsr.F set_blank.F set_dash.F set_edge.F set_frame_geo.F set_lltick.F set_space.F set_vgrid.F setllstr.F shap_filt.F sig_fig.F step_lines.F step_sys.F sub_sam2d.F sub_sam_mask.F sup_sam2d.F sup_sam_mask.F top_box.F top_key.F topo_stat.F uv_depth.F var_sigma.F var_top.F vec_read_f.F wrt_lvl.F xg_param.F xy2ll.F bgdomdat.h c2fio.h cntlbl.h crs_dat.h dom.h fne_dat.h gpconst.h gridsio.h gridsparm.h hcfmap.h hstat.h optzc1.h pltncar.h rotate.h search.h smdomdat.h titles.h topmap.h tpmed.h tpstt.h version.h GNUmakefile.alpha GNUmakefile.cray GNUmakefile.iris GNUmakefile.rs6000 GNUmakefile.sun3 GNUmakefile.sun4 GNUmakefile.sun5 UPDATES VMSmakefile.com compile.com crs2fne.in grids.in ============= The Makefiles ============= 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. These GNUmakefiles C-preprocess, compile, and link GRIDS source codes. They have been designed to allow the user to compile the GRIDS source codes in a separate directory from that in which the source codes are located. The GNUmakefiles search 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 (4) the directory specified by the macro NCDIR This provides the user with the flexibility for the following configurations: (1) The user needs only copies of the GNUmakefile, the parameter file "gridsparm.h" and a path to the source codes to produce a version of GRIDS with the appropriate C-preprocessing and compilier options. (2) The user who is modifying GRIDS, 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. ---------------------------------- Makefile Tunable macro definitions ---------------------------------- The User needs to check and modify the following macro definitions in the appropriate makefile before compiling and linking the application code: ARFLAGS flags for the archive utility BIN name of the executable code BINDIR directory path for executable code C2FBIN name for nesting utility executable CPPFLAGS C-preprocessing flags and options FFLAGS flags for the FORTRAN compiler NCDIR directory path for NetCDF include files NGLIB name for an object library containing non-plotting routines PARAMDIR alternate directory path for include files SRCDIR directory path for source codes XTRBIN name for extraction utility executable SRCDIR directory path for source codes -------------------------------- Makefile C-preprocessing Options -------------------------------- The following are the available C-preprocessing options to use in the macro definition CPPFLAGS: aixdate AIX intrinsic date routine (IBM RS6000). craydate Using CRAY time/date intrinsic routines decdate Using DEC time/date intrinsic routines fsmed Filter step topography with integral-weighted median filter fsmen Filter step topography with integral-weighted mean filter ftclip Filter topography by clipping ftmed Filter topography with integral-weighted median filter ftshap Filter topography with Shapiro filter gendbg Generic debugging. Prevents deletion of intermediate files. lnext Use linear extrapolation of topography to edges. noplot Disables NCAR graphics plotting. sundate Using SUN time/date intrinsic routines sunflush Flush output buffers on SUN systems. sunfpe SUN's floating point exception trap ------------------------------- 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 GRIDS 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. (If not necessary on current system, leave blank.) FC The FORTRAN compilier NCARGFC NCAR's script for compiling FORTRAN code with the NCAR graphics libraries. ===================== 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 "gridsparm.h". The User needs to set the following parameters: DIMI Dimension of contour integer work space. DIMM maximum size of the area map work space used by the NCAR plotting package to prevent contour lines from being drawn through the high/low labels. DIMR Dimension of contour real work space. IMT maximum number of points in the x-direction. IJMX maximum number of points in any of the two horizontal dimensions (IJMX=max(IMT,JMT)). JMT maximum number of points in the y-direction. MAX_CL maximum number of contour levels. MXCST Maximum number of points in a coastline. Only important when using the netCDF versions of the GSHHS coastal dataset. MAX_LVL maximum number of vertical model levels. It is recommended to set these values big to avoid recompiling each time, for example: parameter (imt=512, jmt=256, ijmx=512, max_cl=120, mx_lvl=100, & dimm=20*imt*jmt, mxcst=1500000, & dimi = 10000, dimr = 10000) ================== Input Script Files ================== ----- GRIDS ----- There are several parameters that the User needs to determine and specify before running the application code. These parameters are read from standard input. A sample of the input parameter data is provided in script file "grids.in". See User's guide "grids.ps" for more details. ------- crs2fne ------- There are several parameters that the User needs to specify to get a collocated sub-domain definition. Basically, they are the size and location of the desired sub-domain (fine grid) and the name of the GRIDS output netCDF file containing the definition for the large (coarse) grid. IMT_F Number of grid points in x direction. (fine grid) JMT_F Number of grid points in y direction. (fine grid) LAT_F (deg) Latitude of center of grid. (fine grid) LON_F (deg) Longitude of center of grid. (fine grid) GFILE Name of previously defined coarse GRIDS netCDF file. ========= Executing ========= ----- GRIDS ----- To execute the GRIDS program, use the following command UNIX command: grids < grids.in > & grids.log & ------- crs2fne ------- To execute the crs2fne program, use the following command UNIX command: crs2fne < crs2fne.in > & crs2fne.log & Then use the results in crs2fne.log to define a new grids.in for the collocated sub-domain (fine grid). ------------- extract_grids ------------- This is an interactive program. It prompts the user for exactly four pieces of input: (1) the name of the GRIDS netCDF output file containing the definition of the large domain (coarse grid). (2) the name of the GRIDS netCDF output file containing the definition of the collocated sub-domain (fine grid). (3) the direction of extraction (large-to-small or small-to-large) (4) the field(s) to extract (topography, land mask or both) The use of extract_grids is discussed in sections 5.2.3 & 5.3.4. ======== Examples ======== ----------------- Massachusetts Bay ----------------- The tar file "Ex_grids_7.2.tar.gz" contains an example which illustrates how the GRIDS package is used. The Example is in Massachusetts Bay. This is a simple example with no nesting, so only the GRIDS program is used. The GRIDS program is executed twice. In the first execution it extracts the bathymetry from the archive topography NetCDF file "gom_topo.nc" (a Gulf of Maine topography obtained from the US Geologic Survey http://oracle.er.usgs.gov/gomaine/), extract a copy of this file from "pub/HOPS/Atlas" at this site. In the second execution GRIDS applies a (4,1) Shapiro filter, clips the shallowest and deepest depths and applies a median filter. This example includes the following files: GNUmakefile.sun5 makefile used to create the executable. gridsparm.h GRIDS main parameter statement. grids GRIDS SUN Ultra executable. grids_massbay_01.in input script for first execution of GRIDS. grids_massbay_02.in input script for second execution of GRIDS. gulf_cst.dat coastlines/islands data from CIA dataset. grids_massbay.nc output GRIDS NetCDF file. grids_massbay_01.log output echo file from GRIDS first execution. grids_massbay_02.log output echo file from GRIDS second execution. gmeta.01 NCAR's plot file of GRIDS first execution. gmeta.02 NCAR's plot file of GRIDS second execution.