**Note** To run this program, you must have this file: file.cio And at least one of these files: output.rch output.sub output.hru README.txt README file for the program READOUT Copyright (C) 2004 Thorsten Pohlert Contact: nsammons@spa.ars.usda.gov - Nancy Sammons Thorsten.Pohlert@agrar.uni-giessen.de Make sure you have the SWAT2005 User's Manual (IO_DOC - Ch32_output.doc). ================================================================================ 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 SWAT2005 output files, namely output.sub, output.rch and output.hru. You can extract one variable per subbasin/reach or HRU. Since SWAT2005 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 SWAT2005 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 SWAT2005 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 SWAT2005 output files. Start the program with the command "READOUT". The READOUT session begins with a welcome message like this: =================================================================== Welcome to READOUT for SWAT2005 Copyright (C) 2004 Thorsten Pohlert READOUT is a menu driven program to extract a variable of interest from the major SWAT2005 output files, namely output.sub, output.rch and output.hru. 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 SWAT2005 output files will not get so big with the above option, thus READOUT is not necessary. Customized file.cio -------------------- I successfully tested READOUT on customized file.cio 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 SWAT2005 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 SWAT2005 run with daily printout frequency of 2,737 years. If you intend to run SWAT2005 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 SWAT2005 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 SWAT2005 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.