r.answers

NAME

r.answers - Menu-driven interface from GRASS to ANSWERS

SYNOPSIS

r.answers

DESCRIPTION

r.answers integrates ANSWERS (1991) with GRASS. ANSWERS (Areal Nonpoint Source Watershed Environmental Response Simulation) is an event oriented, distributed parameter model that was developed to simulate the behavior of watersheds having agriculture as their primary land use. Its primary applications are watershed planning for erosion and sediment control on complex watersheds, and water quality analysis associated with sediment associated chemicals.

r.answers provides a menu of steps to complete the input required to run an ANSWERS simulation. Each simulation is treated as "project" by r.answers. The inputs collected for the steps completed are recorded under a project name, so that they may be copied or recalled for further completion or modification. The first menu one encounters when running r.answers includes functions to create a new project, work on existing projects, copy an existing project, and remove existing projects. The main menu (shown below) lists steps to be completed to prepare ANSWERS input, to run ANSWERS, plus other miscellaneous functions.

   ANSWERS on GRASS Project Manager Main Menu Project Name:
   <sample>

 Status Option Description
--------------------------------------------------------- 
          0    Quit
          1    Set mask, region, and resolution
          2    Catalogue soils parameters
          3    Catalogue land use and surface parameters
          4    Identify elevation-based input layers
          5    Prepare rain gauge data
          6    Identify outlet cell
          7    Specify areas with subsurface drainage
          8    Catalogue channel parameters
          9    Define channel slopes
         10    Specify BMP's in watershed
         11    Prepare ANSWERS input and run simulation
         12    Miscellaneous Command Menu

 Option: 0__

Steps 1-11 record and display their status to the left of the step number. If a step has not been run, no status is displayed (as seen above). If the step has been successfully completed, the status will be listed as "done". In some cases, a change in one step will cause the need to run another step again, in which case the status will read "rerun". If a step has a status of "done" or "rerun", if it is run again it will attempt to offer previous inputs as defaults.

Interface Operation Notes Throughout r.answers two primary types of interface/input are used:

1) Text input that can be completed by hitting the RETURN key. In most cases, if no text was entered, the given question or operation is canceled. Often times text input will consist of the name of a new or existing map or project name, in which case entering the word "list" will provide a list of currently used names.

2) Text or menu options that can be completed by hitting the ESC (escape) key. This type of interface is used for menus or for entering tables of parameters. All menus have a default answer of Exit (0), so that by simply hitting ESC one may leave the program's menus. The following keystroke guide is helpful to know when using the parameter entry worksheets that use this interface:

<RETURN> moves the cursor to next prompt field
<CTRL-K> moves the cursor to previous prompt field
<CTRL-H> moves the cursor backward non-destructively within the field
<CTRL-L> moves the cursor forward non-destructively within the field
<CTRL-A> writes a copy of the screen to a file named "visual_ask" in your home directory
<CTRL-C> where indicated (on bottom line of screen) can be used to cancel operation

Description of Main Menu Steps

The following section describes each option of the main menu. All steps are verbose to provide as much immediate information as is practical, however it is necessary that the user also be familiar with the operation of ANSWERS. (Obtain a copy of the ANSWERS User's Manual (1991) by David Beasley and Larry Huggins. Available from Bernard Engel, Agricultural Engineering, Purdue University, W. Lafayette, Indiana, 47907).

Steps 1 through 10 collect inputs (either maps from the currently available mapsets or other text/numerical inputs) in order to create or extract the necessary portions of ANSWERS inputs for that step. After steps 1 through 10 are done, step 11 can be run to assemble an ANSWERS input file. ANSWERS can then be run using the inputs, and the output from the simulation is captured and processed, as described under step 11.

Step 1 Set mask, region, and resolution

Map input: Watershed mask
Other inputs: Project resolution, project region (optional)
Description: All raster values in the input mask map greater than zero will be used to create reclass rules to set the project MASK to the watershed area. Each time the project is called, the MASK will be automatically set. Project resolution is input in meters and it used to set the size of the watershed elements to be used in the simulation. The part of this step attempts to find the minimal region needed to contain the watershed mask at the given resolution. A region will be calculated to allow at least a one-cell border around the watershed area. This region is then presented in an input screen (much like that of r.region) for editing or approval. After the project mask, region and resolution are set, the information is recorded and will be reset automatically each time the project is called. This step will create a new raster map in the user's current mapset enTITLEd project name>.ELEMENT. This map will act as a reference to ANSWERS' methods of refering to raster cells. Raster values of the map will indicate element number, with the category description giving row and column numbers. If any of the inputs in this step are subsequently reset, all other steps that may have been completed will be marked with a status of "rerun", since changing mask, resolution or region will require that inputs will have to be resampled.

Step 2 Catalogue soils parameters

Map input: Soils
Other input: Soils parameters, tile drainage coefficient, groundwater release fraction.
Description: This step prompts for the name of a soil map, then reads the map and lists all soil categories found in the watershed mask. For each soil found in the watershed, ANSWERS requires values for the parameters listed below. The Project Manager facilitates preparation parameters by input into a table.

+------------------------------------------------------------------------+
|Soil Parameters for ANSWERS (see ANSWERS Users Manual for more details) |
+------------------------------------------------------------------------+
|1      total porosity (percent pore space volume of soil)               |
|2      field capacity (percent saturation)                              |
|3      steady state infiltration rate (mm/hour)                         |
|4      difference between steady state and maximum infiltration         |
|        rate (mm/hour)                                                  |
|5      exponent in infiltration equation                                |
|6      infiltration control zone depth (mm)                             |
|7      antecedent soil moisture (percent saturation)                    |
|8      USLE 'K'                                                         |
+------------------------------------------------------------------------+

After the soil parameters are input, a screen will prompt for groundwater release fraction and tile drainage coefficient, which will apply to the entire watershed. The tile drainage coefficient indicates the design coefficient (mm/day) of tile drains in those areas designated as having tile drainage. The groundwater release fraction is measure of the contribution of lateral groundwater movement or interflow to total runoff.

After this step is completed, it will provide an option to save the entered parameters to a file or printer for reference. ANSWERS soils inputs will then be extracted and stored. This step may be rerun to change any of the information. Previously entered information will be recalled and may be modified.

Step 3 Catalogue land use and surface parameters

Map input: Land cover/use.
Other input: Land cover parameters
Description: For each category in the land use map found in the watershed, ANSWERS requires values for the parameters listed below. The Project Manager facilitates preparation parameters by input into a table.

+-------------------------------------------------------------------------+
|Land Cover Parameters for ANSWERS (see ANSWERS Users Manual for details) |
+-------------------------------------------------------------------------+
|1      short (8 characters) description of land use and management       |
|       (program will attempt to use map category description, if any)    |
|2      mm of potential rainfall interception by land cover               |
|3      percentage of surface covered by specified land use               |
|4      oughness coefficient of the surface (a shape factor)              |
|5      m of maximum roughness height of the surface profile              |
|6      Manning's n (a measure of flow retardance of the surface)         |
|7      relative erosiveness (function of time and USLE 'C' and 'P')      |
+-------------------------------------------------------------------------+

After this step is completed, it will provide an option to save the entered parameters to a file or printer for reference. ANSWERS cover inputs will then be extracted and stored. This step may be rerun to change any of the information. Previously entered information will be recalled and may be modified.

Step 4 Identify elevation-based input layers

Map input: Slope and aspect.
Description: This step prompts for the names of previously prepared maps of slope and aspect for the project watershed. It is important to note that the required format of slope and aspect maps vary from that created by the r.slope.aspect program. Programs have been developed to process an elevation surface map and create ANSWERS slope and aspect map. The elevation map should be true elevations in meters. The elevation map can be "filtered" to remove "pits" and other potential problems to ANSWERS with the r.fill.dir program. The r.direct program can be used to prepare an ANSWERS aspect map from the elevation layer created by r.fill.dir. The r.slope.aspect program can be used to prepare an ANSWERS slope map from the elevation layer created by r.fill.dir. ANSWERS requires slope values which are percent multiplied by 10 (so a slope map value of 35 indicated a slope of 3.5%). The aspect map is a critical input to ANSWERS, since it defines the routing of runoff through the watershed, and should be carefully examined, since the r.direct program is unable to create flawless output. The d.rast.arrow and the d.rast.edit programs have been developed to assist this manual inspection and editing process. When editing the flow direction map, pay careful attention to 1) cells on the watershed border, which all must flow into the watershed. 2) cells that will be declared as "channels" must flow directly from one to another (therefore it is suggested that channels should be identified in conjunction with this step). 3) flow from two cells must not point directly to each other (-><-) or otherwise form circuitous routes. In the final flow map, one should be able to start at any cell in the watershed and follow the flow directions from cell to cell until arriving at the outlet cell.

Step 5 Prepare rain gauge data

Map input: Rain gauge areas (for multiple gauges)
Other input: Rain gauge data
Description: This step is designed to organize data used to describe the precipitation event to be simulated. ANSWERS permits up to four rain gauges to be used, each of which will require a table of rainfall data (time in minutes and rainfall intensity in millimeters per hour). Data from at least one rain gauge are required. If more than one gauge is used, you will need to prepare a raster map of the watershed area to indicate which cells are to represented by a given gauge's data.

To facilitate the modeling of a number of storms this step will prompt for a rainfall event name. The data tables entered will be stored in the ANSWERS database under the event name.

Rain gauge data for ANSWERS consists two columns of numbers. The first is Time (in minutes) and the second is Rainfall Intensity (in mm/hour). Decimal values will be rounded to the closest whole number. To input rain gauge data to the Project Manager, a file must first be prepared with rain gauge data. If multiple gauges are to be used, one input file is still used, data for each gauge are separated by '-1' flag in the "Time" (first) column. Data for multiple gauges should occur sequentially by gauge; so that data for gauge 1 is first in the file, data for gauge two is the second group of data, and so on.

Example rain gauge data input files:

        +----------+------------------------------------------+
        |one gauge |    two gauges                            |
        +----------+------------------------------------------+
        |  0    0  |  0          0                            |
        | 10    3  | 11          1          data for gauge 1  |
        | 20   10  | 25          7                            |
        | 35   22  | -1 <----- delimiter                      |
        | 55    9  |  0          0                            |
        | 67    4  | 15          6          data for gauge 2  |
        |100    0  | 10          4                            |
        +----------+------------------------------------------+

This step will prompt to determine if multiple rain gauges are to be used. If so, it will prompt for the name of a map that represents areas to be assigned to the given gauges. The number of categories and their value should match the number of rain gauges. Next the program prompts for the name of the rain gauge data file. The program reads the file and displays what it found to the screen for approval. Having this, it will create the appropriate ANSWERS input files.

Step 6 Identify outlet cell

Map input: none
Other input: row and column number of watershed outlet element
Description: ANSWERS needs to know the row and column number of the element at the watershed outlet. To facilitate your finding this information, The raster map <project name>.ELEMENT has been created. The category values of this map are the sequentially numbered cells of the watershed. The category descriptions are the cell's row and column number. Using a tool such as d.what.rast, the row and column number of the outlet cell can be queried from the displayed element map.

Step 7 Specify areas with subsurface drainage

Map input: Areas with subsurface drainage (optional)
Description: This step offers a menu which allows the delineation of 1) all the watershed with subsurface drainage, 2) none of the watershed with subsurface drainage, or 3) areas with subsurface drainage specified with a raster map (all elements with a value greater than zero will be input to ANSWERS as having subsurface drainage. Note: the drainage coefficient for areas with subsurface is set with the other soils parameters in step 2. If "all" or "none" of the watershed is simulated as having subsurface drainage, no input map is required; otherwise a raster map is used to specify areas with subsurface drainage.

Step 8 Catalogue channel parameters

Map input: Channels
Other input: Channel width and roughness coefficient for each category of channel
Description: Watershed cells with a well-defined channel should be defined to ANSWERS. ANSWERS assumes the channel is rectangular in cross-section and is sufficiently deep to handle runoff.

To prepare channel data for use with ANSWERS, the following is needed: a raster map layer of the channels in the watershed and a description of width (meters) and roughness (Manning's "n") for each channel category found in the layer.

It is suggested that the aspect map from Step 4 be created in conjunction with the channel map, since ANSWERS will abort operation if a one channel element does not flow directly into another adjacent channel element.

Step 9 Define channel slopes

Map input: Channel slope
Description: An optional input to ANSWERS is the slope of channels. If a channel slope input is not given, ANSWERS assumes the slope for the channel is the same as the overland slope for the element.

If desired, a raster map may be used to define channel slope values. To do so, a raster map should be prepared with category values for channel slopes in tenths of a percent (i.e. a category value of 31 would indicate a channel slope of 3.1 percent).

Note: Even though channel slopes are an optional input to ANSWERS, this step must be run if only to say no map will be used.

Step 10 Specify BMP's in watershed

Map input: Tile Outlet Terrace, Sedimentation Pond, Grassed Waterway, and/or Field Borders.
Other input: Grassed waterway or field border width (meters)
Description: This step provides a menu to prepare any or none of the four structural Best Management Practices (BMPs) that ANSWERS recognizes. Many BMPs can be described to ANSWERS by changing variables describing the surface condition of the soil. Practices which are tillage-oriented, for example, are described in the soils and land use sections. Gully structures such as a drop spillway may be simulated by reducing channel slope. On the other hand, BMPs which are structural in nature require a change in land use (row crop to grass for waterways, for example). ANSWERS recognizes four optional BMP structures. Even though the use of BMP structures is optional, this step still must be run to verify this. NOTE: Since ANSWERS will recognize one BMP for a given watershed element, the most effective BMP should be used. The following is a brief discussion of the BMPs:

1. ANSWERS Tile Outlet Terrace Assumptions:

- Trap efficiency of 90%
- Only lowermost terraces are described

Also, if a terrace exists only in a portion of an element, the assumption is made that all incoming flow is influenced by the BMP. Thus, elements which have only a small portion of the practice within their boundaries should not be given credit for the practice.

2. ANSWERS Sedimentation Pond Assumptions:

- Trap efficeincy of 95%
- Only ponds in upland areas should be defined. In stream structures are treated differently.

Also, if a pond exists only in a portion of an element, the assumption is made that all incoming flow is influenced by the BMP. Thus, elements which have only a small portion of the practice within their boundaries should not be given credit for the practice.

3. ANSWERS Grassed Waterway Assumptions:

- The vegetated area with in the affected element is no longer subject to any sediment detachment.
- The model deliberately prohibits deposition within the vegetation of a grass waterway, since any waterway that effectively traps sediment would soon fill and become ineffective.

For each category found in the layer, you will be prompted for width of the waterway

4. ANSWERS Field Border Assumptions

- The vegetated area with in the affected element is no longer subject to any sediment detachment.

For each category found in the layer, you will be prompted for width of the field border.

Step 11 Prepare ANSWERS input and run simulation

Description: Steps 1-10 must have a status of "done" before this step can be run. (Even steps for optional inputs must be run before an ANSWERS input file can be completed.) Each of the prior steps will have prepared their part of the ANSWERS input. The first function of this step is to compile all the parts together. Once the input file is complete, the simulation can be run. (NOTE: r.answers will call the ANSWERS program, which must be compiled as a part of the r.answers installation. The source code for ANSWERS should be part of the software distributed with r.answers.) The error messages that ANSWERS may send to "standard output" are captured to a file by r.answers and displayed. If none, a message to that effect will be printed to the screen (although this doesn't mean that the simulation ran entirely error-free). The primary output of the simulation is captured to another file, then processed to separate it into component parts of

1) text - the verbose reiteration of the inputs and summary of watershed characteristics. This is useful for checking to insure that inputs were read in by ANSWERS properly;

2) outlet hydrograph data of rainfall, runoff and sediment yield and concentration. If these data are in order, they will be processed into a format readable by the d.linegraph program for display;

3) individual element net sedimentation showing sediment loss or deposition, if any, for each raster element in the watershed.

Also, sediment deposition in channel elements. This step will prompt for names to use for new watershed maps it will create by extracting these data from the output. If the simulation event did not create sediment loss or deposition, or channel deposition for the scenario, the given map will not be created. To find out how to access the output files, see the description of step 12, below.

Step 12 Miscellaneous Command Menu

This step calls a menu that

1) allows access to the project files in the project database and to

2) a function that prepares a summary of the project's current status.

The project database is where r.answers stores all the inputs, output, and other non-map data associated with the project. See the "FILES" section (below) for more information. There are two sections to the project data, since rainfall data are kept in a separate directory. When using this step to access database files, the program will list both the project data and the rain data files, and ask which section you wish to access. Next you will be prompted for the name of the file to access. This request will be turned over to the "file handler program" which facilitates sending a file to the screen, copying to another file, or printing.

The project status function available under step 12 creates a helpful summary of the project, and then passes control to the "file handler program" for display, copying to a file, or printing.

FILES

Index of ANSWERS on GRASS database files

Each project will create and use the following files in $LOCATION/answers/<project name>/data. For the most part, there isn't much to see, unless something is not working right. If that is the case, The first thing to check would be files listed here under the Output section or Input file. Furthermore, attempting to fix a problem by editing any of these files could prove to have unpredictable results. Once a problem is identified (with the input maps or parameters, most likely) fix the input maps if need be, run r.answers again to make any changes, such a using a different map or correcting parameters. Remember that if a map is changed the menu step that uses it must be run again to resample the inputs. Run step 11 again to create a new input file and re-run ANSWERS.

General project data

reclass		reclass rules to create project MASK
region          project region coordinates

ANSWERS Input file

answers_input file created to use as input to ANSWERS

ANSWERS Output

When ANSWERS is run, output from stdout is sent to answers_output and anything that may go to stderr is captured in answers_error. After that the output is cut into sections. (if something unpredictable happened when ANSWERS ran, then the output and the files extracted from it may be garbled; reading answers_output and answers_error may provide clues).

answers_output  complete output from running answers
answers_error   errors captured when answers is run
out_chnl        channel deposition data
out_sediment    element sediment deposition/loss data
out_text        verbose input reiteration 
out_hydro       outlet hydrograph data

The outlet hydrograph data is broken into 5 files to use as input to d.linegraph

hydro_time      time increments of simulation (minutes)
hydro_rain      rainfall (mm/h)    
hydro_runoff    runoff at outlet (mm/h)
hydro_sed1      cumulative sediment at outlet (kg)
hydro_sed2      sediment concentration in runoff (mg/l)

ANSWERS Element data

Element data files are extracted from input maps. Each line is data for a watershed cell element. When answers input is created, these files are used to create the element data section.

in_row_col      watershed row and column number
in_soil         soil type
in_cover        land use
in_elev         slope and aspect
in_chnl         channel element data
in_rain         rain gauge number
in_tile         subsurface drainage flag

ANSWERS Predata

The following files are used to form the "predata" section of the answers input file.

chnl_predata    description of channel types
cover_predata   description of cover parameters
soil_predata    description of soil parameters
rain_predata    rain gauge data

Parameter data

These files are used by the project manager to "remember" parameters used to create the respective predata files, allowing the parameters to be read back by the program for editing.

chnl_data       channel parameters
cover_data      cover parameters
soil_data       soil parameters

AUTHOR

Chris Rewerts, Agricultural Engineering, Purdue University