HOPS Local Objective Analysis (OA) Package HOST: maelstrom.harvard.edu (128.103.2.50) TAR FILES: pub/HOPS/OA/oa_6.6.tar.Z (139905:552960 bytes) pub/HOPS/OA/Ex_oa_6.6.tar.gz (4866091:7809024 bytes) VERSION: 6.6 (January 23, 2001) 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) 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 generalized space-time objective analysis/statistical forecast package. This package is used to map irregularly positioned data onto a regular grid. This package uses a local solution of the Objective Analysis (OA) equations. That is, only NNCE influential observations are considered at each mapped grid point. This approximation can be justified since observations that are too far apart in space and time from the mapped point contribute very little to the estimate (correlations are very small). This method is practical because it avoids inverting large matrices when the number of observations NOBS is large. However, this approach destroys the smoothness properties of the mapping; the estimated field can be somewhat noisy. If time and computer memory are not issues, it is suggested that the global OA be used. The HOPS global OA package is available at this site in the directory "pub/HOPS/OAG". ============ 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/OA" and get files: Readme.oa This file. OA_6.6.tar.Z Compressed tar file of the OA package. Ex_oa_6.6.tar.gz Compressed tar file of an example using the OA package. To install this package, simply go to the directory in which you want to put the OA package and execute the following commands: zcat oa_6.6.tar.Z | tar -pxvf - gzip -dc Ex_oa_6.6.tar.gz | tar -pxvf - The tar file oa_6.6.tar.Z contains the following files: oamain.F acor.F asm.F bes1d.F bes2d.F blkdat.F caldate.F day_code.F defcdf.F dhlev.F diagn.F down_shift.F dynht.F errscl.F exitus.F filter.F gcircle.F get_date.F get_ewpt.F getclima.F getdynht.F getobs.F gregorian.F headln.F ierinv.F indepen.F invmtx.F length.F lintrp.F ll2xy.F lnblk.F locate.F lubksb.F ludcmp.F my_handler.F nxt_blnk.F oamean.F oapar.F objan.F outlier.F qtrap.F readgrids.F readhydro.F remove.F rmblklines.FF rotparm.F rout_chk.F select.F set_type.F sort.F svafunc.F svan.F svel.F trapzd.F trend.F trendcoef.F xclima.F xhydro.F xy2ll.F clima.h corscl.h date.h debug.h domdat.h fdiagn.h hydobs.h hydro.h inppar.h oa_netcdf.h oagrid.h obscor.h param.h trapz.h trdcff.h version.h GNUmakefile.alpha GNUmakefile.cray GNUmakefile.iris GNUmakefile.rs6000 GNUmakefile.sun3 GNUmakefile.sun4 GNUmakefile.sun5 UPDATES VMSmakefile.com compile.com oa.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 OA 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 OA with the appropriate C-preprocessing and compilier options. (2) The user who is modifying the OA 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. ---------------------------------- 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: 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 directory path for the parameter file: "param.h". SRCDIR directory path for the source code. -------------------------------- Makefile C-preprocessing Options -------------------------------- The following C-preprocessing options are available and are specified 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 rmcomments Remove comments when pre-processing. sundate SUN's intrinsic date routine. sunflush regularly flush output buffers in SUN systems. 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 OA 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 include parameter file "param.h". The User needs to set the following parameters: MOBS maximum number of hydrographic observations. MPTS maximum number of points per hydrographic profile. MGRD maximum number of points to objectively analyze. MDAY maximum number of day to objectively analyze. MLEV maximum number of depth levels to objectively analyze. MVAR maximum number of variables to objectively analyze. MNCE maximum number of influential points. It is recommended to set these values big to avoid recompiling each time, for example: parameter (mobs=16000,mpts=10000,mgrd=60000,mday=50,mlev=20, & mvar=10,mnce=100) ================= 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 "oa.in". The input parameters and switches that the User needs to determine are: Card 1: TITLE Application title. Card 2: IHFRMT input hydrography file format: [0] unformatted: depth, temperature, salinity, and dynamic height. [1] unformatted: depth, temperature and salinity (CTD,XCTD). [2] unformatted: depth and temperature (XBT,AXBT) [3] unformatted: depth and dynamic height. [4] unformatted: depth and any oceanic field. [5] unformatted: any field (a single value; NHPTS=NHVAR=1). The following parameters are reset internally: NFLD=1, IDFLD(1)=0, NDAY=1, OADAY(1)=0, NLEV=1, and Z(1)=-9. [6] formatted: HOPS hydrography ASCII format. The read statement for options [0] to [5] is as follows: read (iunit) CASTID, HLAT, HLNG, JDAY, ITIME read (iunit) NHPTS, ((FIELDS(i,j),i=NHVAR),j=1,NHPTS) Card 3: ICLIMA option to compute mean fields: [0] OA mean field from hydrographic observations only. [1] OA mean field from climatologic observations only. [2] OA mean field using both hydrographic and climatologic observations. [3] Use global observation mean (a single value). The user must provide climatology file (Card 51) when using ICLIMA=1,2,3. For very sparse hydrographic data, it is recommended to use both hydrographic data and climatological data (for example, Levitus Atlas) when computing mean fields. Climatology data is a more oceanographically correct field than any extrapolation of data to places of no observations. In dynamically active regions, the melding of hydrographic and climatological data to compute mean fields is like assuming non-stationary statistics for the mean. Card 4: ICFRMT input climatology file format (same options as IHFRMT). Card 5: COORD grid type: [0] Cartesian (rotated or unrotated). [1] unrotated spherical. [2] rotated spherical. Card 6: IM number of points in the x-direction. Card 7: JM number of points in the y-direction. Card 8: DX zonal grid spacing (depending on COORD, km or degrees). Card 9: DY meridional grid spacing (depending on COORD, km or degrees). Card 10: CLNG domain centroid longitude (degrees, west values are negative). Card 11: CLAT domain centroid latitude (degrees, south values are negative). Card 12: DELX X-offset from transformation point to grid center. (km or deg) Card 13: DELY Y-offset from transformation point to grid center. (km or deg) Card 14: THETAD domain rotation (degrees, positive counterclockwise from EAST). Card 15: NNCE number of influential points. Card 16: RNCE radius of influence (km). Card 17: TNCE influential time window (days). Card 18: RAVG averaging radius for nearby observations (km). If RAVG and TAVG are zero, then close observations are not averaged. Card 19: TAVG averaging time for nearby observations (days). Card 20: ROUT outlier radius (km), observations outside ROUT are rejected. Card 21: ICORR type of analytical correlation. Currently, only ICORR=1 is available: rotated or non-rotated, time displaced or not, Cartesian or spherical, isotropic (symmetric: circular) or anisotropic (asymmetric: elliptical) Gaussian correlation in space and time. C(Xj,Yj,Tj,Xi,Yi,Ti) = ( 1 - a2 ) * EXP ( b2 + c2 ) where a2 = Rx^2 / xzero^2 + Ry^2 / yzero^2 b2 = - 0.5 * ( Rx^2 / xdcay^2 + Ry^2 / ydcay^2 ) c2 = - 0.5 * delt^2 / tdcay^2 Rx = xp * cos(phi) + yp * sin(phi) + delt * uphse Ry = yp * cos(phi) - xp * sin(phi) + delt * vphse phi = corang - thetad delt = Tj - Ti if Cartesian grid coordinates, xp = Xj - Xi yp = Yj - Yi or if spherical grid coordinates, r = gcircle (Xj,Yj,Xi,Yi,dist,bearing) xp = dist*cos(bearing) yp = dist*sin(bearing) The correlation displacement speeds UPHSE and VPHSE are aligned with the correlation axes rotated by CORANG. Card 22: XZERO correlation, zonal zero crossing (km). Card 23: YZERO correlation, meridional zero crossing (km). Card 24: XDCAY zonal decorrelation (decay) scale (km). Card 25: YDCAY meridional decorrelation (decay) scale (km). Card 26: TDCAY temporal decorrelation (decay) scale (days). Card 27: UPHSE correlation, zonal phase speed (km/day). Card 28: VPHSE correlation, meridional phase speed (km/day). Card 29: CORANG correlation, rotation angle (deg) counterclockwise from EAST. Card 30: XZEROM correlation, zonal zero crossing (km) used in the computation of the mean. Card 31: YZEROM correlation, meridional zero crossing (km) used in the computation of the mean. Card 32: XDCAYM zonal decorrelation (decay) scale (km) used in the computation of the mean. Card 33: YDCAYM meridional decorrelation (decay) scale (km) used in the computation of the mean. Card 34: TDCAYM temporal decorrelation (decay) scale (days) used in the computation of the mean. Card 35: UPHSEM correlation, zonal phase speed (km/day) used in the computation of the mean. Card 36: VPHSEM correlation, meridional phase speed (km/day) used in the computation of the mean. Card 37: CORANGM correlation, rotation angle (deg) counterclockwise from EAST used in the computation of the mean. Card 38: ITRT detrend option (surface to remove from observations): [0] only the mean is substrated. [1] linear. [2] quadratic. [3] cubic. Card 39: OBSERR observation error (value to add to correlation matrix diagonal). Card 40: CLMERR climatology error (value to add to correlation matrix diagonal). Card 41: NORD order to of Shapiro filter to apply to each OA field. Card 42: NFRQ number of times to Shapiro filter the field. Set NFRQ=0 for no filtering. Card 43: NFLD number of fields to OA. Card 44: IDFLD ID of field(s) to OA. The User needs to enter a NFLD values here. Use the following ID code: [0] generic oceanic field. [1] pressure (depth). [2] temperature. [3] salinity. [4] dynamic height. [5] density. [6] sigma-t. [7] sound speed. Card 45: IDHOPT dynamic height computation option. This is only possible when pressure (or depth), temperature, and salinity are available at input. Options: [0] DO NOT compute. [1] integrate specific volume anomaly from ZREF to the surface. [2] integrate specific volume anomaly from ZREF to the bottom. [3] integrate in both [1] and [2] directions. [4] integrate specific volume anomaly from the surface to the local bottom of the hydrographic profile. Card 46: ZREF level of no motion (in meters) for dynamic height computation. Card 47: NDAY number of days to OA. If only one objective analysis day is desired set NDAY=1 and if, in addition, it is desired to be centered at the mean observations time. Card 48: OADAY day to OA. Usually modified Julian day. The User needs to enter NDAY values here. The OADAY should be consisted with the input data. Card 49: NLEV number of depth levels to OA. Card 50: Z depth(s) of level to OA. The User needs to enter NLEV values here. Card 51: IGRIDS flag to activate the reading of GRIDS NetCDF file for the application problem: [0] DO NOT read GRIDS. [1] Use GRIDS file (Card 55) to set OA grids parameters. Card 52: IWRT flag to write out verbose output: [0] no. [1] yes. The program will write into the echo file (Card 52) a message every time that there are insufficient influential observations or every time that the estimation is unsuccessful because a poor conditioned local covariance matrix. The mean field value is assigned at that particular interpolation point, if either of these two problems occur. Card 53: FNAME(1) name of output OA NetCDF file. Card 54: FNAME(2) name of output OA information/diagnosis file. Card 55: FNAME(3) name of input hydrographic observations file. Card 56: FNAME(4) name of input climatology data file. This file is used only if ICLIMA=1 or ICLIMA=2. Card 57: FNAME(5) name of input GRIDS NetCDF file. This file is used only if IGRIDS=1. ========= Executing ========= To execute the OA program, use the following UNIX command: oa < oa.in > & log & ======== Examples ======== ----------------- Massachusetts Bay ----------------- The tar file "Ex_oa_6.6.tar.gz" contains an example that shows how the OA package is used. The Example is in Massachusetts Bay (MassBay) and uses data collected by Drs George B. Gardner (University of Massachusetts) and W. Rockwell Geyer (Woods Hole Oceanographic Institution) during a cruise on 24-26 July 1990, funded under the Massachusetts Bays Program. The data has been converted to the HOPS hydrographic ASCII format. Information about this format can be found in "pub/HOPS/Datamng". This example contains a two stage OA field estimation. The first stage is for the estimation of the mean fields, which is computed by melding the hydrographic observations with the climatological data. Rather large correlation scales are used to compute this mean field: spatial decay scale: 400 (km) spatial zero crossing: 600 (km) temporal decay scale: 100000 (days) The second stage is for the desired synoptic fields: temperature, salinity and dynamic height. Smaller correlation scales are used spatial decay scale: 15 (km) spatial zero crossing: 30 (km) temporal decay scale: 100 (days) This example also shows how the plotting package is used to produce horizontal contours from OA output NetCDF file. Use only QG field classification when plotting OA NetCDF field. 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 OA parameter statement. oa OA SUN Ultra executable. oa.in input script used to run the OA program. massbay_gardner_jul90.mods IFF hydrography data file. massbay_nodc_jul.mods climatology data file. grids_massbay.nc IFF input GRIDS NetCDF file. oa_massbay.nc IFF output OA NetCDF file. oa_massbay.echo output echo file from OA. gmeta.cnt NCAR's plot file of IFF horizontal contours. gmeta.sec NCAR's plot file of MassBay vertical contours. oa_ccnt.in input script to plotting package CCNT_NCAR. oa_csec.in input script to plotting package CSEC_NCAR. gs1.pal.white color palette used in horizontal contours. plot_pe.gap.dat plotting package parameters for the IFF. gulf_cst.dat coastlines/islands data from CIA data set. sec_line.dat section endpoints. Used to plot line oa_ccnt.log output of CCNT_NCAR, use to trace version number for plotting package. oa_csec.log output of CSEC_NCAR, use to trace version number for plotting package.