README.TXT PEAKFQ Annual Flood Frequency Analysis Using Bulletin 17B Guidelines Version 4.1 2002/02/25 Instructions for installation, execution, and testing are provided below. After installation, see peakfq.txt in the doc subdirectory for summary information on PEAKFQ. 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. SYSTEM REQUIREMENTS B. DISTRIBUTION FILE C. DOCUMENTATION D. INSTALLING o Installing PEAKFQ o PEAKFQ directory structure E. COMPILING (optional) F. RUNNING THE SOFTWARE o Out of environment space error G. GRAPHICAL OUTPUT H. TESTING I. UNINSTALLING J. CONTACTS A. SYSTEM REQUIREMENTS To install and run PEAKFQ, the following are necessary: - Pentium-class PC - Windows 9x/Me, Windows NT 4.0, Windows 2000, or Windows XP - up to 4.3 megabytes of free disk space - 3.7 megabytes of free memory - on Windows 9x/Me machines, MS-DOS Command Prompt window memory settings as described below A memory protection fault error can occur on Windows 9x/Me machines if the memory settings of MS-DOS Command Prompt windows are not set as follows: After opening an MS-DOS Command Prompt window, click the icon in the upper left corner of the window and select the Properties menu item. Select the Memory tab and modify the fields to set everything to "Auto", but change "Expanded (EMS) memory" to "none" and enter 65535 (the maximum allowed value) in the "MS-DOS protected-mode (DPMI) memory" input field. B. DISTRIBUTION FILE The following distribution file (containing the software, test data sets, and information files) is currently available. peakfq4_1.exe - Compiled using Lahey Fortran 90, includes source C. DOCUMENTATION Interagency Advisory Committee on Water Data, 1982, Guidelines for determining flood-flow frequency: Bulletin 17B of the Hydrology Subcommittee, Office of Water Data Coordination, U.S. Geological Survey, Reston, Va., 183 p. Available as report no. PB 86 15 7278 from National Technical Information Service 5285 Port Royal Road Springfield VA 22161 electronic mail: orders@ntis.fedworld.gov Phone: 1-800-553-NTIS (6847) or (703) 605-6000 Fax: (703) 605-6900 Thomas, W.O., Jr., Lumb, A.M., Flynn, K.M., and Kirby, W.H., 1998, User's manual for program PEAKFQ, annual flood frequency analysis using Bulletin 17B guidelines, written communication, 89 p. This document is available in electronic format. A Portable Document Format (PDF) version is included in the doc subdirectory of the PEAKFQ program distribution. This and other formats can also be found at http://water.usgs.gov/software/peakfq.html. Lumb, A.M., and Kittle, J.L., Jr., and Flynn, K.M., 1990, Users manual for ANNIE, a computer program for interactive hydrologic analyses and data management: U.S. Geological Survey Water-Resources Investigations Report 89-4080, 236 p. Unless otherwise noted, printed copies of USGS publications can be obtained from USGS Information Services. For information on ordering, see http://water.usgs.gov/software/ordering_documentation.html. D. INSTALLING Installing PEAKFQ ----------------- Follow the steps below to install PEAKFQ: 1. If a previous version of PEAKFQ is already installed, remove it. If you previously installed PEAKFQ 4.0, double-click Add/Remove Programs in the Control Panel, select PEAKFQ 4.0, and click the Add/Remove button. Any user files in the PEAKFQ 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 peakfq4.0 installation directory. -- OR -- If you previously installed an earlier version of PEAKFQ, move to another location any data files that you happened to store in the PEAKFQ installation directory, then: a) Delete the peakfqX.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 PEAKFQ easily accessible from any directory, remove the peakfqX.X\bin directory from the PATH environment variable: (1) On Windows 9x machines, edit C:\AUTOEXEC.BAT to remove the peakfqX.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 peakfqX.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 peakfqX.X\bin directory. Rebooting is not necessary, but any existing MS-DOS Command Prompt windows should be closed and reopened. 2. Double-click peakfq4_1.exe to execute the installation program. Follow the directions on the screen. By default, the software is installed in the directory C:\Program Files\USGS\peakfq4.1. 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 peakfq4_1.exe--a maintenance version of the installation program will be executed. PEAKFQ directory structure -------------------------- The following directory structure will be created (the contents of each directory are shown to the right): peakfq4.1 files NOTICE.TXT, RELEASE.TXT, and this README.TXT `-----bin compiled executable `-----bin_data data files required during execution `-----doc documentation files (see file Contents.txt) `-----src Makefile and source code `-----msg files for building message file `-----test files for running verification tests `-----data standard data sets used in verification tests `-----user batch file for running executable 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 PEAKFQ 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.0 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. e) To run test 0 below or to use the WDM data input option, you will need the IOWDM program (version 4.0, or later, available from http://water.usgs.gov/software/iowdm.html). To run the optional fourth test, you will need the ANNIE program (version 4.0, or later, available from http://water.usgs.gov/software/annie.html). E. 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.0 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 PEAKFQ is configured to be compiled with INTERACTER. INTERACTER is not a GKS library, but it is utilized by the DOS version of PEAKFQ through the use of code that substitutes appropriate INTERACTER subroutine calls for GKS subroutine calls. To compile PEAKFQ 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 PEAKFQ 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. F. RUNNING THE SOFTWARE If the option to modify the PATH environment variable was chosen during installation, PEAKFQ can be run in an MS-DOS Command Prompt window from any directory by typing "peakfq". 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\peakfq4.1\bin\peakfq" (note that quotation marks must be typed with and enclose any command name with spaces embedded). Alternatively, you can run PEAKFQ by selecting the PEAKFQ shortcut from the Start menu. The shortcut is found under Programs, in the Program Folder specified during installation (default: USGS). The shortcut will run PEAKFQ 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. Out of environment space error ------------------------------ This error can occur when running PEAKFQ, including when running the verification tests. The error occurs when there is insufficient space to hold a new environment variable definition. You can avoid this error by initiating a new command shell and specifying how much environment space you need. For example, in an MS-DOS Command Prompt window, typing command /e:1024 will initiate a new command shell with 1024 bytes of environment space. Environment space can be between 256 and 32768 bytes. The above command will increase the environment space for only the current Command Prompt window. To permanently increase your environment space, on Windows 9x/Me machines, click the MS-DOS icon in the upper-left corner of the Command Prompt window and select Properties. Select the Memory tab and increase the value in the Initial environment field. On Windows NT/2000/XP machines, add the above command to C:\winnt\system32\config.nt and initiate and use a new MS-DOS Command Prompt window. G. GRAPHICAL OUTPUT Graphical output is generated using version 5.0 of the INTERACTER graphics library from Interactive Software Services Ltd., which is bundled in with the program executable. Graphical output may be displayed on the screen, written to a printer file for subsequent printing on your printer, or written in various output formats for importing into other software packages, such as word-processing and desktop-publishing programs. For a partial listing of which software packages can import the output formats described below, see grexport.txt in the doc subdirectory. The menu choices presented to you for selection of a graphical output device will be: Screen, Laser, Plotter, and Meta. Screen ------ Plots are displayed in full-screen mode and remain on the screen for viewing 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. Laser ----- By default, a printer file formatted for your printer type will be produced and will be named interact.plt. Your printer type must be defined in the initialization file interact.ini (see below). To send a printer file to your printer, in an MS-DOS Command Prompt window, change to the directory containing the printer file and type one of the following commands: copy /b interact.plt lpt1 copy /b interact.plt \\\ where is the name of the computer within your local network to which the printer named is attached. Use the first command above if you have a printer attached to your PC, substituting the name of the port to which the printer is connected, if not lpt1. Graphical output is alternatively written in one of the output formats listed below if a file named TERM.DAT is present in the directory in which you are running PEAKFQ and it includes the "GKSPRT" parameter followed by one of four possible values: Line in TERM.DAT Output format Output file name ---------------- --------------------------- ---------------- GKSPRT 5 Encapsulated PostScript interact.eps GKSPRT 6 PostScript interact.ps GKSPRT 7 PC Paintbrush interact.pcx GKSPRT 8 Windows bitmap (compressed) interact.bmp Note that Encapsulated PostScript and PostScript files are intended for printing on PostScript printers and can be sent to a PostScript printer as described above for printer files. Prior to printing on a PostScript printer, Encapsulated PostScript files can be imported into many word-processing and desktop-publishing packages. Although the imported image will usually not be viewable but will instead only be represented as an empty frame, the image can, in most cases, be repositioned on the page, rotated, and scaled before printing. PC Paintbrush and Windows bitmap files can be imported into many word-processing and desktop-publishing packages. Plotter ------- A Hewlett-Packard Graphics Language file named interact.hpg will be produced which can be imported by some word-processing and desktop-publishing packages or can be sent to a pen plotter. The HP-GL file will be formatted for the plotter type defined in interact.ini. Meta ---- A binary Computer Graphics Metafile (CGM) named interact.cgm will be produced which can be imported by many word-processing and desktop- publishing packages. Modifying the text font ----------------------- The font used for plot titles, axes labels, etc. can be modified for each output device by assigning the values in the table below to the appropriate TERM.DAT parameter. Three parameters control the text font used in plots: GKSCFT specifies the screen and meta file font, GKPRFT specifies the printer font, and GKPLFT specifies the plotter font. In the table below, font 1 is a vector font, where each character is made up of a series of straight lines. The remaining fonts are outline fonts, where each character is drawn as an outline which is then filled as a polygon. Font 1 has a cleaner appearance at low resolutions, and has the cleanest appearance of all the fonts when displayed on the screen. The remaining fonts provide a better-looking result at higher resolutions. TERM.DAT value Font -------------- ------------------------------------------------------------ 1 sans serif (GKSCFT default) 2 sans serif, similar to Helvetica (GKPRFT and GKPLFT default) 3 sans serif, boldface, similar to Helvetica 4 serif, similar to Times Roman 5 serif, boldface, similar to Times Roman 6 monospace, similar to Courier 7 monospace, boldface, similar to Courier To illustrate the use of the above values, you would create a TERM.DAT file in the directory in which you are running PEAKFQ that contains the following 3 lines in order to use a Helvetica-like font in the screen display and meta file output, a Times-Roman-like font in printer output, and a boldface, Courier-like font in plotter output: GKSCFT 2 GKPRFT 4 GKPLFT 7 Note again that, depending on the video card and monitor of the PC, the quality of the screen display of plots--and especially the display of the plot text--may be improved on Windows 9x/Me machines by removing the "display=10" line from the interact.ini initialization file, 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. Important notes --------------- Note that graphical output written to, for example, interact.pcx, will overwrite any previously-generated PC Paintbrush output written to interact.pcx. To generate multiple graphical output files of the same format in a single program session, it is necessary to rename interact.* to a unique file name after each plot is generated. This can be done in My Computer, Windows Explorer, or in a second, separate MS-DOS Command Prompt window from that in which PEAKFQ is run. In My Computer or Windows Explorer, highlight the interact.* file you want to rename and select Rename from the File menu. In an MS-DOS window, use the rename command, as in, "rename interact.pcx plot1.pcx". Note also that changes made to the TERM.DAT file must be made prior to initiating a program session in order for those changes to take effect, but that changes can be made to interact.ini during a program session, in between the production of plots. Initialization file interact.ini -------------------------------- The file interact.ini is used to specify the printer and plotter type for which printer files and HP-GL files, respectively, will be formatted. An example interact.ini is included in the bin_data subdirectory and is copied into the current working directory upon execution of PEAKFQ, unless a file by the same name already exists. Modify the copy of interact.ini in the directory in which you are running PEAKFQ as described below to assign the appropriate values to the "printer" and "plotter" keywords. The value assigned to the "printer" keyword can be any one of the values below. If your specific printer is not listed below, consult the file printers.txt in the doc subdirectory to see which printer type below would be equivalent to your printer. Note that, in printers.txt, for the printers for which INTERACTER driver 2 is listed, PostScript or Encapsulated PostScript files should be generated; printer files cannot be generated for those printers. 2 - IBM Graphics printer 3 - Panasonic KX-P1081 4 - Amstrad DMP 3000 5 - Epson EX/FX/LX/RX 6 - Epson EX/FX/LX/RX (wide carriage) 7 - Epson MX-80 type II/III 8 - Epson MX-100 9 - Shinwa CP80 10 - HP LaserJet + 11 - HP LaserJet II 12 - IBM Graphics printer (wide carriage) 13 - HP PaintJet 14 - HP DeskJet and DeskJet+ 15 - IBM Proprinter 16 - IBM Proprinter (wide carriage) 17 - Epson LQ/SQ 18 - Epson LQ/SQ (wide carriage) 19 - IBM Proprinter X24 20 - IBM Proprinter X24 (wide carriage) 21 - HP DeskJet 500C or 310/color 22 - HP DeskJet 310/320/500/510/520 (monochrome) 23 - Epson JX/LX color 24 - Epson JX/LX color (wide carriage) 25 - Epson LQ color 26 - Epson LQ color (wide carriage) 28 - HP LaserJet III/4L 29 - HP LaserJet 4/5 30 - HP PaintJet XL 300 31 - HP DeskJet 550C/560C/660C 32 - HP DeskJet 1200C/1600C 33 - HP DeskJet 540/monochrome 34 - HP DeskJet 540/color 35 - HP Color LaserJet 36 - Epson Stylus 37 - Epson Stylus color 38 - HP Color LaserJet 4500/8500 The value assigned to the "plotter" keyword can be any one of the following values: 1 - Unspecified HP-GL compatible plotter 2 - Hewlett Packard 7475A using A4 paper 3 - Hewlett Packard 7475A using A3 paper 4 - Epson HI-80 with HP emulation ROM 5 - Facit 4550 A4 6 - Hewlett Packard 7440A A4 (HP Colorpro) 7 - Hewlett Packard 7550A using A4 paper 8 - Hewlett Packard 7550A using A3 paper 9 - Facit 4551 A4 paper 10 - Facit 4551 A3 paper H. 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 tests are run in the test subdirectory. The data subdirectory contains the input data and the expected results for each test. 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 PEAKFQ, if you did not install it in the default location): c: cd "program files" cd usgs\peakfq4.1\test After each test is completed, compare the results to the expected results using a file comparison utility such as fc. If all goes well, the only differences that may appear will be in test4.exp in the values for the attributes DATCRE and DATMOD--the dates of data-set creation and last modification, respectively, and in the date of program execution which is written to the test[1-3].out and interact.ps files referenced below. To clean up after the tests, type the command: clean Notes: a) Some of the tests may require input generated by a previous test, so they should be run in sequential order. b) Two of the tests require other programs, 1) test 0 requires the iowdm program (version 4.0 or later) 2) test 4 requires the annie program (version 4.0 or later) c) A copy of test.wdm has been provided which can be used as an alternative to running test 0 to create test.wdm. Prior to running tests 3 and 4, copy test.wdm into the test subdirectory by typing "copy ..\data\test.wdm". d) Test 1 and 2 can be run independently of the other tests. Run the tests by following the steps below. Test 0: - Type "iowdm" to execute IOWDM (if the PATH environment variable was not modified upon installation of IOWDM so that IOWDM can be executed from any directory, type the full path name of iowdmX.X\bin\iowdm, where X.X is the version number of IOWDM; for example, "c:\program files\usgs\iowdm4.0\bin\iowdm"). - On the opening screen, type "@". In the small panel that appears, type "..\data\test0.log". IOWDM will be run using the keystrokes in ..\data\test0.log as if they were typed in. - The files test.wdm, test0.out, and error.fil will be produced. (In addition to possibly containing error messages, error.fil contains a record of some of the program operations executed.) Compare test0.out and error.fil to their counterparts in the data subdirectory by typing: fc ..\data\test0.out test0.out fc ..\data\test0.err error.fil Tests 1-3: - Type "peakfq" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\testN.log" where N is the number of the test, 1-3. PEAKFQ will be run using the keystrokes in ..\data\testN.log as if they were typed in. When plots are displayed and remain on the screen for viewing, press the Enter key for the program to continue. If, after each test completes, 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. For test 2, note that, although graphical output is not displayed on the screen, it is written to an output file, and the screen display still gets switched into full-screen mode when the graphical output is produced. - The output files shown in the table below will be produced. Compare these files to their counterparts found in the data subdirectory. Note that the counterparts to the error.fil files are the testN.err files and that the counterparts to the interact.* files are the testN.* files having the same suffix, e.g., the counterpart to interact.pcx produced in test 2 is test2.pcx. Test 4: - Type "annie" to execute ANNIE (if the PATH environment variable was not modified upon installation of ANNIE so that ANNIE can be executed from any directory, type the full path name of annieX.X\bin\annie, where X.X is the version number of ANNIE; for example, "c:\program files\usgs\annie4.0\bin\annie"). - On the opening screen, type "@". In the small panel that appears, type "..\data\test4.log". ANNIE will be run using the keystrokes in ..\data\test4.log as if they were typed in. - The files test4.exp and error.fil will be produced. Compare these files to their counterparts in the data subdirectory by typing: fc ..\data\test4.exp test4.exp | more fc ..\data\test4.err error.fil 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. test program description of test and files file name & usage ---- ------- ------------------------------------- ----------------- 0 iowdm create and fill the wdm file command file test0.log i peak flows test0.pks i data management file test.wdm o summary of processed data test0.out o 1 peakfq flood frequency analysis with data from ascii file, no I records command file test1.log i peak flow input file test1.inp i output file test1.out o error file error.fil o 2 peakfq flood frequency analysis with data from ascii file, I records, basin characteristics saved to file command file test2.log i peak flow input file test2.inp i output file test2.out o last plot displayed, pcx interact.pcx o WATSTORE basin characteristics test2.bcd o error file error.fil o 3 peakfq flood frequency analysis with data from table data sets, test 0 required command file test3.log i data management file test.wdm i/o output file test3.out o error file error.fil o 4 annie exports data sets created in step 0 with attributes added in step 3. Used to confirm that all data was correctly placed in the data sets. command file test4.log i data management file test.wdm i/o archived data sets test4.exp o error file error.fil o I. UNINSTALLING To uninstall PEAKFQ, double-click Add/Remove Programs in the Control Panel, select PEAKFQ 4.1, and click the Add/Remove button. Any user files in the PEAKFQ installation directory--such as those created in the test or user subdirectories--will be left behind intact. J. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Hydrologic Analysis Software Support Program 437 National Center Reston, VA 20192 e-mail: h2osoft@usgs.gov