HOPS PE Land/Sea Mask (PE_MASK) Program: HOST: maelstrom.harvard.edu (128.103.2.50) TAR FILES: pub/HOPS/PE_mask/pemask_4.1.tar.Z (103411:423424 bytes) pub/HOPS/PE_mask/Ex_mat_pemask_4.1.tar.gz (544669:1881088 bytes) pub/HOPS/PE_mask/Ex_for_pemask_4.1.tar.gz (464043:3356672 bytes) VERSION: 4.1 (August 3, 2000) ORIGIN: Harvard University, Cambridge Massachusetts Harvard Ocean Prediction System (HOPS) DEVELOPERS: Patrick J. Haley (haley@pacific.harvard.edu) Carlos J. Lozano (lozano@pacific.harvard.edu) LIBRARIES: (1) NetCDF, version 2.3.2 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) NetCDF Toolbox, pick for compatibility with MATLAB Charles Denham http://crusty.er.usgs.gov/~cdenham GRAPHICS: MATLAB, The Math Works, Inc. High-Performance Numeric Computation and Visualization Software. (Proprietary Software) Version 4.2 or 5 http://www.mathworks.com/ ============ INTRODUCTION ============ This directory contains HOPS's Land/Sea mask package for the PE model. The program PE_MASK appends/modifies the Land/Sea mask data to an existing GRIDS NetCDF file. For more information about GRIDS NetCDF see file: pub/HOPS/Grids/Readme.grids The Land/Sea data is first computed from the raw bathymetry contained in the GRIDS NetCDF by specifying a transition isobath (say zero meters) between Land and Sea. The mask data is determined at the tracer points (LANDT) and other mask data are derived from it. Recall that the PE model has a staggered B-grid, so momentum and tracer variables are located differently. The Land/Sea mask at the velocity points, in addition, includes a delimiter for the coastal boundary (LANDV=1). This is to facilitate the coastal segment extraction and, in the future, it can be used for setting special boundary conditions on momentum. The Land/Sea mask data consist of the following variables: NCSEG actual number of coastal segments (integer scalar). LCSEG maximum length found (number of points) for coastal segments (integer scalar). NISLE actual number of islands (integer scalar). LENCOAST length of each coastal segment (integer vector of size NCSEG). ICOAST coastal segments x-index coordinate (integer matrix of size LCSEG x NCSEG). JCOAST coastal segments y-index coordinate (integer matrix of size LCSEG x NCSEG). LANDT Land/Sea mask at the tracer points (integer matrix of size TLON x TLAT): LANDT=0 -> land point. LANDT=1 -> sea point. LANDV Land/Sea mask at the velocity points (integer matrix of size VLON x VLAT): LANDV=0 -> land point. LANDV=1 -> boundary (coastline) point. LANDV=2 -> sea point. ISIS starting x-index coordinate of islands box (integer vector of size ISLAND). IEIS ending x-index coordinate of islands box (integer vector of size ISLAND). JSIS starting y-index coordinate of islands box (integer vector of size ISLAND). JEIS ending y-index coordinate of islands box (integer vector of size ISLAND). If the above variables are not found in the provided GRIDS NetCDF, PE_MASK will define and write them. Contrarily, if the above variables already exist in the provided GRIDS NetCDF file, PE_MASK will over-write their values with the new ones. In order to allow multiple executions of the PE_MASK package, the NetCDF dimensions for the above variables are over-estimated since they are fixed when the dimension is first defined (see NetCDF User's Guide, page 65). The dimensions associated with the above variables are: NCSEG maximum number of coastal segments. LCSEG maximum number of points per coastal segment. ISLAND maximum number of islands. This package will ask the user for the values of these dimensions when they are defined for the first time. The maximum and default values for these dimensions are printed inside brackets and they are: NCSEG=20, LCSEG=2000, and ISLAND=20. The PE_MASK package is an interactive one. It includes several FORTRAN routines and MATLAB M-files; both the FORTRAN and MATLAB routines perform the same task. The MATLAB routines have the advantage that the mask data can be determined graphically and it is faster and not so tedious as the FORTRAN program. **************************************************************** *** If MATLAB is available, the MATLAB version of PE_mask is *** *** highly recommended over the FORTRAN version. *** **************************************************************** The FORTRAN program will create the following ASCII files that can be used for setting the desired Land/Sea mask: T_mask.wrk working Land/Sea mask at the tracer points. T_mask.dat final Land/Sea mask at the tracer points. V_mask.dat final Land/Sea mask at the velocity points. ismask.dat Land/Boundary/Sea mask at the velocity points used to visualize the coastal segments. The User can print the "T_mask.wrk" file so it can determine which points are need to be modified. If there are many points that need to be modified, then it is recommended to enter those points into an ASCII file (for example, "flip.dat") which can be read by this program. If so, enter only one coordinate index pair (I,J) per line. The example below, will illustrate how this is done. ============ 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/PE_mask" and get files: Readme.mask This file. pemask_4.1.tar.Z Compressed tar file of the PE_MASK package. Ex_for_pemask_4.1.tar.gz Compressed tar file of the PE_MASK Examples. Ex_mat_pemask_4.1.tar.gz Compressed tar file of the PE_MASK Examples, MATLAB version. To install this package, simply go to the directory in which you want to put the PE_MASK package and execute the following commands: zcat pemask_4.1.tar.Z | tar -pxvf - gzip -dc Ex_for_pemask_4.1.tar.gz | tar -pxvf - gzip -dc Ex_mat_pemask_4.1.tar.gz | tar -pxvf - The tar file pemask_4.1.tar.Z contains the following files: pe_mask.F blkdat.F clean_bndy.F cst_seg.F day_code.F edt_mask.F exitus.F find_st.F get_date.F init_ilist.F ins_ilist.F length.F lnblk.F load_bndy.F load_coast.F my_handler.F nxt_bpt.F pe_seaseg.F prt_mask.F read_grids.F rem_ilist.F rmblklines.FF set_mask.F valid_st.F write_mask.F xtr_cst.F cstmsk.h param.h version.h GNUmakefile.alpha GNUmakefile.cray GNUmakefile.iris GNUmakefile.rs6000 GNUmakefile.sun3 GNUmakefile.sun4 GNUmakefile.sun5 UPDATES VMSmakefile.com compile.com pe_mask.m Contents.m add_cst_xy.m clean_mask.m clmsk_itr.m coastline.m date_stamp.m day_code.m draw_cstp.m get_ewpt.m get_hand.m get_point.m get_states.m init_mask.m ll2xy.m med_filt2D.m pe_seaseg.m pemask_uifn.m pemsk_hnd.m pemsk_ind.m plot_cst_xy.m pltmask.m put_states.m radchk.m rcoastline.m read_mask.m rotparm.m set_mask.m v_mask.m write_mask.m xtr_box.m xtr_seg.m xy2ll.m ============ 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 PE_MASK 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 (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 this GNUmakefile, the parameter file "param.h" and a path to the source codes to produce a version of PE_MASK with the appropriate C-preprocessing and compiler options. (2) The user who is modifying the PE_MASK code, 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: BIN name of the executable code. BINDIR directory path for the executable code. CPPFLAGS C-preprocessing flags and options. FFLAGS flags to the fortran compiler. NCDIR directory path for NetCDF include files PARAMDIR alternate directory path for the include files. SRCDIR directory path for the source code. ----------------------------------- GNUmakefile 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 CRAY's intrinsic date routine. decdate DEC's VMS intrinsic date routine. gendbg Generic Debugging: Preserves intermediate files sundate SUN's intrinsic date routine. sunfpe enable 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 PE_MASK 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. FC The FORTRAN compiler ===================== 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: MAXVAR maximum number of variables in GRIDS NetCDF file. MCSEG maximum number of coastal segments. MISLE maximum number of islands in the basin. MPSEG maximum number of points per coastal segment. NFPTS maximum number of points to flip during editing. NP maximum number of horizontal points. STDINP standard input logical unit. STDOUT standard output logical unit. It is recommended to set these values big to avoid recompiling each time, for example: parameter (maxvar=150,mcseg=20,misle=20,mpseg=2000,nfpts=10000, * np=100000,stdinp=5,stdout=6) ========= Executing ========= To execute the PE_MASK FORTRAN program, use the following UNIX command: pe_mask Then the User will be asked interactively to enter all the necessary information. The file "pe_mask.log" in the example below shows a typical running session with the FORTRAN program. To execute the PE_MASK MATLAB program, use the following command after invoking MATLAB: pe_mask Again, the User will be asked interactively to enter all the necessary information. The file "pe_mask.log" in the example below shows a typical running session with the MATLAB program. Before starting the MATLAB session, it is necessary that the User defines the proper paths to the mexcdf utilities. For MATLAB 5 it is imperative that the full mexcdf toolbox is in the path (the toolbox contains a front end giving the necessary backward compatibility). ======== Examples ======== The tar files "Ex_for_pemask_4.1.tar.gz" and "Ex_mat_pemask_4.1.tar.gz" contain examples which illustrate how the PE_MASK FORTRAN and MATLAB programs are used. The Example is in the Massachusetts Bay with one coastal segment (Massachusetts coastline from Cape Cod to Cape Ann) and no islands in the basin. This example starts from where the GRIDS example left off. -------------------------- FORTRAN: Massachusetts Bay -------------------------- After installing the examples tar file "Ex_for_pemask_4.1.tar.gz", the following files are extracted: GNUmakefile.sun5 makefile used to create the executable. param.h PE_MASK main parameter statement. pe_mask PE_MASK SUN Ultra executable. grids_massbay_nomask.nc A copy of the input GRIDS NetCDF file before masking. When working the example, a working copy should be made of this file, with the masking done on that file. flip.dat An ASCII file containing the (I,J) pairs of the points that need to be masked from the starting mask data which was obtained by selecting the zero meter isobath from the raw bathymetry. grids_massbay_mask.nc A copy of the input GRIDS NetCDF file after masking. This is provided for comparison to the user's results pe_mask.log an echo file of PE_MASK session showing how "pe_mask" was executed. T_mask.wrk working Land/Sea mask at the tracer points. T_mask.dat final Land/Sea mask at the tracer points. V_mask.dat final Land/Sea mask at the velocity points. ismask.dat Land/Boundary/Sea mask at the velocity points used to visualize the coastal segments. ------------------------- MATLAB: Massachusetts Bay ------------------------- After installing the examples tar file "Ex_mat_pemask_4.1.tar.gz", the following files are extracted: gulf_cst.dat Eastern US coastline data from CIA database. grids_massbay_nomask.nc A copy of the input GRIDS NetCDF file before masking. When working the example, a working copy should be made of this file, with the masking done on that file. grids_massbay_mask.nc A copy of the input GRIDS NetCDF file after masking. This is provided for comparison to the user's results pe_mask.log an echo file of PE_MASK session showing how "pe_mask" was executed. figure1.ps color Postscript file showing the starting Land/Sea mask data at the tracer points. This mask data is determined by selecting the zero meter isobath of the raw bathymetry. figure2.ps color Postscript file showing the final Land/ Sea mask.