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. INSTALLING D. COMPILING (optional) E. RUNNING THE PROGRAM F. GRAPHICAL OUTPUT AND TROUBLESHOOTING G. TESTING H. CONTACTS A. DISTRIBUTION FILES The following distribution packages (containing the software, test data sets, and information files) are currently available: 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. INSTALLING Follow the steps below to install the program: 1. If a previous version of the program is already installed, remove it. If you previously installed GLSNET 3.0 - 4.0, double-click Add/Remove Programs in the Control Panel, select GLSNET and click the Add/Remove button. Any user files in the ANNIE installation directory--such as those created in the test or user subdirectories--will be left behind intact. Move any such user files that need to be retained to another directory and delete the old annie4.0 installation directory. -- OR -- If you previously installed an earlier version of GLSNET, move to another location any data files that you happened to store in the GLSNET installation directory, then: a) Delete the glsnetX.X directory and its contents, where X.X is the version number of the previously-installed version. b) If you modified the PATH environment variable to make the previous version of GLSNET easily accessible from any directory, remove the glsnetX.X\bin directory from the PATH environment variable: (1) On Windows 9x machines, edit C:\AUTOEXEC.BAT to remove the glsnetX.X\bin directory from the "set PATH=" command. Reboot your system after modifying AUTOEXEC.BAT. (2) On Windows Me machines, select Run from the Start menu, enter "msconfig", and click OK. Select the Environment tab, select the PATH variable, and click the Edit button. Remove the annieX.X\bin directory from the value of PATH and click OK. (3) On Windows NT/2000 machines, double-click System in the Control Panel, select the Environment tab, and modify the value for Path to remove the annieX.X\bin directory. Rebooting is not necessary, but any existing MS-DOS Command Prompt windows should be closed and reopened. 2. Double-click glsnt4_0.exe to execute the installation program. Follow the directions on the screenoftware is installed in the directory By default, the software is installed in the directory C:\Program Files\USGS\glwnet4.0. This is the recommended installation directory, but you may use other directories or disk drives. Note that program components not installed initially can be installed later, and that any components damaged by, for example, being inadvertently overwritten, can be quickly reinstalled by double-clicking annie4_1.exe--a maintenance version of the installation program will be executed. Directory Structure ------------------- The following directory structure will be created (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 src and msg subdirectories are not installed in the Typical or Compact installations, but can be installed by choosing the Custom installation and selecting the Source Code component. b) The Compact installation will install only the bin, bin_data, and user subdirectories. c) It is recommended that any user files kept in the ANNIE directory structure be placed in the user subdirectory only. 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 (77 or later), and (3) a Graphical Kernel System (GKS) library or the INTERACTER graphics library. D. COMPILING (optional) The source code is provided so that users can generate the executable themselves. 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 (77 or later), b) familiarity with the compiler and the operating system under which the compiler runs (i.e., DOS or Windows), c) libraries and other data files from the LIBANNE distribution (version 4.1 or later, available from http://water.usgs.gov/software/libanne.html), and d) a Graphical Kernel System (GKS) library or the INTERACTER library from Interactive Software Services Ltd. (http://www.demon.co.uk/issltd/). As distributed, the DOS version of GLSNET is configured to be compiled with INTERACTER. INTERACTER is not a GKS library, but it is utilized by the DOS version of GLSNET through the use of code that substitutes appropriate INTERACTER subroutine calls for GKS subroutine calls. To compile GLSNET with a GKS library, see the README.TXT documentation distributed with LIBANNE for information on modifying graph.lib. Note that under Windows NT/2000/XP GLSNET must be compiled as a DOS executable (as opposed to a Windows console-mode executable). Subroutines within the LIBANNE util.lib library require the ANSI.SYS device driver, but ANSI.SYS is only supported for DOS applications and not for Windows applications under Windows NT/2000/XP. The Makefile used to compile the executable, using the Lahey Fortran 90 compiler and the Opus make program, is provided as an example. Lahey previously distributed the Opus make program with its compilers, but has since substituted the simpler automake program. The syntax of the Makefiles used with Opus make is very similar to that of UNIX make and can be adapted for use with other make programs. There will likely be further changes needed to compile using a different compiler. E. RUNNING THE PROGRAM If the option to modify the PATH environment variable was chosen during installation, GLSNET can be run in an MS-DOS Command Prompt window from any directory by typing "glsnet". If the option to modify the PATH environment variable was not chosen during installation, the full path name of the program must be typed, as in, for example, "c:\program files\usgs\glsnet4.0\bin\glsnet" (note that quotation marks must be typed with and enclose any command name with spaces embedded). Alternatively, you can run GLSNET by selecting the GLSNET shortcut from the Start menu. The shortcut is found under Programs, in the Program Folder specified during installation (default: USGS). The shortcut will run GLSNET from the user subdirectory. Therefore, if an input file name is specified with no directory path preceding the name, the input file will be expected to be found in the user subdirectory. Likewise, if an output file name is specified without a directory path preceding the name, the output file will be placed in the user subdirectory. Note that when plots are displayed on the screen, they will be displayed in full-screen mode and will be held on the screen until the Enter key is pressed. If, after pressing the Enter key to clear a plot, the display remains in full-screen mode (which will be the case under Windows NT/2000/XP), press alt+Enter to return from full-screen mode to window mode. Note also that, depending on the video card and monitor of the PC, the quality of the screen display of plots may be improved on Windows 9x/Me machines by removing the "display=10" line from the interact.ini initialization file (see below for details on interact.ini), though this line should not be removed during execution of the verification tests. The "display=10" line is necessary for proper display of plots on Windows NT/2000/XP machines. F. GRAPHICAL OUTPUT and TROUBLESHOOTING See the annie README.TXT file for guidance. 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 bat files to to run the tests check the results, and clean up after. The data subdirectory contains the input data and the expected results for each test. Do NOT run the tests in the data subdirectory. Run the tests by first opening an MS-DOS Command Prompt window and changing to the test subdirectory by typing the following (substitute the drive letter and directory where you installed GLSNET, if you did not install it in the default location): c: cd "program files" cd usgs\glsnet4.0\test Type the following command to run the tests: test.sh [start [stop ]] where: start = the number of the first test to perform, default = 1 stop = the number of the last test to perform, default = 4 At each Glsnet opening screen, type: @input.log The check.bat file will be run automatically when the tests are completed. 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: clean 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 and 4.1 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, 3, and4 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