README.TXT GLSNET Generalized Least Squares NETwork analysis Version 4.0 2005/01/27 IMPORTANT NOTE: If you have n-day data sets that were created using the N-day option in version 3.2 of SWSTAT, you will need to run WDMRX to correct a problem with the SEADBG and SEADND attributes. WDMRX is distributed with GLSNET. Instructions for installation, execution, and testing are provided below. After installation, see glsnet.txt in the doc subdirectory for summary information on GLSNET. For assistance, enhancement requests, or to report bugs, contact the Hydrologic Analysis Software Support Program by sending e-mail to h2osoft@usgs.gov. TABLE OF CONTENTS A. DISTRIBUTION FILES B. DOCUMENTATION C. EXTRACTING FILES D. COMPILING (optional) E. INSTALLING F. RUNNING THE PROGRAM G. TESTING H. CONTACTS A. DISTRIBUTION FILES The following distribution packages (containing the software, test data sets, and information files) are currently available for UNIX systems: glsnt4_1.exe - Compiled for Windows (includes source code) glsnet4.0.Solaris.tar.gz - Compiled for Sun UltraSPARC-II glsnet4.0.source.tar.gz - Source code only, for Unix compilation B. DOCUMENTATION Tasker, G.D., and Stedinger, J.R., 1989, An operational GLS model for hydrologic regression: Journal of Hydrology, v. 111, p. 361-375. Stedinger, J.R., and Tasker, G.D., 1985, Regional hydrologic analysis 1: Water Resources Research, v. 21, no. 9, p. 1421-1432. Stedinger, J.R., and Tasker, G.D., 1986, Regional hydrologic analysis 2: Water Resources Research, v. 22, no. 10, p. 1487-1499. Flynn, K.M., Hummel, P.R., Lumb, A.M., and Kittle, J.L., Jr., 1995, User's manual for ANNIE, version 2, a computer program for interactive hydrologic data management: U.S. Geological Survey Water-Resources Investigations Report 95-4085, 211 p. This report may be useful for understanding how the user interface and the wdm file work. This document is available in electronic format. A Portable Document Format (PDF) version is included in the doc subdirectory of the ANNIE program distribution. This and other formats can also be found at http://water.usgs.gov/software/annie.html. See http://infotrek.er.usgs.gov/pubs/ for information on obtaining electronic and/or printed copies of USGS publications. C. EXTRACTING FILES Compressed tar files are used to distribute the source code and versions of the software compiled for selected UNIX operating systems. All of the files needed to install and test the program are contained in the file glsnet4.0.OS.tar.gz (where OS is a string indicating the intended operating system.) If there is not a tar file for your operating system or you want to compile the software, the source version of the tar file contains all of the program files needed to compile and install the program on a UNIX-based computer (required libraries are available separately, see COMPILING below for details). For all of these distributions, the directory glsnet4.0 is created (or overwritten) when the files are extracted from the tar file; if this directory already exists, you may want to delete or rename it before extracting the files. Follow the steps below to extract the files from a distribution tar file. The software is configured for installation under /usr/opt/wrdapp. The wrdapp directory may be a separate file system mounted at /usr/opt/wrdapp. If you choose to install the software elsewhere, you will need to retrieve the source version of the tar file and compile the software. Steps in extracting files explanation ---------------------------------------- ----------------------------------- mv glsnet4.0.____.tar.gz /usr/opt/wrdapp If the tar file is not already in the directory where you want the distribution installed, move it there. cd /usr/opt/wrdapp If you are not in the directory where the tar file is located, go there. gunzip glsnet4.0.____.tar.gz Uncompress the distribution file. tar -xvpof glsnet4.0.____.tar Extract the distribution files from the tar file. This creates the following directory structure (the contents of each directory are shown to the right): glsnet4.0 files NOTICE.TXT, RELEASE.TXT, and this README.TXT `-----bin compiled executable(s) and shell script to run program `-----bin_data message file required during program execution `-----doc documentation files (see file Contents.txt) `-----src Makefile (and, with source tar, the source code) `-----msg (with source tar, script & file to build message file) `-----test scripts to run verification tests `-----data standard data sets used in verification tests Notes: a) The bin and bin_data subdirectories are not included in the source distribution; they are created during compilation. b) Source code is included only with the source distribution. c) It is recommended that no user files be kept in the program directory structure. If you plan to put files in the program directory structure, do so only by creating subdirectories. d) To compile a new version of the software, you will also need: (1) libraries and other data files from the libanne library distribution (version 4.1, or later, available from http://water.usgs.gov/software/libanne.html), (2) a Fortran compiler (90 or later), (3) a Graphical Kernel System (GKS) library, and (4) the annie program (version 4.1 or later) to build the test wdm files. D. COMPILING (optional) If you have retrieved a pre-compiled distribution of the software, skip to the Installing section below. If a compiled version of the software is not available for your computer or you want to build the executable yourself, follow the instructions in this section. The source distribution is provided for those users who want the source code. Little or no support can be provided for users generating their own versions of the software. In general, to compile a new version of the software, you will need: a) a Fortran compiler (90 or later), b) a minimal level of knowledge of Make, the compiler, and the UNIX operating system, c) libraries and other data files from the libanne library distribution (version 4.1 or later, available from http://water.usgs.gov/software/libanne.html), and d) a Graphical Kernel System (GKS) library; GKS libraries available without fee include Gli/gks (available from http://iff001.iff.kfa-juelich.de/gli/) and xgks (available as the file ftp://unidata.ucar.edu/pub/xgks/xgks-2.5.5.tar.Z). As provided in the source distribution, the software is set up to be compiled under Solaris in the /usr/opt/wrdapp directory. A small number of changes may be needed to compile on other UNIX platforms or in another directory. Additional changes will be required to compile on a PC or other non-UNIX platform. The versions.txt file found in the doc subdirectory identifies items that may need to be changed. To generate a new executable and message file, do the following: 1. The values for the indicated variables in the following files may need to be modified (see versions.txt in the doc subdirectory for more details): may need to be modified ------------------------------- version compiler file name variables flags name library --------------------- --------- ----------- ------- src/Makefile WrdA Libr FFLAGS FC LGks FFVrsn Strip LdA LdB LdC fglsms.inc FNAME msg/wdimex.sh WrdA Libr Anne test/test.sh WrdA GlsN Anne 2. Run make in the src directory to compile the source and build the message file. cd glsnet4.0/src make [SIZE=max_no_sites] Where SIZE is the maximum number of sites that can be analyzed. The default is 300 sites. Files for 300, 600, 700, and 1200 are provided, the user must provide their own ps___.inc file for other maximums. make will: a. create the subdirectories bin and bin_data, if they do not already exist, b. compile the source code, c. place the program executable in the bin subdirectory (the executable will be named gls[max_no_sites].exe, by default this is gls300.exe), d. run wdimex from the wdimex.sh script found in the msg subdirectory to build the message file (glsmes.wdm); the file is placed in bin_data, and e. run annie from the wdimex.sh script in the msg subdirectory to build the the tx.wdm and va.wdm files; the files are placed in the data directory. E. INSTALLING To make the program easy to use, a link to the shell script should be placed in a directory that is included in each user's search path. Run make in the src subdirectory to create the link: make install BINDIR=directory_for_links A link to the shell script will be placed in the directory assigned to BINDIR. For example, if each user's search path consists of /usr/bin:/usr/opt/bin:/usr/local/bin using the command make install BINDIR=/usr/local/bin will make the program accessible from any directory without requiring the full pathname of the shell script. Note that to create and delete links to the shell script, the installer must have sufficient rights to the BINDIR directory. This program uses the GLIGKS graphics library, V4.5.24, to generate graphics. You do not need to install the GLIGKS graphics library on your computer to use this pre-compiled distribution. You do need the GLIGKS file gksfont.dat; the bin_data subdirectory of this distribution contains a copy of the file. The program expects to find the file in the /usr/local/lib directory, but, you can install it elsewhere. If you do not already have gksfont.dat installed: o For the standard installation, copy the file to /usr/local/lib, from the bin_data directory of this distribtution: cp -p gksfont.dat /usr/local/lib (note that you may need system administrator rights) o If you install the file elsewhere, you will need to tell GLIGKS about the new font path: setenv GLI_HOME path or export GLI_HOME=path (Note that each user of the software will need to set the path for GLI_HOME.) F. RUNNING THE PROGRAM If the program has been installed in a directory included in the users' PATH (as described above), the program can be executed with the command: glsnet [size] where: size = max no. of stations program will analyze By default, size is 300. Versions of glsnet dimensioned for 600 and 700 stations are also included. If the program has not been installed in a directory included in the users' PATH, the full pathname of the shell script will need to be typed. G. TESTING Test data sets are provided to verify that the program is correctly installed and running on the system. The tests may also be looked at as examples of how to use the program. The test subdirectory contains the scripts to run the tests. The data subdirectory contains the input data and the expected results for each test. Tests are usually run in the test subdirectory, but they can be run in any user directory. Do NOT run the tests in the data subdirectory. Type the following commands to test the program installation. [path]/test.sh [start [stop [size]]] where: path = path to the script use "." if running the tests in the test directory, use full pathname if running in a directory other than test; do _NOT_ run the test in the data directory. start = the number of the first test to perform, default = 1 stop = the number of the last test to perform, default = 3 size = version of glsnet to be tested, by default this is = 300, versions dimensioned for 600, 700, and 1200 stations are also available. For example: command what happens -------------------------------------- -------------------------------- ./test.sh runs tests 1 - 3 ./test.sh 1 1 runs the first test ./test.sh 2 runs tests 2 and 3 /usr/opt/wrdapp/glsnet4.0/test/test.sh runs all of the tests ./test.sh 1 2 600 runs tests 1 & 2 using glsnet dimensioned to 600 After the tests are completed, the results are compared to the expected results (found in the data subdirectory). See the file check.log to verify the tests produced the expected results. Expect to find the following differences: a) The standard data sets were created on a Sun UltraSPARC-II system. You may notice slight numeric differences in the results on other computers. These are generally due to different round-off algorithms and the different architecture of the central processing unit chip. Slight differences in output formats may occur on other computers, particularly for the value 0.0. b) Each data set in an archive file (.exp) will contain the attribute DATCRE and DATMOD, the dates the data set was created and last modified, respectively. c) Postscript files contain the creation date. d) If a graphics library other than GliGks is used, there will probably be significant differences in the graphics output files (.ps and .cgm); they should still produce the same images. To clean up after the tests, type the command: [path]/clean.sh where path is as described above. The tests are described in the table below, where 'test' is the test number, 'program' is the program used to run the test, and the 'usage' column indicates how a file is used, with i for input, o for output, and i/o for both input and output. Notes: a) The annie program (version 4.1 or later) is required for test 1.a if data/tx.wdm is not available and for tests 2.a and 3.a if data/va.wdm is not available If the wdm files and the annie program are not available, the tests cannot be run. b) Tests 2.d and 3.d requires the annie program, if the program is not available, this steps will be skipped. c) Tests 1, 2, and 3 are independent. test program description of test and files file name & usage ---- ------- --------------------------------- ----------------- 1.a annie build Texas wdm file (if data/tx.wdm exists, it will be used) annie command file test1.lga i annie archive file tx.exp i Texas peak-flow data tx.wdm o error file test1.era o 1.b glsnet Generalized least squares analysis of peak-flow data glsnet command file test1.log i Texas peak-flow data tx.wdm i regression summary output file test1.out o variables used for input test1.ot1 o concurent record matrix test1.ot2 o cross-correlation matrix test1.ot3 o 100-yr peak vs darea plot test1.ps o cross-correlation plot test1a.ps o error file test1.err o 2.a annie build Virginia wdm file (if data/va.wdm exists, it will be used) annie command file test2.lga i annie archive file va.exp i Virginia peak-flow data va.wdm o error file test2.era o 2.b glsnet add partial record data Stedinger partial record sites have month in file glsnet command file test2.lgb i Virginia low-flow data va.wdm i/o partial record site test2.pr1 i partial record site test2.pr2 i partial record data computation test2.ot1 o partial record data computation test2.ot2 o resid vs obs, Shenandoah R test2.ps o error file test2.erb o 2.c glsnet Generalized least squares analysis of low-flow data. glsnet command file test2.log i Virginia low-flow data va.wdm i/o regression summary output file test2.out o error file test2.err o 2.d annie export simulated time series annie command file test2.lgd i Virginia peak-flow data va.wdm i export file test2.exp o error file test2.erd o 3.a annie build Virginia wdm file (if data/va.wdm exists, it will be used for va2.wdm) annie command file test3.lga i annie archive file va.exp i Virginia peak-flow data va2.wdm o error file test3.era o 3.b glsnet add partial record data Stedinger partial record sites have no month in file glsnet command file test3.lgb i Virginia low-flow data va2.wdm i/o partial record site test3.pr1 i partial record site test3.pr2 i partial record data computation test3.ot1 o partial record data computation test3.ot2 o resid vs obs, Shenandoah R test3.ps o error file test3.erb o 3.c glsnet Generalized least squares analysis of low-flow data. glsnet command file test3.log i Virginia low-flow data va2.wdm i/o regression summary output file test3.out o error file test3.err o 3.d annie export simulated time series annie command file test3.lgd i Virginia peak-flow data va2.wdm i export file test3.exp o error file test3.erd o 4.a annie build Texas wdm file (if data/tx.wdm exists, it will be used for tx2.wdm) annie command file test4.lga i annie archive file tx.exp i Texas peak-flow data tx2.wdm o error file test4.era o 4.b glsnet Generalized least squares analysis of peak-flow data glsnet command file test4.log i Texas peak-flow data tx.wdm i regression summary output file test4.out o variables used for input test4.ot1 o concurent record matrix test4.ot2 o cross-correlation matrix test4.ot3 o 100-yr peak vs darea plot test4.ps o error file test4.err o H. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Office of Surface Water 415 National Center Reston, VA 20192 e-mail: h2osoft@usgs.gov