HOPS Global Objective Analysis (OAG) Package HOST: maelstrom.harvard.edu (128.103.2.50) TAR FILES: pub/HOPS/OAG/oag_5.6.tar.Z (135854:534528 bytes) pub/HOPS/OAG/Ex_oag_5.6.tar.gz (4874217:7821312 bytes) VERSION: 5.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 global solution of the Objective Analysis (OA) equations. That is, the NOBS linear equations are solved by inverting the NOBS by NOBS matrix via direct (LU decomposition) or minimization (conjugate gradient) methods. By using a global solution, the OA problem is solved exactly. A potential problem is that this can quickly become too time consuming for a moderately large data set or even require more memory than is available. In these situations, an quick and memory sparse method is to use the approximate method of a local OA. The HOPS local OA package is available at this site in the directory "pub/HOPS/OA". ============ 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/OAG" and get files: Readme.oag This file. oag_5.6.tar.Z Compressed tar file of the OAG package. Ex_oag_5.6.tar.gz Compressed tar file of an example using the OAG package. To install this package, simply go to the directory in which you want to put the OAG package and execute the following commands: zcat oag_5.6.tar.Z | tar -pxvf - gzip -dc Ex_oag_5.6.tar.gz | tar -pxvf - The tar file oag_5.6.tar.Z contains the following files: oagmain.F acor.F blkdat.F brent.F caldate.F costfun.F day_code.F dcostfun.F defcdf.F descent.F dhlev.F diagn.F dynht.F errscl.F exitus.F f1dim.F filter.F gcircle.F get_date.F get_ewpt.F getclima.F getdynht.F getobs.F gregorian.F headln.F length.F linmin.F lintrp.F ll2xy.F lnblk.F locate.F lubksb.F ludcmp.F mapcor.F mnbrak.F my_handler.F nxt_blnk.F oa_err.F oamap.F oamean.F oapar.F qtrap.F readgrids.F readhydro.F rmblklines.FF rotparm.F rout_chk.F set_type.F svafunc.F svan.F svel.F trapzd.F xclima.F xhydro.F xy2ll.F cdescent.h clima.h corscl.h date.h debug.h domdat.h f1com.h fdiagn.h hydobs.h hydro.h inppar.h oa_netcdf.h oagrid.h obscor.h param.h trapz.h version.h GNUmakefile.alpha GNUmakefile.cray GNUmakefile.iris GNUmakefile.rs6000 GNUmakefile.sun3 GNUmakefile.sun4 GNUmakefile.sun5 UPDATES VMSmakefile.com compile.com oag.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 OAG 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 OAG with the appropriate C-preprocessing and compilier options. (2) The user who is modifying the OAG 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 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. ----------------------------------- GNUmakefile 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 OAG 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. MCMTX maximum size of correlation matrices. It is recommended to set these values big to avoid recompiling each time, for example: parameter (mobs=1000,mpts=10000,mgrd=60000,mday=50,mlev=20, & mvar=10,mcmtx=mobs*mobs) ================= 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 "oag.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 46) 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: ROUT outlier radius (km), observations outside ROUT are rejected. Card 16: METHOD OAG solution method: [0] direct: LU decomposition. [1] minimization: Conjugate gradient. Card 17: 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 18: XZERO correlation, zonal zero crossing (km). Card 19: YZERO correlation, meridional zero crossing (km). Card 20: XDCAY zonal decorrelation (decay) scale (km). Card 21: YDCAY meridional decorrelation (decay) scale (km). Card 22: TDCAY temporal decorrelation (decay) scale (days). Card 23: UPHSE correlation, zonal phase speed (km/day). Card 24: VPHSE correlation, meridional phase speed (km/day). Card 25: CORANG correlation, rotation angle (deg) counterclockwise from EAST. Card 26: XZEROM correlation, zonal zero crossing (km) used in the computation of the mean. Card 27: YZEROM correlation, meridional zero crossing (km) used in the computation of the mean. Card 28: XDCAYM zonal decorrelation (decay) scale (km) used in the computation of the mean. Card 29: YDCAYM meridional decorrelation (decay) scale (km) used in the computation of the mean. Card 30: TDCAYM temporal decorrelation (decay) scale (days) used in the computation of the mean. Card 31: UPHSEM correlation, zonal phase speed (km/day) used in the computation of the mean. Card 32: VPHSEM correlation, meridional phase speed (km/day) used in the computation of the mean. Card 33: CORANGM correlation, rotation angle (deg) counterclockwise from EAST used in the computation of the mean. Card 34: OBSERR observation error (value to add to correlation matrix diagonal). Card 35: CLMERR climatology error (value to add to correlation matrix diagonal). Card 36: NORD order to of Shapiro filter to apply to each OA field. Card 37: NFRQ number of times to Shapiro filter the field. Set NFRQ=0 for no filtering. Card 38: NFLD number of fields to OA. Card 39: 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 40: 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 41: ZREF level of no motion (in meters) for dynamic height computation. Card 42: 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 43: 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 44: NLEV number of depth levels to OA. Card 45: Z depth(s) of level to OA. The User needs to enter NLEV values here. Card 46: IGRIDS flag to activate the reading of GRIDS NetCDF file for the application problem: [0] DO NOT read GRIDS. [1] Use GRIDS file (Card 50) to set OA grid parameters. Card 47: IWRT flag to write out verbose output: [0] no. [1] yes. The program will write into the echo file (Card 47) 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 48: FNAME(1) name of output OAG NetCDF file. Card 49: FNAME(2) name of output OAG information/diagnosis file. Card 50: FNAME(3) name of input hydrographic observations file. Card 51: FNAME(4) name of input climatology data file. This file is used only if ICLIMA=1 or ICLIMA=2. Card 52: FNAME(5) name of input GRIDS NetCDF file. This file is used only if IGRIDS=1. ========= Executing ========= To execute the OAG program, use the following UNIX command: oag < oag.in > & log & ======== Examples ======== ----------------- Massachusetts Bay ----------------- The tar file "Ex_oag_5.6.tar.gz" contains an example that shows how the OAG 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 OAG 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 OAG output NetCDF file. Use only QG field classification when plotting OAG NetCDF fields. 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 OAG main parameter statement. oag OAG SUN Ultra executable. oag.in input script used to run the OAG program. massbay_gardner_jul90.mods MassBay hydrography data file. massbay_nodc_jul.mods NODC July climatology data file. grids_massbay.nc MassBay input GRIDS NetCDF file. The output from, finally, the Cond_Topo example. oag_massbay.nc MassBay output OAG NetCDF file. oag_massbay.echo output echo file from OAG. gmeta.cnt NCAR's plot file of MassBay 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 MassBay. gulf_cst.dat coastlines/islands data from CIA data set. sec_line.dat section endpoints. Used to plot line indicating section location on horziontal plots. 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.