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



NNAAMMEE
       rr..wwaatteerr..ffeeaa   - Finite element analysis program for hydro-
       logic simulations.


       _(_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 technique.  Infiltration  is  calculated
       using the Green and Ampt formulation. rr..wwaatteerr..ffeeaa computes
       and draws hydrographs for every basin as well as at stream
       junctions  in  an  analysis  area. It also draws animation
       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 parame-
       ters  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 pro-
       ject 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 pro-
       ceed 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  independent  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  ani-
       mation  of  flow  depth	for all the basins that have been
       analyzed. All animation maps use a  multiplication  factor
       of 1000.  The map cell value divided by the multiplication
       factor yields the actual value of flow  depth  in  meters.
       The  user  will	require  enough  file  space in the GRASS
       database for this configuration. 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  cre-
       ated 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 number 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 signals 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  environ-
	 ment for the user to select basins in the area of analy-
	 sis. 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 informa-
	 tion 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 statis-
	 tics 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 parame-
	   ters. The simulation 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-sec-
	   tions.   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 col-
       umn should be in an increasing order. It is also not  nec-
       essary  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 com-
       mencement of rainfall (minutes) in the first  column  fol-
       lowed by the rainfall intensity (cm/hr) in the second col-
       umn 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 hydrograph 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 simula-
	    tion of all the basins. This file  contains   columns
	    of discharge for each basin. The column number corre-
	    sponds 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 parame-
	     ters.   This  choice can be used only after the suc-
	     cessful 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 provided to the model.



	      This part of the menu connects the basins that were
	      considered independent in the previous step.  Rout-
	      ing 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 con-
	      tains 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 val-
       ues 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, meander-
       ing 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 dis-
	      charge values. The first row specifies  the  stream
	      junction icon numbers.



NNOOTTEESS
       1. rr..wwaatteerr..ffeeaa alters the region in the _W_I_N_D file. This is
       done by making 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
       infiltration 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 anywhere 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 drastically.  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 resolution 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 analysis 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, con-
	      figuration 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 rainfall 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)
