HOPS PE model forcing processing (PE_FORCING) Program: HOST: maelstrom.harvard.edu (128.103.2.50) TAR FILES: pub/HOPS/PE_forcing/pefrc_3.5.tar.Z (50666:207360 bytes) pub/HOPS/PE_forcing/Ex_pefrc_3.5.tar.gz (5636030:9185280 bytes) VERSION: 3.5 (January 24, 2001) ORIGIN: Harvard University, Cambridge Massachusetts Harvard Ocean Prediction System (HOPS) DEVELOPER: Patrick J. Haley Jr. (haley@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/ ============ INTRODUCTION ============ This directory contains HOPS's PE model forcing processing (PE_FORCING) program. PE_FORCING reads, processes, and writes forcing fields to be used by the PE model. The forcing fields are of two types: point or gridded data. Point data only varies in time whereas gridded data varies in space and time. Currently, this program processes the following forcing fields: (1) Surface momentum flux (wind stress). A vector field with two components: zonal and meridional fluxes. It is written in units of dynes/cm^2. (2) Surface (net) heat flux. A scalar field written in units of Watt/m^2, and positive for downward flux (heating). (NET = shortwave + longwave + sensible + latent) (3) Surface water flux (Evaporation-Precipitation). A scalar field written in units of cm/day, and positive for net net evaporation and negative for net precipitation. (4) Shortwave radiation. A scalar field written in units of Watt/m^2, and positive for downward flux (heating). These forcing fields are written into a NetCDF file which is read by the PE model. ============ Installation ============ This program 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.pefrc This file. pefrc_3.5.tar.Z Compressed tar file of the PE_FORCING program Ex_pefrc_3.5.tar.gz Compressed tar file of the PE_FORCING Examples. To install this package, simply go to the directory in which you want to put the PE_FORCING program and execute the following commands: zcat pefrc_3.5.tar.Z | tar -pxvf - gzip -dc Ex_pefrc_3.5.tar.gz | tar -pxvf - The tar file pefrc_3.5.tar.Z contains the following files: pe_forcing.F bes1d.F bes2d.F blkdat.F day_code.F defcdf.F exitus.F get_date.F get_grdflx.F get_parm.F length.F lnblk.F my_handler.F readgrids.F rmblklines.FF wrt_fluxes.F forcing.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_forcing.in ============ 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_FORCING 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_FORCING with the appropriate C-preprocessing and compilier options. (2) The user who is modifying the PE_FORCING 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_FORCING 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 compilier ===================== 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 parameter: NP maximum number of horizontal points. It is recommended to set these values big to avoid recompiling each time, for example: parameter (np=100000) ================= Input Script File ================= 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 "pe_forcing.in". The input parameters and switches that the User needs to determine are: Card 1: TITLE Application title (character string). Card 2: SMFTYP switch indicating the type of input surface momentum flux (wind stress) data: [0] point time-series data. [1] gridded time-series data. Card 3: SMFFRM switch indicating the input file format for surface momentum flux (wind stress) data: [1] ASCII. [2] NetCDF. It will be available in a future version. Card 4: SMFSCL scale for input surface momentum flux (wind stress) data. This program expects surface momentum flux in units of dynes/cm^2 and positive toward the true NORTH and EAST. If applicable, use SMFSCL to convert to this units, otherwise set SMFSCL=1.0. 1 dyne/cm^2 = 0.1 N/m^2 = 0.1 Pa Card 5: SHFTYP switch indicating the type of input surface (net) heat flux data: [0] point time-series data. [1] gridded time-series data. Card 6: SHFFRM switch indicating the input file format for surface (net) heat flux data: [1] ASCII. [2] NetCDF. It will be available in a future version. Card 7: SHFSCL scale for input surface (net) heat flux data. This program expects surface net heat flux in units of Watt/m^2 and positive for downward flux: heating. If applicable, use SHFFRM to convert to this units, otherwise set SHFFRM=1.0. (NET = shortwave + longwave + sensible + latent) 1 W/m2 = 2.5e-5 degC cm/s Card 8: SWFTYP switch indicating the type of input surface water flux (E-P) data: [0] point time-series data. [1] gridded time-series data. Card 9: SWFFRM switch indicating the input file format for surface water flux (E-P) data: [1] ASCII. [2] NetCDF. It will be available in a future version. Card 10: SWFSCL scale for input surface water flux (E-P) data. This program expects surface water flux in cm/day, and positive for net evaporation and negative for net precipitation. If applicable, use SWFSCL to convert to this units, otherwise set SWFSCL=1.0. Card 11: SWRTYP switch indicating the type of input shortwave radiation data: [0] point time-series data. [1] gridded time-series data. Card 12: SWRFRM switch indicating the input file format for shortwave radiation data: [1] ASCII. [2] NetCDF. It will be available in a future version. Card 13: SWRSCL scale for input shortwave radiation data. This program expects shortwave radiation in units of Watt/m^2, and positive for downward flux: heating. If applicable, use SWRSCL to convert to this units, otherwise set SWRSCL=1.0. Card 14: INTOPT horizontal interpolation option for gridded data: [0] linear. [1] Bessel. Card 15: GRDNAME input GRIDS NetCDF file name. Card 16: OUTNAME output PE_FORCING NetCDF file name. Card 17: LSMFLUX logical switch to process surface momentum flux (wind stress) data. Card 18: FNAME(1) input surface momentum flux (wind stress) file name. Card 19: LSHFLUX logical switch to process surface (net) heat flux data. Card 20: FNAME(2) input surface (net) heat flux file name. Card 21: LSWFLUX logical switch to process surface water flux (E-P) data. Card 22: FNAME(3) input surface water flux (E-P) file name. Card 23: LSWRAD logical switch to process shortwave radiation data. Card 24: FNAME(4) input shortwave radiation file name. ===================================== Input ASCII Format for Forcing Fields ===================================== The input forcing fields to PE_FORCING program can be any of the following two types: Point or Gridded time-series data. ---------------------- Point Time-Series Data ---------------------- The point time-series data are defined as ungridded data in which a single value is taken as constant for the horizontal forcing field distribution. This type of data only varies in time, and is uniform in the horizontal (longitude,latitude) grid. The PE_FORCING reads the following variables (for clarity, the names of these variables are generic): NTIME length of time series (integer). TIME modified Julian Day (real vector of length NTIME). VAL scalar forcing field value (real vector of length NTIME). VALX x-component forcing field value (real vector of length NTIME). VALY y-component forcing field value (real vector of length NTIME). The data is read in free format as follows: read(*,*) ntime do n=1,ntime read(*,*) time(n),val(n) scalar forcing field or read(*,*) time(n),valx(n),valy(n) vector forcing field end do ------------------------ Gridded Time-Series Data ------------------------ The gridded time-series data are defined as data available in a regular non-rotated grid, equally-spaced in degrees in latitude and longitude (although the longitude spacing need not equal the latitude spacing) and with LON(i) < LON(i+1) and LAT(j) < LAT(j+1) and with no missing or flagged values. Otherwise, the horizontal interpolation will not work correctly. This type of data varies in space and time. The PE_FORCING reads the following variables (for clarity, the names of these variables are generic): NTIME length of time series (integer). NPTX number of points in the x-direction (integer). NPTY number of points in the y-direction (integer). LON longitude of the gridded data (real vector of length NPTX). LAT latitude of the gridded data (real vector of length NPTY). TIME modified Julian Day (real vector of length NTIME). VAL scalar forcing field (real vector of length NPTX x NPTY for each time series). VALX x-component forcing field (real vector of length. NPTX x NPTY for each time series). VALY y-component forcing field (real vector of length NPTX x NPTY for each time series). The data is read in free format as follows: read(*,*) ntime,nptx,npty read(*,*) (lon(i),i=1,nptx) read(*,*) (lat(j),j=1,npty) do n=1,ntime read(*,*) time(n) read(*,*) ((val(i,j),i=1,nptx),j=1,npty) scalar forcing field or read(*,*) time(n) read(*,*) ((valx(i,j),i=1,nptx),j=1,npty) vector forcing field read(*,*) time(n) read(*,*) ((valy(i,j),i=1,nptx),j=1,npty) end do This gridded data is interpolated to the appropriated model grid using either linear or Bessel (see input Card 14) interpolation. The Bessel (cubic) interpolation uses 16-points so the input forcing data grid should be larger than that of the model. ========= Executing ========= To execute the PE_FORCING FORTRAN program, use the following UNIX command: pe_forcing < pe_forcing.in > & log & ======== Examples ======== ----------------- Massachusetts Bay ----------------- The tar file "Ex_pefrc_3.5.tar.gz" contains an example which illustrates how the PE_FORCING program is used. The Example prepares the forcing fields for a grid in Massachusetts Bay. It prepares surface forcing data which was obtained from the Fleet Numerical Meteorology/Oceanography Center (FNMOC) over the period 17 June - 9 July 1997 and converted into a format readable by PE_FORCING. The topography file was created by the GRIDS package ("pub/HOPS/GRIDS"), given a land mask by the land masking package ("pub/HOPS/PE_mask") and had it's topography conditioned by the topography conditioning package ("pub/HOPS/Cond_Topo"). This topography file was taken from the output of the example in the conditioning package. This example also shows how the plotting package is used to produce horizontal contours. This plotting package can be found in "pub/HOPS/Plot". This example includes the following files: GNUmakefile.sun5 makefile used to create the executable. param.h PE_FORCING main parameter statement. pe_forcing PE_FORCING SUN Ultra executable. pe_forcing.in input script used to run PE_FORCING. grids_massbay.nc input GRIDS NetCDF file. dat.emp.all input water flux (Evaporation-Precipitation) data. dat.heat.all input surface (net) heat flux data. dat.rad.all input shortwave radiation data. dat.wstr.all input surface momentum flux (wind stress) data. pe_frc_fnmoc.nc output PE_FORCING NetCDF file. gmeta.cnt NCAR's plot file of MassBay horizontal contours. pe_ccnt.in input script to plotting package CCNT_NCAR. gs1.pal.white color palette used in horizontal contours. plot_pe.frc.dat plotting package parameters for the MassBay. gulf_cst.dat coastlines/islands data from CIA dataset. pe_ccnt.log output of CCNT_NCAR, use to trace version number for plotting package.