README                                                   March 1, 1996

                                ANNIE

     A Computer Program for Interactive Hydrologic Data Management

                 ANNIE - Version 2.2  1996/03/01


   annie2.2.DGUX.tar.gz   - Distribution prepared on a Data General
                            AViiON under DG/UX 5.4
   annie2.2.source.tar.gz - Distribution that includes the source code
                            but no compiled software

                          TABLE OF CONTENTS
                        
                          A. DESCRIPTION
                          B. DOCUMENTATION
                          C. EXTRACTING FILES
                          D  COMPILING
                          E. INSTALLING
                          F. RUNNING THE PROGRAM
                          G. TESTING
                          H. CONTACTS


A. DESCRIPTION

ANNIE is a program that helps users interactively store, retrieve, list, plot,
check, and update spatial, parametric, and time-series data for hydrologic
models and analyses.  ANNIE is written in Fortran and designed for portability
to a variety of computer platforms.  A binary, direct-access file is used to
store data in a logical, well-defined structure and is called a Watershed
Data Management (WDM) file.  Many hydrologic and water-quality models and
analyses developed by the U.S. Geological Survey and the Environmental
Protection Agency currently use a WDM file.  The WDM file provides the user
with a common data base for many applications, thus eliminating the need to
reformat data from one application to another.

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.  

   A postscript version of this report is available in the annie2.2/doc
   directory.  See the files annie.ps (does not include graphics pages)
   and annie_gr.ps (graphics pages 115, 119, 129, 133, and 139).


C. EXTRACTING FILES

Compressed tar files are used to distribute pre-compiled versions of the
software and the source code.  All of the files needed to install annie2.2
are contained in the files annie2.2.______.tar.gz (where ______ is a string
indicating the file contains either the source code or a pre-compiled
version of the program for the indicated operating system).  The source
version of the tar file contains the source code and all other files needed
to compile and install the software on a UNIX-based computer.  For either
type of distribution, the directory annie2.2 will be created (or overwritten)
when the files are extracted from the tar tape.  If the annie2.2 directory
already exists, you may want to delete or rename it before extracting the
files.  The following are the steps to extract the files from a distribution
tar file.

  Steps in extracting files                explanation
  ---------------------------------------  -----------------------------------
  mv annie2.2.____.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 annie2.2.____.tar.gz              Uncompress the distribution file.

  tar -xof annie2.2.____.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):

   annie2.2            copy of this README file
     `-----bin         compiled executable
     `-----bin_data    message file required during execution
     `-----doc         documentation files (see file Contents)
     `-----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
           annie2.2.source.tar.gz distribution; they are created during
           compilation.
        b) Source code is included only with the annie2.2.source.tar.gz
           distribution.
        c) It is recommended that no user files be kept in the annie2.2
           directory structure.  If you plan to put files in the annie2.2
           directory structure, do so only by creating subdirectories
           of annie2.2.
        d) The software is configured for installation under the
           directory /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.
        e) To compile a new version of the software, you will also need:
           (1) libraries and other data files from the lib3.0 library
           (lib3.0.______.tar.gz), (2) ANSI-compliant Fortran 77 compiler,
           and (3) a Graphical Kernel System (GKS) library.
     

D. COMPILING

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 if you want to build the executable yourself,
follow the instructions in this section.

The source code is provided in the annie2.2.source.tar.gz distribution 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, the requirements are ANSI-compliant Fortran 77 and a minimum
level of knowledge of the compiler and the UNIX operating system.  A
Graphical Kernel System (GKS) library is required.  Libraries and data files
from the lib3.0 distribution are also required.  As provided, the make
file, source code, and text version of the message file are set up for use
on Data General AViiON workstations running the DG/UX operating system.

To generate a new executable and message file, do the following:

1.  The values for the indicated variables in the following annie2.2 files
    may need to be modified (see the file annie2.2/doc/versions.doc for
    more details):

                               may need to be modified
                           -------------------------------
                            version     compiler
    file name              variables  flags  name  library
    ---------------------  ---------  -----------  -------
    src/Makefile           WrdA       FFLAGS  F77    LGks
        fmsgwd.inc         FNAME
    msg/wdimex.sh          WrdA
    test/test.sh           WrdA
         graph.sh          WrdA  Gks

2.  Run the Makefile program in the src directory to compile the source and
    build the message file.  In the directory annie2.2/src, run the make:

        cd annie2.2/src
        make

    The annie2.2/src/Makefile will:

        a.  Create the directories annie2.2/bin and annie2.2/bin_data,
            if they do not already exist.

        b.  Compile the source code and place the annie executable
            in the directory annie2.2/bin.

        c.  Run the wdimex.sh script in annie2.2/msg to build the message
            file (anmess.wdm); the file is placed in annie2.2/bin_data.


E. INSTALLING

To make the annie program easy to use, it should be installed in a directory
included in the user's search path.  The Makefile in annie2.2/src contains
instructions to optionally place a link in a specified directory to the
executable contained in annie2.2/bin.  Use the following commands to do this:

    cd annie2.2/src
    make install [BINDIR=bin_path]

where bin_path is the name of a directory in the user's search path.  If
BINDIR is specified, a link to the executable (annie2.2/bin/annie) is placed
in the specified directory.  If BINDIR is not specified, no link is set and
the full pathname of the executable is required to run the program.

For example, if the search path is /usr/bin:/usr/opt/bin:/usr/local/bin, you
can use the following command to install the program:

    make install BINDIR=/usr/local/bin

Notes:  a) Brackets "[xxx]" are used to indicate optional arguments
           to commands.
        b) To create and delete links to the annie executable, the installer
           must have sufficient rights to the BINDIR directory.


F. RUNNING THE PROGRAM

After the annie executable is properly installed (see Installing, above) in a
directory that is included in the user's PATH, the program can be executed
with the command "annie".


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 directory annie2.2/test contains the scripts to run
the tests.  The directory annie2.2/data contains the input data and the
expected results for each test.  Tests are usually run in the annie2.2/test
directory, but they can be run in any user directory.  Type the following
commands to test the user interface and wdm data base (test.sh) and the
graphics interface (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 annie2.2/test directory
                use full pathname if not running the test in annie2.2/test
        start = the number of the first test to perform
                default = 1
        stop  = the number of the last test to perform
                default = 3 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 graphics tests
     ./test.sh 1 1                          runs the first test test
     ./graph.sh 2 4                         runs graphics tests 2, 3, and 4
     /usr/opt/wrdapp/annie2.2/test/test.sh  runs all of the test tests

After the test and graph tests are completed, the results are compared to the
expected results (found in annie2.2/data).  See the file check.out; if all
goes well, there should be no differences.  If you are not using the Prior
library for GKS, you may find differences in the postscript files (graph_.ps).
To clean up after the tests, type the command:

     ./clean.sh

Notes:  a) Some of the tests may require input generated by a previous test,
           so they should be run in sequential order.
        b) The standard data sets were created on a Data General AViiON
           workstation.  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.

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.  Note that if the
implementation of GKS you are using does not support postscript output, the
graph_.ps files will not be output.

test      no.  program  description of test and files      file name & usage
--------  ---  -------  ---------------------------------  -----------------
test.sh    1   annie    create the wdm file, import two
                        files in the wdm export format

                        annie command file                 test1.log      i
                        data for Cane Branch               cane.exp       i
                        Illinois basin characteristics     il.exp         i
                        data management file               test.wdm       o

test.sh    2   annie    output to a file a table of
                        selected attributes for the
                        Cane Branch and Illinois data
          
                        annie command file                 test2.log      i
                        data management file               test.wdm       i
                        output table of attributes         test2.out      o

test.sh    3   annie    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

                        annie command file                 test3.log      i
                        data management file               test.wdm      i/o
                        archive file of new data sets      test3.exp      o

graph.sh   1   annie    time-series graph of Cane Branch
                        x - time
                        left y - discharge hydrograph
                        right y - evaporation
                        aux - precipitation
                        
                        annie command file                 graph1.log     i
                        data management file               test.wdm       i
                        postscript file                    graph1.ps      o

graph.sh   2   annie    time-series graph of Cane Branch
                        x - time
                        left y - discharge
                        aux - precipitation and evap

                        annie command file                 graph2.log     i
                        data management file               test.wdm       i
                        postscript file                    graph2.ps      o

graph.sh   3   annie    x-y graph of Cane Branch
                        x - monthly evap
                        left y - monthly precipitation

                        annie command file                 graph3.log     i
                        data management file               test.wdm       i
                        postscript file                    graph3.ps      o

graph.sh   4   annie    x-y graph of Cane Branch, check
                        for uneven no. of time series

                        annie command file                 graph4.log     i
                        data management file               test.wdm       i
                        postscript file                    graph4.ps      o


graph.sh   5   annie    x-y plot of the Illinois
                        basin characteristics
                        left y - P100 and    
                        x - DAREA
           
                        annie command file                 graph5.log     i
                        data management file               test.wdm       i
                        postscript file                    graph5.ps      o

graph.sh   6   annie    x-y plot of the Illinois
                        basin characteristics
                        left y - P100 and
                        right y - p1.25
                        x - DAREA
           
                        annie command file                 graph6.log     i
                        data management file               test.wdm       i
                        postscript file                    graph6.ps      o


H. CONTACTS

Inquiries about this software distribution should be directed to:

  U.S. Geological Survey
  Hydrologic Analysis Software Support Team
  Kathleen M. Flynn                           e-mail:  h2osoft@usgs.gov
  437 National Center                         phone:   703-648-5313
  Reston, VA  22092                           fax:     703-648-5722
