r.water.fea(1)		      Grass User's Manual		r.water.fea(1)



NNAAMMEE
       rr..wwaatteerr..ffeeaa   -	Finite element analysis program for hydrologic simula-
       tions.


       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..wwaatteerr..ffeeaa



OOVVEERRVVIIEEWW
       rr..wwaatteerr..ffeeaa is an interactive program that allows the user to  simulate
       storm  water  runoff  analysis using the finite element numerical tech-
       nique.  Infiltration is calculated using the Green  and	Ampt  formula-
       tion.  rr..wwaatteerr..ffeeaa  computes  and  draws hydrographs for every basin as
       well as at stream junctions in an analysis area. It also  draws	anima-
       tion maps at the basin level.



DDAATTAA RREEQQUUIIRREEMMEENNTTSS
       The maps required by rr..wwaatteerr..ffeeaa  are:


       1) Basin map
       2) Stream map
       3) Drainage map
       4) Accumulation map
       5) Slope map


       The other data requirements of rr..wwaatteerr..ffeeaa are the parameters needed to
       calculate infiltration  and  the  channel  roughness  parameter.  Model
       parameters may be provided either in the form of maps or as values:


       1) Manning roughness coefficient map or basin value
       2) Saturated hydraulic conductivity map or basin value
       3) Suction head at wetting front map or basin value
       4) Effective porosity map or basin value
       5) Degree of saturation basin value



DDEESSCCRRIIPPTTIIOONN
       On  running rr..wwaatteerr..ffeeaa for the first time, the directory _"_r_._w_a_t_e_r_._f_e_a_"
       is created under $LOCATION. When the user runs rr..wwaatteerr..ffeeaa, the program
       will  prompt  the user for the project name. The project name refers to
       the directory that is created under the	_"_r_._w_a_t_e_r_._f_e_a_"  directory.  All
       files (not maps) related to the analysis carried out by rr..wwaatteerr..ffeeaa are
       stored under this directory. If the project does  not  exist  then  the
       user  is  further  requested for the input maps. If the project already
       exists, then the program looks for the proper project related files  to
       proceed with stopped work.


       CCoonnffiigguurraattiioonn


       The  user is  asked for the following  configuration modes: I) Rainfall
       mode: The rainfall mode is defined as follows:


       1 = spatially uniform and constant in time
       2 = spatially uniform but varying in time


       If the user decides to use mode 2, then	a  mechanism  is  provided  to
       allow creation of a rainfall rate file (described in step 4).


       II) Basin-level hydrographs: This configuration mode allows the user to
       view intermediate hydrographs for every basin. The hydrographs will  be
       displayed on the graphics monitor. Each basin is considered to be inde-
       pendent of every other basin in the analysis area.


       III) Basin-level animation maps: This  configuration  mode  allows  the
       user  to  create time-series maps for later animation of flow depth for
       all the basins that have been analyzed. All animation maps use a multi-
       plication  factor of 1000.  The map cell value divided by the multipli-
       cation factor yields the actual value of flow depth in meters. The user
       will  require enough file space in the GRASS database for this configu-
       ration. All animation map names have the following naming scheme:


       fea..#


       Here '#' represents the time step. One time step refers	to  1/40th  of
       the  total monitoring time. Twenty maps are created at every other time
       step.


       PPrrooggrraamm ffllooww


       The basin and stream maps are displayed on the monitor  when  the  user
       starts working on a project. The entire analysis is divided into a num-
       ber of steps.  The user is presented with a menu to proceed through the
       set  of	steps to facilitate easy changes to the simulation for a given
       analysis area or to stop analysis between menu steps and continue at  a
       more convenient time.


       The main menu is shown below:




       Choose from the menu:




       *   1. Process steps without breaks.
       *->  2. Select basins for simulation.
       X   3. Extract topographical data.
       X   4. Select hydraulic parameters and simulation time.
       X   5. Basin simulation.
       X   6. Simulate any particular basin.
       X   7. Channel routing of basin hydrographs.
       *   8. Stop.




       You are starting from the beginning.


       Choice:


       The "X", "*", and "*->" above have the following meaning.



       * 8    The user can select this part from the menu.

       *-> 8  This  is	the step that the user must select in order to proceed
	      in a sequence.

       X 8    The user can not select these parts of the menu (until  previous
	      steps have been executed).




       Throughout  the	program the symbols described above change as the user
       moves from step to step.  The message just above the Choice prompt sig-
       nals  the  status of the program, and guides the user as to what should
       be the next step.





	This  part of the menu will not prompt for steps 2-5, 7 and will carry
	out  all  the analysis. The user will find it advantageous to use this
	step when analyzing a small area or a few basins.



	 This part of the menu draws the basin and stream maps for the user to
	 select the area of analysis. The mouse is then activated to provide a
	 point and click environment for the user to select basins in the area
	 of analysis. Upon successfully selecting the basins the user is given
	 the choice of deleting basins	from  the  selected  area.  The  basin
	 topology  is  then  determined and information on basin statistics is
	 gathered. The information on connectivity between basins is stored in
	 the  _"_i_n_p_u_t_._b_a_s_i_n_"  file  and	the information on basin statistics is
	 stored in the _"_b_a_s_i_n___i_n_f_o_" file.  Two	reclass  maps  describing  the
	 analysis  area  are  also created. The maps have the following naming
	 scheme:


       _"_f_e_a_._s_t_r_e_a_m_._"
       _"_f_e_a_._b_a_s_i_n_._"


       The user should avoid using these names	to  create  other  maps.  Once
       these  maps  are  created the user should not destroy them, if the user
       wishes to continue working on the project.



	  This part of the menu generates information about  the  connectivity
	  between cells and boundary conditions. This information is stored in
	  the _"_i_n_p_u_t_._f_i_l_e_" file in the project directory.   If	the  animation
	  configuration has been set then another file called _"_c_o_o_r_d_i_n_a_t_e_s_" is
	  created in the project directory. This file contains information  on
	  the coordinates of every cell in the analysis area.





	   This  part  of  the	menu  carries  out  two  tasks. The first task
	   involves querying the user for simulation parameters.  The  simula-
	   tion  parameters  include  duration of rainfall, maximum intensity,
	   time step for simulation, monitoring time and names	of  simulation
	   maps if any. The second task involves querying channel characteris-
	   tics assuming the channels as trapezoidal cross-sections.  The user
	   is required to provide channel side slope, channel bottom width and
	   the channel roughness coefficient values for every stream category.


       The program creates a file _"_t_i_m_e_d_a_t_a_" in the project directory to store
       information from this part of the menu. If the user  has  selected  the
       "Spatially uniform and time varying rainfall" mode (mode = 2), then the
       user is queried for the the name of a time file. If the file  does  not
       exist then a screen like the one shown below appears:



       center;
       l l l.
       ------------------------------------------------------------------
				      Rainfall data
				      -------------
       [The time column must be filled in increasing order.]

			    Time[minutes]	 Intensity[cm/hr]

	   1			______		    ______
	   2			______		    ______
	   3			______		    ______
	   4			______		    ______
	   5			______		    ______
	   6			______		    ______
	   7			______		    ______
	   8			______		    ______
	   9			______		    ______
	  10			______		    ______
	  11			______		    ______
	  12			______		    ______
	  13			______		    ______
	  14			______		    ______
	  15			______		    ______
       c s s s
       c s s s
       l l l l.
       AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
       (OR <Ctrl-C> TO CANCEL)
       ------------------------------------------------------------------






       It  is  important to note  that the values in the time column should be
       in an increasing order. It is also not necessary to fill all  the  rows
       and  the  user  can  stop  after filling only a few rows. The number of
       lines are limited to fifteen. If more than fifteen lines  are  required
       then  the  user	will  have to create the file using an editor. In that
       case the user should just type the time since commencement of  rainfall
       (minutes)  in  the  first  column  followed  by	the rainfall intensity
       (cm/hr) in the second column as shown below:



       center;
       l l
       l c.
       10   2.54
       30   4.52
       60   5.62







	    This part of the menu carries out the simulation for each basin in
	    the  area  of  analysis. Every basin is analyzed as independent of
	    every other basin.	The user is shown the independent basin hydro-
	    graph   for   every  basin	on  the  graphics  monitor.  The  file
	    _"_d_i_s_c_h_._b_a_s_i_n_" is created  towards the end of simulation of all the
	    basins.  This  file contains  columns of discharge for each basin.
	    The column number corresponds to the basin category value  in  the
	    legend. If the animation configuration mode was set then a file is
	    created in the project directory called _"_d_i_s_c_h___f_i_l_e_"_.   This  file
	    holds  basin discharge values at every point in every basin of the
	    analysis area.



	     This part of the menu provides the  facility  of  changing  basin
	     characteristics  such  as	the  Manning roughness coefficient and
	     other infiltration parameters.  This  choice  can	be  used  only
	     after  the  successful  completion  of choice 5.  If the user has
	     provided maps for the parameters  then  the  user	should	select
	     "stop"  from  the menu to make changes to the parameter maps pro-
	     vided to the model.



	      This part of the menu connects the basins that  were  considered
	      independent  in  the  previous  step. Routing of the basin-level
	      hydrographs is done based on the	connectivity  between  basins.
	      This  can  generate hydrographs only for seven stream junctions.
	      If there are more than seven stream  junctions  then  the  first
	      seven  stream  junction  hydrographs  are  shown. The process of
	      drawing individual basin animation maps follows the  drawing  of
	      the  hydrographs	at  stream  junctions.	 After completing this
	      choice a file _"_d_i_s_c_h_._j_u_n_c_t_i_o_n_" is created.  This	file  contains
	      discharge values at different steps for every stream junction.



	       This  part  of  the  menu  is available to the user at any time
	       between the different choices described in the menu  and  exits
	       the user out of the program.




LLIIMMIITTAATTIIOONNSS
       1.)  Negative values of drainage direction inside basins maps cannot be
       accepted. Negative values are  generated  as  a	result	of  incomplete
       information  regarding  the  basin  drainage pattern (e.g., rr..wwaatteerrsshheedd
       produces negative values as a result of outflowing drainage basins).


       2.) The drainage map should route the water and not form  pits,	lakes,
       or  ponds.  Note that this does not imply that the DEM by itself should
       not have any pits.


       3) Interstorm modeling, interflow, or baseflow are not considered.


       4) Backwater effects are not considered.


       5) The kinematic wave analogy is appropriate  where  the  land  surface
       slope and channel slope are large. This may not be true in flat, marshy
       terrain and in slow, meandering river channels.



OOUUTTPPUUTT FFIILLEESS OOFF IINNTTEERREESSTT
       These are ASCII files that can be found in the _"_$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_"
       directory.   The  files	have  a format such that it can be imported to
       various analysis packages.



       _d_i_s_c_h_._b_a_s_i_n 8
	      This file contains multiple columns which contain the individual
	      basin  discharge	values in order of first column containing the
	      discharge values for basin one and the second for basin two  and
	      so on.



       _d_i_s_c_h_._j_u_n_c_t_i_o_n 8
	      This file contains the results of the discharge values at stream
	      junctions specified by the icons. The first column in this  file
	      shows  the  time	step in minutes. The remaining columns specify
	      the discharge values. The first row specifies the  stream  junc-
	      tion icon numbers.



NNOOTTEESS
       1. rr..wwaatteerr..ffeeaa alters the region in the _W_I_N_D file. This is done by mak-
       ing a systems call to:


       g.region align=name


       just when the program rr..wwaatteerr..ffeeaa is run.


       2. A small watershed can be  analyzed  by  providing  values  of  model
       parameters.   However  it  is advisble to provide maps of various model
       parameters if there are many basins in the watershed.   In  the	former
       case  the  value  provided by the user shall be constant for the entire
       basin for which the value is queried. The user shall create the	infil-
       tration maps using the following set of rules. The map value divided by
       the multiplication factor yields the  actual  value  in	the  described
       units:



       center tab(:);
       ll
       lc.
       Parameter:Multiplication factor





       Soil saturated hydraulic
       conductivity map (meters/sec):10,000,000





       Manning roughness coefficient:1000





       Soil suction at wetting front (m):1000





       Soil porosity map (m3/m3):1000






       3.  If the user has provided a slope map that has zero slope value any-
       where in the map, then a slope value of 5% is assumed for that cell.


       4. It is preferred that none of the basins in  the  analysis  area  has
       more than 750 cells, as this will increase the computation time drasti-
       cally.  The number of cells in a basin can be controlled by setting the
       threshold value to small values when running rr..wwaatteerrsshheedd.


       5.  Using larger cells can speed up the analysis process significantly.
       It is important to note that rr..wwaatteerrsshheedd should be run for the  resolu-
       tion at which the user desires to run the rr..wwaatteerr..ffeeaa analysis.



FFIILLEESS
       All  the files listed below are ASCII files. None of these files should
       be deleted if the user wishes to continue working on the same  project.



       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_i_n_p_u_t_._b_a_s_i_n 8
	      This file contains information on connectivity between different
	      basins in the analysis area.

       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_i_n_p_u_t_._f_i_l_e 8
	      This file contains information on connectivity between different
	      cells for every basin in the analysis area.

       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_d_i_s_c_h_._b_a_s_i_n 8
	      This file contains discharge values for every basin in the anal-
	      ysis area.

       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_d_i_s_c_h_._j_u_n_c_t_i_o_n 8
	      This file contains discharge values at every stream junction  in
	      the analysis area.

       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_t_i_m_e_d_a_t_a 8
	      This file contains the response querried from the user in choice
	      4 of the menu.

       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_b_a_s_i_n___i_n_f_o 8
	      This file contains information on statistics of  the  basins  in
	      the analysis area.

       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_c_o_o_r_d_i_n_a_t_e_s 8
	      This  file  contains information on coordinates of every cell in
	      the analysis area.

       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_c_o_n_t_r_o_l 8
	      This file  contains  information	on  map  names,  configuration
	      modes, and stopped choice in the menu.

       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_d_i_s_c_h___f_i_l_e 8
	      This  file  contains  the discharge values at every point in the
	      analysis area.

       _$_L_O_C_A_T_I_O_N_/_r_._w_a_t_e_r_._f_e_a_/_/_t_i_m_e_f_i_l_e_s_/ 8
	      This file contains the spatially constant and time variant rain-
	      fall mode file.




RREEFFEERREENNCCEESS
       Finite element methodology used by r.water.fea is described in
       Vieux,  B. E., Bralts, V. F., Segerlind, L. J., Wallace, R. B., (1990),
       "FINITE ELEMENT WATERSHED MODELING:  ONE-DIMENSIONAL ELEMENTS",	J.  of
       Water Resources Planning and Management, Vol. 116, No. 6, p803-819.



SSEEEE AALLSSOO
       _r_._s_l_o_p_e_._a_s_p_e_c_t

       _r_._w_a_t_e_r_s_h_e_d

       _r_._m_a_s_k

       _r_._r_e_c_l_a_s_s

       _r_._s_t_a_t_s

       _r_._c_o_l_o_r_s

AAUUTTHHOORR
       Baxter E. Vieux, University of Oklahoma, Norman
       Nalneesh Gaur, University of Oklahoma, Norman

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0							r.water.fea(1)
