OVERVIEW

Corrections (documented in source code) and installation improvements were made by Markus Neteler neteler@itc.it). 3.3.1998
This "Hannover" version of GRASS AGNPS 5.0 is available at http://www.geog.uni-hannover.de/phygeo/grass/agnps.html.

The WATERSHEDSS GRASS-AGNPS modeling tool was developed to assess nonpoint source pollution origination and movement in a watershed. Users with the appropriate GRASS map layers can simulate nutrient, sediment, and pesticide loads associated with various land management/use scenarios by running the input file generator and AGNPS model contained in the tool. Current land management/use within the watershed can be evaluated to identify source areas that contribute relatively high levels of pollutants to various points in the watershed. Other land management/use scenarios such as changing or moving cropping systems to different areas on the landscape may be assessed by modifying GRASS map layers and running the tool. Simulated pollutant yields from various scenarios may then be compared to provide estimates of pollutant reductions associated with changes in land management/use.

The modeling tool was designed to minimize user interaction and time in preparing the input data set for the AGNPS model while facilitating the input of essential, user-supplied data and the visualization of output. The input file generator was developed to provide the parameters needed for the latest version of AGNPS (5.0) and allow the user the option of entering characterization data for point sources, channels, and fertilizer and pesticide applications.

The modeling tool takes advantage of the speed and automation of the geographic information system (GIS), GRASS, to compute values for most of the AGNPS input. The input generator will prepare the 22 input parameters required for each cell from 8 to 11 basic user-supplied GRASS map layers and several parameters needed for the AGNPS model. Several map layers are optional depending on the user's preference and the desire to simulate pesticide movement. Additionally, specific information can be input for individual cells, if desired. User selected cell input can include data for characterizing feedlot and nonfeedlot point sources, natural and constructed runoff conveyance channels, and fertilizer and herbicide application rate and method. Convenient user-friendly screens are provided for input. The input generator then combines all the data into an input file for use by the AGNPS model.

The output from the AGNPS model can be viewed as 1) color GRASS maps displaying ranges of simulated contaminant yields for the entire watershed or 2) a summary table for any cell selected. For the maps, yields are divided into four ranges, each with a single color, while the tabular option displays the actual numeric output for the cell. Cell numbers are displayed on the maps for convenient reference.

While not required in all cases, a working knowledge of GRASS or another GIS and the AGNPS model is recommended before using the tool. Most GRASS commands are automatically called by the input file generator; however, in many cases the aspect or flow map must be edited manually using GRASS commands. A working knowledge of some GRASS commands is also needed to import and modify the required map layers, if they are not already available.

DOWNLOADING AND INSTALLATION

The following instructions are included to provide a general procedure for obtaining the software required to use the GRASS-AGNPS Modeling Tool. The instructions are not comprehensive; therefore, knowledge of operating systems, file transfer programs, and application software is needed.

GRASS-AGNPS input generator and output viewer: All the necessary source code, executable scripts, and a sample GRASS mapset are located in the tar archive named grass-agnps.tar and can be downloaded from the WATERSHEDSS web site. Simply click on the hyperlink labeled "grass-agnps.tar.Z" to initiate an anonymous FTP transfer to your UNIX workstation. Your Web browser should be set up for binary-mode FTP transfer. Alternatively, you can use any FTP utility in binary mode to do an anonymous FTP download from the WATERSHEDSS web site. After receiving the tar file, uncompress the file by entering [uncompress grass-agnps.tar.Z] then [tar -xvf grass-agnps.tar]. This should result in a directory entitled 'grass-agnps' with the following seven main subdirectories:

   src_agnps_input_1  (source code for the executable agnps_input_1)
   src_agnps_input_2a  (source code for the executable agnps_input_2a)
   agview             (source code for the executable agnps_view)
   hydro_tools        (source code for special GRASS hydrologic functions)
   scripts            (executable scripts)
   example            (test GRASS dataset from North Carolina)
   agnps_source       (source code and compiled executable for AGNPS 5.0)

GRASS version 4.2.1: GRASS 4.2.1 is the version of GRASS used in the GRASS-AGNPS modeling tool. If you do not already have GRASS 4.1 or 4.2.1, you may obtain it by clicking on the Web hyperlink labeled GRASS 4.2.1, or by GRASS Research Group (www.baylor.edu/~grass/). Download and install (compile if necessary) GRASS 4.1 on your UNIX/Linux workstation according to the instructions provided at that WWW site. For more information about GRASS visit the web page.

AGNPS version 5.0: The AGNPS 5.0 source is available within the directory agnps-source. The compiled executable called agrun500.out was compiled for the Solaris 2.x operating system. The source code should also be available from this site, if needed. Next rename the compiled version of AGNPS to r.agnps50.run to conform to the model executable named in GRASS-AGNPS input file generator. Then copy the file to the GRASS-AGNPS directory. If you install the "Hannover version" this all is done automatically.

Compiling and installing GRASS-AGNPS:

Check the first line of the
scripts/make_display_rules.pl
script to make sure that the path of the PERL utility on your UNIX workstation is correct, for example /usr/bin/perl. Type [which perl] to determine the correct path for your PERL utility if you are not sure.

Start the process with:

gmake4.2 (or gmake4.1)

This

 - compiles and installs the executable agnps_input_1
 - compiles and installs the executable agnps_input_2a
 - compiles and installs the executable agnps_views
 - compiles and installs the GRASS hydrologic functions      
      r.cn2, r.weighted.cn
 - copies scripts into etc/agnps50 subdirectory 
You must have a .cshrc in your directory with the following statement in the PATH-command: $GISBASE For example: path = ( . /usr/local/bin $GISBASE/bin $GISBASE/scripts $GISBASE/garden/bin (optimize this for your machine) Otherwise the csh-scripts of AGNPS won't work.

INPUT FILE GENERATOR

The GRASS map layers required by the input file generator include the watershed boundary, topographic, machine, C and K-factors from the USLE, nutrient/fertilizer application, land use, management practice map, hydrologic soil group, percent sand, percent clay, and, optionally, pesticide application rates. Eight of these maps can usually be created by changing the category labels/values of the soils and land use map layers using the [r.support] command of GRASS. All map layers must be in raster format with cell resolutions smaller than AGNPS cells. The following is a brief explanation of each map layer:

Watershed boundary (X.wshd): This layer should have a category value of 1 or greater within the watershed area and 0 outside the area. This layer defines the watershed or analysis boundary for all map layers. All other input layers must extend beyond the boundary of this layer.

Topographic (X.elev): Elevations in meters must be the category values for each cell. This layer must extend at least 2 cells beyond the watershed boundary all the way around so that slope and aspect at the watershed boundary can be estimated. Thus, if the user plans to model a cell size of 100 m, then the elevation map must extend at least 200 m beyond the watershed boundary in all directions, otherwise, errors may occur.

USLE K-factor (X.K): A raster map layer of the soil series map with K-factors as the category value for each map unit is required. GRASS routines divide or aggregate the map areas into cells based on the size of cell selected by the user. The following 3 maps (hydrologic soil group, percent sand, and percent clay) can often be created by copying [g.copy] the USLE K-factor map layer and editing the category values/labels using the [r.support] GRASS command.

Hydrologic soil group (X.hyg): Category labels of A, B, C, or D should be assigned to each map layer unit based on the hydrologic soil group of the soil in the unit.

Percent sand (X.sand): Category values should be the percentage of sand-sized particles in the soil of each map layer unit.

Percent clay (X.clay): Category values should be the percentage of clay-sized particles in the soil of each map layer unit.

Land use (X.luse): Each map unit should have one of the following category labels: fallow, row crops, small grain, rotation meadow, close-seeded legumes, pasture (poor), pasture (good), range, meadow, woods, hard surface, farmsteads, roads (dirt), water, and marsh. The (poor) and (good) designations are for the hydrologic condition and are used to determine the curve number.

Note: The following 5 map layers (fertilizer/nutrient application, machine, management practice, USLE C-factor, pesticide) can often be created by copying [g.copy] the land use map layer and editing the category values/labels [r.support].

Fertilizer/Nutrient application (X.nut): Category values should correspond to the level of fertilizer application where 0=none, 1=50 lb/ac N and 20 lb/ac P, 2=100 lb/ac N and 40 lb/ac P, and 3=200 lb/ac N and 80 lb/ac P. The user can also enter custom fertilizer application rates for individual cells via the interactive part of the tool, if desired.

Machine (X.mach): Each cell should have one of the following category labels: large offset disk, moldboard plow, lister, chisel plow, disk, field cultivator, row cultivator, anhydrous applicator, rod weeder, planter, smooth, or no till. Urban, water, marsh, and farmstead land use areas can be no till or smooth. These values are used to determine the fertilizer availability factor.

Management practice (X.mgpr): Each cell should have one of the following category labels: straight row, contoured, or contoured and terraced.

USLE C-factor (X.C): This map layer should contain the value of the USLE C factor as the category value for each cell.

Pesticide (X.pest): This data layer is optional. Up to three pesticide application scenarios (1, 2, 3) can be entered as category values. A scenario consists of a unique set of pesticide type, application rate and timing, and method.

Channel slope (X.chsl): This data layer is optional. The category values for each cell should be the channel slope in percent for each cell. The user also has the option of entering channel information for each cell individually in the interactive part of the input file generator. If the layer is missing, the channel slope is assumed to be 50% of the overland slope for each cell unless the user enters specific information in the interactive part of the tool.

Note: The X in the above map layer names should be replaced with the watershed name (ex: gaston). It is very important that each data layer extend at least to or beyond the watershed boundary; if it doesn't, errors may occur. Also, maps created in other GIS formats should use the UTM projection before conversion to GRASS.

In addition to the maps, several general watershed parameters must be known. These include rainfall depth and duration, area of each cell, and a short watershed description. Helpful hints about many of these parameters are provided in the following application procedure.

Application Procedure for Input File Generator

After successfully compiling the source code, the following procedure should be used when running the GRASS-AGNPS input generator:

1. Start GRASS by typing
[grass4.2].

2. Check the database, mapset, and location settings to make sure they correctly reflect the hierarchy of directories for the set of maps of interest. Open a graphics monitor by typing
[d.mon start=x1].
Reposition the monitor if desired. For large watersheds or those with a lot of cells (>100) maximize the size of the monitor. Start the input generator program by typing
[r.agnps50.input]
and hit [enter]. Hit [esc] to pass the cover page. If some of the text appears to be missing the UNIX window may be too small; resize it to show at least 25 lines and 82 columns.

3. An initial input menu will appear in the shelltool window with blanks or defaults for the following general information. Depressing the [return] key will move the cursor to the next input field. To correct a mistake, continue hitting enter until the cursor cycles back to the mistake and then simply retype the correct input. Depressing the [esc] key will enter the information and advance the program to the next screen.

a. Input filename: Enter a filename for the AGNPS input file. Be sure to enter the .dat extension (ex: test1.dat). This file will appear in the current working directory when a successful run is completed. After running the AGNPS model, the output files will have the same base name with different extensions (ex: test1.nps).

b. Watershed name: This is the filename without extension that is common to all the input map layers. Do not enter an extension (ex: gaston for gaston.wshd, gaston.nut, gaston.elev, etc.).

c. Watershed description: Enter a brief description of the watershed or simulation run. This optional information will be written to both input and output files for the AGNPS model run (ex: gaston_test).

d. Cell size: Enter the length of all sides of a cell in meters (ex: 100). Cell lengths should not be smaller than the resolution of the raster maps. Also, for optimum viewing of output maps, the cell size should be selected to result in less than 400 cells.

4. Precipitation and Model Parameters: (for detailed descriptions of the parameters and suggested values, consult the AGNPS manual)

a. Rainfall amount: Enter the total amount of rainfall for the storm (ex: 2.5) in inches. Do not enter values for frozen precipitation.

b. Storm type: Enter the storm type I, Ia, II, IIa, or III (ex: II). The value represents the type of synthetic 24 hour rainfall distribution being simulated. Type II represents distributions for most of the U.S.

c. Storm duration: Enter the duration of the storm in hours (ex: 8).

d. Energy intensity value: Enter the energy intensity value in English units for the storm/rainfall event of interest (ex: 30). If unknown, enter 0 and this number will be computed from the rainfall amount and storm type and duration.

e. Soil antecedant moisture condition: Enter 1 (dry), 2 (normal), or 3 (wet) for the antecedant moisture condition prior to the storm.

f. Nitrogen in precipitation: Enter the concentration of nitrogen in precipitation, if unknown use the default of 8 ppm (ex: 8 ppm).

g. Peak flow method: Enter the method for computing the peak flow, either SCS-TR55 or AGNPS. The SCS-TR55 option assumes a rectangular channel while the AGNPS option assumes a triangular channel. Type exactly as it appears in the choices (ex: AGNPS). If SCS-TR55 is selected, the user will need to provide channel widths and depths later.

h. Geomorphic calculations: Enter y or n. If yes, channel widths, depths, and lengths are computed based on geomorphic principles and relationships. Default geomorphic parameters will be provided.

i. Hydrograph shape factor: Enter K coef. or % Runoff for the method of calculating the triangular hydrograph (ex: K coef.).

j. K coefficient or % runoff: Enter the value to use based on which shape factor was selected (ex: 484). The % runoff is the percent of total storm runoff occurring before the peak flow rate occurs.

Notes. If there is no pesticide map layer in the input mapset, a warning message will appear twice. Ignoring this message by depressing [return] will not effect the analysis for other pollutants.

Error solving hints: The input file generator will create an initial aspect map based on the topographic map layer; however, the aspects often require editing. If the map needs editing, an error message will appear and the program will terminate. Common errors include cell collisions or more than one outlet cell. Then enter [d.rast] and the watershed name with ".asp.cell size" (e.g., gaston.asp.100 for a cell size of 100). The aspect map will appear in the graphics window. Next enter [d.rast.edit] and then at the prompt a new name for the aspect map (e.g. gaston.asp.100.new). Now use the mouse pointer to select aspect, agnps, and default. Edit the aspect arrows by following the instructions. Remember to make sure the cursor is within the UNIX window when entering a new aspect number in response to the questions.

After editing the aspect map, use the [g.remove] command to delete the old aspect map (gaston.asp.100) and then use [g.rename] to rename the new aspect map (gaston.asp.100.new) to the standard name (gaston.asp.100). Repeat the procedure above to run the input generator with the new map.

If any of the category labels/values for the input layers are not valid, an error message is printed and the program stops. Run [r.support] on the map layer where the category label/value is incorrect to edit it. The r.support function allows the user to modify the supporting files of a map, which include header, category, color, and history. Choose the category option to edit the labels/values.

During each run of the input generator, a temp_cell_num layer is created and stored in the current mapset. This map contains the cells numbered from left to right and top to bottom. This is a useful layer for editing and interpreting the error messages because it allows the user to locate the cell number where problems occur. It can be viewed using the d.rast command (ex: d.rast map = temp_cell_num).

5. If no other information is known about the watershed, then answer 'n' for no to the question of whether the user wants to enter data for specific cells and the input file generator will create an AGNPS input file based solely on the maps provided. However, if information about point source(s), channel characteristics, or fertilizer application rates is known, then answer 'y' and the input generator will prompt the user for the information.

6. When entering feedlot, channel, fertilizer, and pesticide data consult the AGNPS manual for an explanation of inputs. Otherwise the input screens should be self explanatory.

Point source of feedlot input: To enter the location of a feedlot, use the mouse to click on a cell in the map that appears automatically in the graphics monitor that was opened previously. Confirm your selection. Input the data required as explained in the AGNPS manual.

Channel input: If channel characterization data are available, enter "y" and "M" for locating the channel by clicking on the map and "D" for entering the number of the cell that contains the channel. Input the data by filling in the blanks with values as explained in the AGNPS manual. These data will write over any channel data already in the file.

Fertilizer input: Select cell similar to above and enter data as explained in the AGNPS manual.

Pesticide input: Enter data for each area identified on the pesticide map layer. Inputs are explained in the AGNPS manual.

7. Once the input file generator completes its execution without errors, the data is saved in an ASCII file in the AGNPS format. The file can be viewed using most UNIX editors. The AGNPS model can be executed with this input data file [r.agnps50.run]. The program will ask to make a model run. If the user answered yes or y, the AGNPS model will use the input file (ex: gaston.dat) and generate output files (ex: gaston.nps) based on the input. A GIS-formatted output file is not used; therefore, selecting "n" to the next question will not effect the user's ability to view the results.

8. The output of this or any previous runs can be viewed by answering "y" to the question concerning viewing the output; however, the user must enter the filename he/she wants to view without its .nps extension. After viewing the output, the program will return to the input generator so that additional runs can be made for other storms by simply entering a new filename and storm characteristic data.

OUTPUT VIEWER

The output viewer program extracts data from the .nps file created during an AGNPS model run and reformats and reclassifies the output data in order to display it as a GRASS map or a summary table. Model output can be viewed after each execution of the AGNPS model in the input file generator, or the viewer can be started as a stand alone program to view output files by entering
[r.agnps50.view]
while in the GRASS shell environment. In either case the name of the AGNPS output file to be viewed must be entered. The r.agnps50.view file should be in the same directory as the input generator executable (r.agnps50.input), the input file (.dat), and the output file (.nps). A GRASS graphics monitor must be opened by entering [d.mon start=x1] to use the graphics options of the viewer.

Application Procedure for Output Viewer

1. The file name of the watershed must be entered without its .nps extension (ex: gaston). The user then selects from the list of output options. Options 1-7 and 9-11 display GRASS maps of the selected output in the graphics monitor while options 8 and 12 print a table of summary data for the outlet cell of the watershed. It is usually recommended that the user views a map of the output first because the map displays the cell numbers for easy reference when using the table summary option. The user can then enter any cell number in the watershed and obtain summary data for that cell.

2. After selecting a map viewing option, the user must enter the cell size for the data file (ex: 100). This should be the same size as was entered in the input generator. A watershed map of values represented by colors will then appear. Each color represents a quartile of the range of values for the watershed. Due to limitations in the display functions, cells with output values of less than 0.01 will not be displayed in color; however, the cell number will be printed to mark the cell. Some cell numbers are white; therefore, they are not visible for cells which also have output less than 0.01 (the whole cell is white with no number). All output, except cell erosion and pesticide percolation, is for the amount leaving the cell which includes input from cells that drain to the cell. For summary table options, entering the cell size is unnecessary.

3. The user can then select other option numbers or, in the case of the summary table, enter other cell numbers or 0 to return to the options menu.

4. Entering 0 returns control to where the output viewer was started from, either the input generator or the GRASS shell.

After exiting the viewer, the user should execute the command [d.frame -e] to return the graphics monitor to its normal operation.