README.TXT
ANNIE
A Computer Program for Interactive Hydrologic Data Management
Version 4.1
2002/02/25
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 ANNIE.
Instructions for installation, execution, and testing are provided
below. After installation, see annie.txt in the doc subdirectory
for summary information on ANNIE.
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:
annie4.1.source.tar.gz - Source code only
annie4.1.Solaris.tar.gz - Compiled for Sun UltraSPARC-II under Solaris 2.6
B. DOCUMENTATION
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 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://water.usgs.gov/software/ordering_documentation.html for
information on ordering 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 annie4.1.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 files needed to compile and install the program on
a UNIX-based computer. For all of these distributions, the directory
annie4.1 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 annie4.1.____.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 annie4.1.____.tar.gz Uncompress the distribution file.
tar -xvpof annie4.1.____.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):
annie4.1 files NOTICE.TXT, RELEASE.TXT, and this README.TXT
`-----bin compiled executable
`-----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.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.
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 (77 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
distribution (version 4.0 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 F77 LGks
FFVrsn
Strip
LdA LdB
LdC
fmsgwd.inc FNAME
msg/wdimex.sh WrdA Libr
test/test.sh WrdA Anne
graph.sh WrdA Anne
Gks
2. Run make in the src directory to compile the source and build the
message file.
cd annie3.3/src
make
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,
d. run the wdimex.sh script found in the msg subdirectory to build
the message file (anmess.wdm); the file is placed in bin_data,
and
e. run the wdimex.sh script in the msg subdirectory to build the
test.wdm file; the file is placed in the data directory.
E. INSTALLING
To make the program easy to use, a link to the executable 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 executable 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 executable. Note that to create and delete links to
the executable, 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
"annie". Otherwise, the full pathname of the executable 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 user interface and wdm data base
(test.sh) and the graphics options (graph.sh):
[path]/test.sh [start [stop]]
[path]/graph.sh [start [stop]]
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 = 5 for test.sh
default = 6 for graph.sh
For example:
command what happens
-------------------------------------- --------------------------------
./test.sh runs all of the test tests
./graph.sh runs all of the graph tests
./test.sh 1 1 runs the first test test
./graph.sh 2 4 runs graph tests 2, 3, and 4
/usr/opt/wrdapp/annie4.1/test/test.sh runs all of the test tests
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) Graphics output files (.ps and .cgm) contain the date the
file was generated.
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 shell script
being used, 'no.' 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) Some of the tests may require input generated by a previous test,
so they should be run in sequential order.
b) If the implementation of GKS being used does not support
output files, the .ps and .cgm files will not be generated.
test no. description of test and files file name & usage
-------- --- --------------------------------- -----------------
test.sh 1 Create the wdm file, import two
files in the wdm export format
(must be run before tests 2-5).
command file test1.log i
data for Cane Branch cane.exp i
Illinois basin characteristics il.exp i
data management file test.wdm o
error file test1.err o
test.sh 2 Output to a file a table of
selected attributes for the
Cane Branch and Illinois data
(run after test 1).
command file test2.log i
data management file test.wdm i
output table of attributes test2.out o
error file test2.err o
test.sh 3 Use the generate options to
(1) compute inches of runoff
from cfs and (2) transform
15-minute discharge to 1-hour
discharge and then archive the
new data sets (run after test 1).
command file test3.log i
data management file test.wdm i/o
archive file of new data sets test3.exp o
error file test3.err o
test.sh 4 Test import and export of a
range of data values (run after
test 1).
command file test4.log i
data management file test.wdm i/o
archive import file test4.imp i
archive export file test4.exp o
error file test4.err o
test.sh 5 List time-series data (1) within
a specified range and (2) screen
for outliers and magnitude changes.
Table time-series data (run after
test 1).
command file test5.log i
data management file test.wdm i/o
time series listings test5.ot1 o
tabled time series test5.ot2 o
error file test5.err o
graph.sh 1 time-series graph of Cane Branch
x - time
left y - discharge hydrograph
right y - evaporation
aux - precipitation
command file graph1.log i
data management file test.wdm i
postscript file graph1.ps o
error file graph1.err o
graph.sh 2 time-series graph of Cane Branch
x - time
left y - discharge
aux - precipitation and evap
command file graph2.log i
data management file test.wdm i
postscript file graph2.ps o
error file graph2.err o
graph.sh 3 x-y graph of Cane Branch
x - monthly evap
left y - monthly precipitation
command file graph3.log i
data management file test.wdm i
postscript file graph3.ps o
error file graph3.err o
graph.sh 4 x-y graph of Cane Branch, check
for uneven no. of time series
command file graph4.log i
data management file test.wdm i
postscript file graph4.ps o
error file graph4.err o
graph.sh 5 x-y plot of the Illinois
basin characteristics
left y - P100 and
x - DAREA
command file graph5.log i
data management file test.wdm i
postscript file graph5.ps o
error file graph5.err o
graph.sh 6 x-y plot of the Illinois
basin characteristics
left y - P100 and
right y - p1.25
x - DAREA
command file graph6.log i
data management file test.wdm i
postscript file graph6.ps o
error file graph6.err o
H. 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