README.txt

README file for the program READOUT
Copyright (C) 2004  Thorsten Pohlert

Contact:
Thorsten.Pohlert@agrar.uni-giessen.de

Make sure you have the SWAT2000 User's Manual (Chapter 32, pgs 325-330).

================================================================================

CONTENT

  1. WHAT IS READOUT?

  2. INSTALLATION

  3. STARTING READOUT

  4. WARNING

  5. IMPORT OF READOUT RESULTS INTO OTHER APPLICATIONS

  6. ERROR MESSAGES AND LIMITATIONS

  7. DE-INSTALLATION

  8. TO DO

  9. LICENSE (SHORT)

 10. DISCLAIMER (SHORT)

================================================================================

1. WHAT IS READOUT?

READOUT is a menu driven, interactive program to extract a variable of interest 
from the major SWAT2000 output files, namely basins.rch, basins.sbs 
and basins.bsb. You can extract one variable per subbasin/reach or 
HRU.

Since SWAT2000 output files may get very big (> 500 MB), SWAT users find it 
difficult to post-process their simulation runs. READOUT helps the user, to
extract and write the data of ONE variable of interest to a file. The output 
file of READOUT can easily be imported to spreadsheet applications.

Make sure you have the SWAT2000 User's Manual (Chapter 32, pgs 325-330).

================================================================================

2. INSTALLATION

WIN-2000,NT,XP
---------------------
READOUT was written in FORTRAN90 and was compiled as a console application
for MS-DOS under WIN2000, WIN-NT or WIN-XP. 

1. Download the zip-file "readout.zip" from the SWAT-homepage
   (www.brc.tamus.edu/swat/)

2. Unzip the file. You will get an executable file named

   READOUT.exe

3. Copy the executable file to the following directory 
   (Let us assume, "C:" is your partition,
   where WindowsNT is installed:

   C:\WINNT\system32

4. That's it.


INSTALLATION FROM SOURCE
------------------------
If you run SWAT2000 on UNIX or LINUX, you may wish to compile READOUT for
your machine. You need "make" for compilation.

1. Get the tar-file "readout.src.tar.gz" from the SWAT-homepage (see above).

2. Copy the tar-file in an installation directory (i.e. "readout") 
   
   mkdir readout
   cp readout.tar.gz /MY/PATH/TO/readout/readout.tar.gz
   cd /MY/PATH/TO/readout/

3. Unpack the tar-file:

   gzip -d readout.tar.gz
   tar -xf readout.tar

4. Check the "Makefile" for customization 
   (i.e. change the name and the options of the compiler).

5. For compilation and linking of READOUT run make:

   make

6. If you want to run READOUT from any directory, you have to copy/move the
   binary file READOUT to a directory within your shell-path (i.e. /usr/bin)
   NOTE: You have to be "root" to do so:

   cp /MY/PATH/TO/readout/READOUT /usr/bin/READOUT

7. Change the file permissions as apropriate (you have to be "root"):

   chown root READOUT
   chgrp root READOUT
   chmod ugo-wr READOUT
   chmod o+x READOUT

   The file permissions would look like that:
   ls -l READOUT

-r-xr-xr-x    1 root     root       432900 Mai 10 15:08 READOUT*

================================================================================

3. STARTING READOUT

Since READOUT is a console program, the interface is a
command line. Do the following clickings to open an MS-DOS Window:

|START|PROGRAMS|ACESSOIRES|COMMAND PROMT|

Now it's time to remember some essential DOS commands:

cd    Change directory
dir   Directory list
mkdir Create Directory (Folder)
copy  Copy a file
del   Delete a file
CRT-C Aboard the program
exit  Exit MS-DOS Session

Change with "cd" to your folder with the SWAT2000 output files.

Start the program with the command "READOUT". The READOUT session begins
with a welcome message like this:

===================================================================
Welcome to READOUT for SWAT2000
Copyright (C) 2004  Thorsten Pohlert

READOUT is a menu driven program to extract a variable of interest
from the major SWAT2000 output files, namely basins.rch, basins.sbs
and basins.bsb. You can extract one variable per subbasin/reach or
HRU.

(... to be continued!)


You will be guided through a READOUT session.
You can ABORT READOUT without savings at any time by enter CRT-C.

================================================================================

4. WARNING

Annual printout frequency
-------------------------
READOUT does not work, if you have selected "ANNUAL PRINTOUT FREQUENCY".
However, the SWAT2000 output files will not get so big with the above option,
thus READOUT is not necessary.

Customized basin.cod
--------------------
I successfully tested READOUT on customized basin.cod files.
Apparently, there was no problem with customized output.

Customized source code
----------------------
READOUT will DEFINITELY NOT WORK if you customized the FORMAT specifier for
the WRITE command of any of the following "writing" routines:

sbs[rch,bsb]aa.f  sbs[rch,bsb]day.f  sbs[rch,bsb]mon.f  sbs[rch,bsb]yr.f

You are free to use and modify the source code of READOUT, to meet
your requirements.

================================================================================

5. IMPORT OF READOUT RESULTS INTO OTHER APPLICATIONS

After a successfull READOUT session, you may want to import the results 
into a spreadsheet application or a graphic program to plot diagrams.

During the session you will be asked for a certain output format.
Each output file is ASCII-Format, but the field delimiter differs. You can
chose comma (","), semicolon (";"), gnuplot format or R format.

SPREADSHEETS
------------
The best formats for importing the output into a spreadsheet application are 
comma-separated-fields (",") for the English spoken countries and a semicolon 
(";") for non-English spoken countries (since (",") is the decimal delimiter 
in non-English spoken countries). This may work for importing READOUT files 
into OPEN-OFFICE, MS-EXCEL(R) and SPSS(R).

GNUPLOT
-------
The gnuplot format can be easily evoked by gnuplot. Assume you extracted
the FLOW_OUT variable for the reach 8 and wrote the result to the file
flowout08.txt, you will just need to type this command within gnuplot:

  > plot 'flowout08.txt' using 1:3 title 'Outflow from RCH 8' with line

This will produce a line diagram with the title "Outflow from RCH 8" where
field 1 (a counter) and 3 (the variable) are used.

To learn more about the free software package gnuplot, see 

   http://www.gnuplot.info/

R
-
For plotting and further statistical analysis of your SWAT2000 data you
may want to use the free statistical package R. You can select the R format
within READOUT, which enables an easy import into the R environment.
We assume again you selected FLOW_OUT from reach 8. To do a line plot, 
enter the following commands within R.

   > xx <- read.table("flowout08.txt") 
   > plot.default(xx[2], type="line", linetype="solid")
   
After you plotted your diagram, you can run statistical analysis within R. 
The command "summary" will produce an output of descriptive statistics like this:

   > summary(xx)
      MON         X.FLOW.OUTcms
 Min.   :  0.00   Min.   :0.000e+00
 1st Qu.: 91.25   1st Qu.:3.314e-06
 Median :182.50   Median :9.638e-04
 Mean   :182.50   Mean   :2.699e-02
 3rd Qu.:273.75   3rd Qu.:1.864e-02
 Max.   :365.00   Max.   :6.262e-01

where:
MON is the time (here: day of year) and X.FLOW.OUTcms is the discharge
leaving reach 8 of our virtual project.

You can do many more things with R, i.e. time series analysis,  
statistical testing, ... .

To get more information and a free download version of R, see:

  http://www.r-project.org/

================================================================================

6. ERROR MESSAGES AND LIMITATIONS

ERRORS
------
You will be guided throughout a READOUT session. The error messages are
almost self-explanatory. However, there might be some cases, when READOUT
aborts and a FORTRAN90 error message occurs. The most common one might
be the following one.

MSG:    Error 148: Invalid character
A:      You may have typed a "letter", instead of a "number". Start READOUT again
        and do your selections by typing the given digit, not characters.

MSG:    Error 530 : In program unit [unit] the size of array [array] exceeds the 
        implementation limit (2**31-1)
A:      I am pretty sure, you will never get this message (see below).


LIMITS
------
I carefully created READOUT with the use of the FORTRAN90 feature to
dynamically allocate RAM and the use of a "file-line-counter" with data
type REAL (some .bsb files may have more lines, then the range of INTEGER 
data types on a 32-BIT processor). However, there are some technical
limits, although of theoretical importance:

The 2,737-years-limit
-- The output FORMAT for the enumerator is set to 6 digits (max. Nr. 999999),
   which equals a SWAT2000 run with daily printout frequency of 2,737 years.
   If you intend to run SWAT2000 throughout the paleocene, you might want
   to change the FORMAT specifier in the writing subroutines :-).

The 2,939,744-years-limit
-- The data will be written into an array, which size may not exceed the range
   of the INTEGER data type (2exp31-1 on a 32-BIT processor). This equals
   a SWAT2000 run with a daily printout frequency of 2,939,744 years.
   If you run READOUT on a 16-BIT processor, the largest INTEGER number will
   be less (exactly 2exp16-1). I guess, you will have to recompile READOUT on
   such a processor, since it was compiled on a 32-BIT processor.

Memory runs out?
-- I successfully tested READOUT on a 750 MB output file. However, extracting
   data from such huge files may take several minutes. I realized, that
   my computer started to SWAP memory from the RAM to the harddisk. 
   The reason for this might depend on the operation-system and how
   it manages huge files, since READOUT does not use much RAM.

==================================================================================

7. DE-INSTALLATION

For de-installation of READOUT, simply use your file manager (i.e. MS Explorer(R))
and delete the binary file (READOUT.exe) from your installation folder.

================================================================================

8. TO DO

There are some things to do:

  - Expand the capability of READOUT, that the "HRU impoundment output file" (.wtr)
    and the "Reservoir Output File" (.rsv) can be extracted.

  - Expand the capability of READOUT, that averages for each variable and REACH/
    SUBBASIN can be computed. This might be useful, for linking the output to
    GIS.

================================================================================

9. LICENSE (SHORT)

READOUT for SWAT2000                        
Copyright (C) 2004  Thorsten Pohlert

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
at your option) any later version.


10. DISCLAIMER (SHORT)

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.