
NAME r.hydro.CASC2D - GRASS raster command to execute fully integrated
distributed hydrologic modeling.

SYNOPSIS r.hydro.CASC2D, r.hydro.CASC2D help, 
   r.hydro.CASC2D [-toepidbuq] elevation=name time_step=value 
   tot_time=value discharge=name outlet_eastNnorthNslope=east,north,bedslope 
   rain_duration=value [watershed_mask=name] [initial_depth=name]
   [storage_capacity=name] [interception_coefficient=name] [roughness_map=name]
   [Manning_n=value] [conductivity=name] [capillary=name] [porosity=name] 
   [moisture=name] [pore_index=name] [residual_sat=name] [lake_map=name]
   [lake_elev=name] [radar_intensity_map=name] [links_map=name]
   [nodes_map=name] [channel_input=name] [table_input=name] [dis_profile=name]
   [wat_surf_profile=name] [hyd_location=name] [r_gage_file=name]
   [unif_rain_int=value] [num_of_raingages=value] [gage_time_step=value]
   [radar_time_step=value] [write_time_step=value] [unit_el_conv=value]
   [unit_lake=value] [unit_space=value] [d_thresh=value]
   [dis_hyd_location=name] [depth_map=name] [inf_depth_map=name]
   [surf_moist_map=name] [rate_of_infil_map=name] [dis_rain_map=name]

NOTE: In above, the command line arguments have been rearranged so that the 
required parameters are placed first. When doing "r.hydro.CASC2D help", the user
will see a different sequence of parameters. 

DISCLAIMER: The r.hydro.CASC2D model is Copyleft 1994 by B. Saghafian and F. L.
Ogden. There are absolutely no warranties, expressed or implied, made regarding
the accuracy of the results produced by this program. Use of this program is
allowed as long as the original developers are properly acknowledged.  No part
of this document describing the use of the model may be used or duplicated
without a complete citation.  Users with no background in or understanding of
distributed hydrology are strongly advised against using this code in any mode,
particularly in operational mode.  Besides knowledge of basic hydrology, 
experience with typical numerical techniques used in physically-based  
hydrodynamic models is recommended as it will help the user grasp capabilities
and limitations of this model.  This manual is significantly condensed and is 
in no way comprehensive.  Users are encouraged to experiment with the model and
venture in hydrology textbooks and journal papers to learn more about the topics
touched upon in this manual.  The r.hydro.CASC2D code is continuously being 
improved.  Changes in the source code of r.hydro.CASC2D may be made at any time,
without notification.  No claims are made regarding the suitability of
r.hydro.CASC2D for any particular purpose.  The model r.hydro.CASC2D was
written for research and educational purposes. Use r.hydro.CASC2D at your own
risk.

HISTORY: CASC2D originally began with the two-dimensional overland flow routing
algorithm developed in APL by Prof. P.Y. Julien at Colorado State University.
The overland flow routing module was converted from APL to FORTRAN by Bahram
Saghafian, then at Colorado State University, with the addition of Green & Ampt
infiltration and explicit channel routing (Julien and Saghafian, 1991,
Saghafian, 1992, and Julien et al., 1995). The Fortran version was
reformulated, significantly enhanced, and re-written in the C programming
language by Bahram Saghafian at the U.S. Army Construction Engineering
Research Laboratories.  Implicit channel routing code was developed and added
to r.hydro.CASC2D by Fred L. Ogden (Ogden, 1994), formerly at Colorado State
University, now Asst. Professor, Department of Civil and Environmental
Engineering, University of Connecticut, Storrs, Connecticut.  This version
became known as r.hydro.CASC2D, part of the GRASS GIS for hydrologic
simulations (Saghafian, 1993).

DESCRIPTION: r.hydro.CASC2D is a physically-based, distributed, raster
hydrologic model which simulates the hydrologic response of a watershed
subject to a given rainfall field. Input rainfall is allowed to vary in space
and time. Major components of the model include interception, infiltration,
and surface runoff routing.  Interception is a process whereby rainfall is
retained by vegetation.  Interception is estimated using an empirical three
parameter model.  Infiltration is the process whereby rainfall or surface water
is pulled into the soil by capillary and gravity forces. The Green and Ampt
equation with four parameters is applied to model the event-based infiltration.
For continuous soil moisture accounting, redistribution of soil moisture can
also be simulated whenever the non-intercepted  rainfall intensity falls below
the saturated hydraulic conductivity of the soil.  The redistribution option
requires two more soil hydraulic parameters.  Excess rainfall becomes surface
runoff and is routed as overland flow and subsequently as channel flow. The
overland flow routing formulation is based on a two-dimensional explicit
finite difference (FD)  technique, while two different FD techniques, one
explicit and one implicit, provide options for routing one-dimensional channel
flow. Through a step function, a depression depth may be specified, below
which no overland flow will be routed.

The following sections describe various aspects of the model. In executing the
model, the likelihood of making a serious mistake by an inexperienced user is
unfortunately very high due to complexity of input and output options. Thus
the user must thoroughly read all the details of this manual and then select
appropriate options for his or her needs.  Since at this time GRASS is an
integer GIS, all input maps are stored in integer form.  This requires
conversion from integer to floating point representation via a scaling factor. 
The scaling factor for all floating point values is fixed.  Therefore, the
integer maps of parameter values are created by multiplying floating point
values (e.g. volumetric water content) by a multiplier.  

PARAMETERS/OPTIONS: The following input/output parameters/options control
complexity of the simulation.  Map and file names in square brackets [] are
optional.  Some maps are mutually exclusive ( logical -or- ), while some maps
require other maps to enable proper function ( logical -and- ).   Carefully 
read the NOTES section.

INPUT
-----------------------------------------------------------------------------

_____TOPOGRAPHY_____
elevation=mapname              map of elevation (DEM).

outlet_eastNnorthNslope=       easting, northing, and bed slope at the outlet
value,value,value              cell comma delimited.

_____TIME_____
time_step=value                computational time step duration in seconds.
                               (typ. 1 to 30 seconds)

tot_time=value                 total simulation time in sec.

_____OVERLAND FLOW_____
[Manning_n=value]              spatially uniform Manning's n roughness
                               value for overland flow.
-or-

[roughness_map=mapname]        spatially varied map of Manning's n roughness
                               coefficient (values in 1000*Manning's n).

[watershed_mask=mapname]       map of watershed boundary (or mask).  This 
                               option is recommended, as it speeds execution
                               greatly.

[d_thresh=value]               threshold overland depth, in meters, below which
                               overland routing will not be performed (i.e. 
                               average depression storage).

[initial_depth=mapname]        map of initial overland (not lakes) depth in mm.

_____RAINFALL_____

rain_duration=value            total rainfall duration in sec.

[unif_rain_int=value]          spatially uniform rainfall intensity in mm/hr.

-or-

  [r_gage_file=filename]       raingage rainfall input file name (ASCII).

  -and-

  [num_of_raingages=value]     number of recording raingages.

  -and-

  [gage_time_step=value]       time step of recorded raingage data in sec.

-or-

  [radar_intensity_map=mapname]   prefix of time series of maps of radar- 
                                  (or otherwise-) generated rainfall
                                  intensities in mm/hr.
  -and-

  [radar_time_step=value]         time increment between radar- (or otherwise-)
                                  generated rainfall maps in sec.

[_____INTERCEPTION_____]

[storage_capacity=mapname]        map of vegetation storage capacity in tenths
                                  of mm.
-and-

[interception_coefficient=mapname] map of interception coefficient (values in
                                   1000*actual coefficient).


[_____INFILTRATION_____]


[conductivity=mapname]         map of soil saturated hydraulic conductivity in
                               tenths of mm/hr (Req'd for G&A and Redist).

[capillary=mapname]            map of soil capillary pressure head at the
                               wetting front in tenths of mm (Req'd for G&A and
                               Redist).

[porosity=mapname]             map of soil effective porosity (values in
                               1000*porosity) (Req'd for G&A and Redist).

[moisture=mapname]             map of initial soil moisture (values in
                               1000*moisture) (Req'd for G&A and Redist).

[pore_index=mapname]           map of soil pore-size distribution index (Brooks
                               & Corey lambda) in 1000*index (Req'd for Redist).

[residual_sat=mapname]         map of soil residual saturation (values in
                               1000*residual saturation) (Req'd for Redist).

[_____LAKES_____]

[lake_map=mapname]             map of lakes categories.

[lake_elev=mapname]            map of lakes initial water surface elevation
                               (also see unit_lake).

[_____CHANNEL ROUTING_____]

[channel_input=filename]       channel input data file name (ASCII), required
                               for explicit (EX) and implicit (IM) channel 
                               routing methods.

[links_map=mapname]            map of channel network link numbers. (EX & IM)

[nodes_map=mapname]            map of channel network node numbers. (EX & IM)

[table_input=filename]         look-up table file for links with breakpoint 
                               cross section, link type 8, (ASCII) (IM) 

[dis_profile=filename]         channel initial discharge profile file name
                               (ASCII). (IM)

[wat_surf_profile=filename]    channel initial water surface profile file name
                               (ASCII). (IM)

[hyd_location=filename]        file name containing link and node numbers of
                               internal locations where discharge hydrographs
                               are to be saved (ASCII).

[_____UNITS_____]

[unit_el_conv=value]           unit conversion factor by which the values in
                               elevation must be DIVIDED to convert them
                               into meters.

[unit_lake=value]              unit conversion factor by which the values in
                               lake surface  elevation map must be DIVIDED to
                               convert them into meters.

[unit_space=value]             unit conversion factor by which all region
                               easting and northing values must be DIVIDED to
                               convert them into meters.


OUTPUT
-----------------------------------------------------------------------------

discharge=filename             outlet hydrograph file name (ASCII).

[dis_hyd_location=filename]    output file name for discharge hydrograph at
                               internal locations (ASCII)

[write_time_step=value]        time increment for writing output raster maps
                               in seconds.
-and-

  [depth_map=name]             output maps of surface depth in mm.

  [inf_depth_map=name]         output maps of cumulative infiltration depth in
                               tenth of mm.

  [surf_moist_map=name]        output maps of surface soil moisture in number of
                               fractions of a thousand.

  [rate_of_infil_map=name]     output maps of infiltration rate in mm/hr.

  [dis_rain_map=name]          output maps of distributed rainfall intensity in
                               mm.


FLAGS: There are several flags whose utility is driven by data availability
and/or user's choice.
----------------------------------------------------------------------------
-t    interpolates raingage rainfall intensities using Thiessen polygon
      technique.  The default technique uses inverse-distance-squared
      proportionality for interpolation of rainfall intensity over space.

-o    routes edge-accumulated overland flow out of active region (ONLY when no
      mask is specified). Often the surface water accumulated at the edges of
      the current region creates severe backwater effects and may limit the use
      of longer computational time steps.

-e    performs one-dimensional explicit finite difference channel routing. May
      be suitable for low- to medium-intensity rainstorms over small arid and 
      semi-arid watersheds with no base flow discharge.  This option often
      limits the computational time step to small values. Channel bed smoothing
      is recommended. No hydraulic structures, except reservoir spillways, can
      be simulated.

-p    assumes uniform channel geometry in each link (needs -e option). If this
      option is chosen, the channel input file (channel_input) must have only
      one line per fluvial link rather than the default of one line per node.

-i    performs Preissmann double sweep implicit channel routing. Particularly
      suitable for watersheds with some base flow to avoid dry-bed condition.
      Supercritical slopes cannot be handled; a warning message will be printed
      if supercritical flow is encountered.

-b    initializes the channel depth and discharge files (similar to -d) using
      the standard step backwater method. This option must be used with -i flag
      and replaces -d option to write "dis_profile" and "wat_surf_profile"
      files.   At present, only link types 1, 2, and 8 may exist in the channel
      network.

-d    performs channel initialization for implicit routing (needs -i
      option) by flooding the entire channel network with a horizontal water
      surface and draining down to normal depth using a y(t) outlet boundary
      condition (similar to -b).  It is essential for implicit channel routing
      technique that a minmum initial base flow discharge exist in the channels
      and also the corresponding initial water surface profile at each node in
      the channel network have a realistic value.  When the depth at the outlet
      reaches normal depth, the values of depth and discharge at each node is
      written to "dis_profile" and "wat_surf_profile" files for use in start up
      of actual simulations.  With this option no other component of the model
      is executed; only the implicit channel routing is performed to create
      initial depth and discharge files necessary for start up of actual
      simulations.

-u    writes discharges in cubic feet per second (cfs) and volumes in cubic feet
      in "discharge" file.  The internal calculations are all in SI units 
      regardless of this flag. The default SI unit prints the discharges
      in cubic meters per second (cms) and volumes in cubic meters (m3).

-q    skips printing iteration, time, and discharge values to the screen.  No
      status report is printed.


IMPORTANT NOTES

The user must pay close attention to the following notes prior to any
simulation:

1) watershed_mask: Although optional, preparation of this map is highly
recommended as it cuts down on the memory requirements by the amount directly
proportional to the ratio of mask area over the region area  (also see -o
flag). If the basin (mask) delineation has not been performed correctly,
surface water may accumulate near the edges of the watershed. This excess water
has no way out of the watershed and will accumulate, creating undesirable
backwater effects within the watershed which eventually dictate use of shorter
time step in order to accommodate such effects. It is recommended, in such
instances, to re-delineate the watershed along the edges. An alternative would
be to lower the elevation of the cells being flooded by excessive surface
runoff near the edges such that no artificial backwater is created.

2) elevation: The elevation map in the form of Digital Elevation Model (DEM) is
undoubtedly one of the most important inputs for distributed modeling.  Thus
the quality of the DEM plays a major role in success of distributed hydrologic
simulations.  DEMs almost always contain errors.  Large flat areas in the DEM
may be due to the limited vertical resolution of elevation data. Routing over
such flat areas usually creates problems for the numerical techniques used in
distributed physically-based models.  Unreal pits in the DEM may be artifacts
of interpolation scheme used to rasterize digitized contours, or due to coarse
resolution in areas of concave topography.  As a rule of thumb, the user must
cross check the DEM with topographic maps of the area.  One way to discover
potential errors in the DEM is to run r.hydro.CASC2D iteratively with no other
option except uniform rainfall and a relatively short time step.  Writing
surface depth maps should also be selected (see depth_map and write_time_step
options).  The simulation may terminate normally, at which case the surface
depth maps must be examined in order to determine where most water accumulation
occurred and whether such accumulation areas is justified by the topographic
map of the area.  Also  stream network may be checked for proper connectivity
via depth maps.  Alternatively, if the model crashed at a certain location
(whose address is printed on the screen as well as at the bottom of discharge
file) the user must zoom in and double check the DEM  with the topographic map.
Often times some manual editing of the DEM is necessary in order to impose the
actual drainage trend of the topo map. Prior to editing it is recommended that
the DEM be multiplied by 10 or 100, particularly if the original vertical
resolution of the DEM is also a concern. To account for this multiplication
factor use unit_el_conv=10 or unit_el_conv=100, whichever appropriate. Note that
only the unreal pits and depressions must be removed since they most likely
trap surface runoff which would have otherwise contributed to the outlet.  The
real lakes and reservoirs may be simulated if delineated (see lake_map).  In
any event, non-smoothed DEMs require short computational time steps, while
properly smoothed DEMs, particularly those with coarser grid space resolution,
allow use of longer time steps.  Another source of concern, which was briefly
mentioned in above paragraph, about the quality of the DEMs is that a nicely
connected stream network cannot be derived from non-smoothed DEM.  If no
delineated network (in the form of a vector file, for example) is available, an
approach similar to what was described before may be taken in order to edit the
DEM. However where a network has been delineated independent of the DEM then
the elevation of stream cells should be checked so that they are not higher
than those of the surrounding cells. Otherwise the stream cells will not
properly collect the surface runoff.

3) initial_depth: This is a map which contains initial overland depth values,
if any.  Rarely used since prior to the storm overland planes are often dry.
For channel initial depth see dis_profile and wat_surf_profile options.

4) storage_capacity & interception_coefficient: In r.hydro.CASC2D, the
interception rate (i) is expressed as:

    i(t)=r(t)     while I<=a
    i(t)=b*r(t)   while I>a

where r(t) denotes rainfall intensity at time t; a is the storage capacity; b
is the interception coefficient; and I is the cumulative interception depth.
Storage capacity map, as well as interception coefficient map, are usually a
reclass of vegetation map.  For table of storage capacity and interception
coefficient values see Gray (1970, section 4.6) or Bras (1990) p. 233.

5) roughness_map: This map represents the spatial distribution of overland
Manning roughness coefficient n.  This map could be a reclass of vegetation
cover map and/or the land use map.  Tables of Manning's n are available in 
most hydrology textbooks.  By using Manning resistance equation it is assumed 
that the overland flow over watersheds satisfies the conditions of turbulent 
flow over rough surfaces.

6) conductivity, capillary, porosity, & moisture: Four soil property maps are
needed for modeling infiltration process using the Green-Ampt technique.  These
maps respectively contain saturated hydraulic conductivity, capillary suction
head, effective porosity, and initial soil moisture content.  The first three
maps may be reclasses of soil texture map and the last one must be prepared
considering antecedent soil moisture conditions.  Based on soil textural
classifications, tables of estimates of the first three parameters can be found
in Rawls et al. (1983).  Wherever reliable field measurements of such
parameters are available they may be substituted for table values.  Note that the
saturated hydraulic conductivity map must be adjusted for the percent of rock
fraction within the soil, if known.  If these four maps are specified, Green &
Ampt infiltration calculations are performed.  If one or more of the maps is
not specified, no infiltration calculations are made.

7) pore_index & residual_sat: These two maps are required when continuous soil
moisture accounting is of primary interest. The model is capable of
redistributing the soil moisture during periods of no- or low- intensity
rainfall, over which infiltration capacity may recover for the next burst of
storm intensity. The technique used herein for hiatus and post-hiatus stages is
primarily based on the method by Smith el al. (1993).  In this model Green-Ampt
equation is used for post-hiatus stage. Tables of pore-size distribution index
(Brooks & Corey lambda) and residual saturation are given by Rawls et al.
(1982).  As in (6), measured values should be substituted where available. 
When the four maps specified in (6) as well as the two maps specified here are
given as command line arguments, the redistribution infiltration routine is
used.  All six maps must be specified to enable redistribution infiltration
calculations.

8) lake_map & lake_elev: The first map is the delineated lake map with
different categories corresponding to individual lakes and the second map holds
the initial water surface elevation in the lakes.  It is best to number the
lakes  categories sequentially. If a lake or reservoir connects to the implicit
channel network at its outlet, then the lake must also be numbered as a link as
reflected in the channel_input file. See channel_input and links_map options
for more details.  However isolated pond areas may be simulated as well; in 
fact such ponds are recommended to be delineated as part of the lake_map.  Such 
isolated lakes should not be present in the links map since their outlet is not 
connected to the channel network.  The routing of the lakes is performed by linear 
reservoir technique.  Rainfall is added directly to the lake inflow.  No 
interception or infiltration is abstracted from the lake cells.

9) radar_intensity_map: This is the common prefix of radar- or otherwise-
generated rainfall maps. One possible source of this type of data could be 
the NEXRAD system (Crum and Albery, 1993).  Alternatively, such time series 
of raster maps may come from the output of an interpolation software,
which takes in the rainfall site data corresponding to different times and
generates the time series of raster maps.  For instance, where raingage
rainfall data is available, one could run s.surf.tps of GRASS, one time for
every recording time, and save the interpolated rainfall maps to be used as 
input for r.hydro.CASC2D. In any case one must pay attention to the unit of 
intensity which is in integer millimeters per hour for map values. Also see
radar_time_step, and rain_duration options.  Example: If one sets 
radar_intensity_map=rain.map and there are a total of eight maps in regular 
intervals of 10 minutes (radar_time_step=600 and rain_duration= 4800, both in 
seconds), then the actual name of the maps in the current mapset would have 
to be: "rain.map.1", "rain.map.2" through "rain.map.8", respectively  
corresponding to time periods of 0-10, 10-20 through 70-80 minutes.

10) links_map & nodes_map: A link is a channel segment, of finite length, which
is comprised of two or more computational nodes placed at the center of each 
grid cell. Any internal boundary condition (weirs and lakes/reservoirs, for 
example) is also considered a link with only two nodes, one node upstream of the 
internal link and one downstream.  Although all links and nodes must be numbered
as discussed below, the link and node maps only contain trapezoidal or look-up
table cross sections (link types 1 and 8).  Internal boundary condition
link types (e.g. weirs) do not appear in the link or node maps.  The internal
boundary condition link types do appear in the channel_input file (see 
attachment).  The purpose of the link and node maps is to provide connectivity
information between overland flow grid cells and channel (link,node) pairs.  This
information is used to pass overland flow to the 1-D channel model as lateral
inflow.  The nodes map must contain the node numbers corresponding to the
links map.  Thus nodes corresponding to internal boundary condition links are
not present in the nodes map.  At a cell where a link terminates and another
link begins (junctions for example) the node number must comply with the
downstream link; i.e. this cell is  assigned a value of 1 in the nodes map.
However one must note that the last node of the upstream link also lies at such
junction cells.  This last node number must be accounted for in the main ascii
channel data file (channel_input), in which the total number of nodes per link
must be given.  An exception to this rule is the most downstream link leading
to the outlet. The links map essentially describes topology of the stream
network and its strict conformation with the stream numbering conventions is
vital.  Output from the GRASS command r.watershed cannot be directly used in
conjunction with r.hydro.CASC2D.  The link numbers assigned by r.watershed
must be re-numbered in accordance with the following rules.  Additionally, the
node map may be constructed by re-numbering the link map.  The general rules
for link and node numbering are:

A) The first link is numbered 1.
B) Upstream links must have smaller link numbers than downstream links.
C) Link numbers must change at junctions.
D) Link numbers may not be skipped.
E) Node numbers increase in the downstream direction.
F) Looped reaches cannot be simulated.
G) Streams may run only in x-y directions and not diagonally.
H) Link types cannot be mixed within a link.

A small example network with three links is given below:

             LINK MAP                        NODE MAP  

     0 0 0 0 0 0 0 0 0 0 0 0 0       0 0 0 0 0 0 0 0 0 0 0 0 0 
     0 0 0 0 1 0 0 0 0 0 0 0 0       0 0 0 0 1 0 0 0 0 0 0 0 0
     0 0 0 1 1 0 0 0 0 0 2 0 0       0 0 0 3 2 0 0 0 0 0 1 0 0
     0 0 0 1 0 0 0 0 0 2 2 0 0       0 0 0 4 0 0 0 0 0 3 2 0 0
     0 0 0 1 1 0 0 0 2 2 0 0 0       0 0 0 5 6 0 0 0 5 4 0 0 0
     0 0 0 0 1 0 0 2 2 0 0 0 0       0 0 0 0 7 0 0 7 6 0 0 0 0
     0 0 0 0 1 1 3 2 0 0 0 0 0       0 0 0 0 8 9 1 8 0 0 0 0 0
     0 0 0 0 0 0 3 0 0 0 0 0 0       0 0 0 0 0 0 2 0 0 0 0 0 0
     0 0 0 0 0 0 3 3 0 0 0 0 0       0 0 0 0 0 0 3 4 0 0 0 0 0
     0 0 0 0 0 0 0 3 0 0 0 0 0       0 0 0 0 0 0 0 5 0 0 0 0 0

This network has three fluvial links, link 1 has 9 nodes in the node map, while
link 2 has 8 and link 3 has 5.  Note that the junction of links 1 and 2 is
labled link 3.  However, links 1 and 2 have hidden nodes at this junction,
which must have the same bed elevation as the first node in link 3, but
different cross-sections.  The junction is really not the same point in space
for all three links, but really represents a short distance from the
confluence.  In the channel_input file, link 1 really has 10 nodes and link 2
has 9.  Link 3 would only have 5 nodes, because its downstream end is not a
junction, rather it is the watershed outlet.  The link and node maps tell
r.hydro.CASC2D that the overland flow in the grid cell at row 5, column 4 is
passed to link 1, node 5.

For more dicussion of links and nodes maps, see channel_input description
and the last section of this document titled "ATTACHMENT for channel_input 
and table_file File Options".

11) channel_input, table_file: For a detailed description of channel data 
file set-up and requirements: see the attachment titled "ATTACHMENT for
channel_input and table_file File Options", which is a modified version of the
document presented at the CASC2D Workshop by F.L. Ogden, June 9-10, 1994, at
the University of Memphis, Tennessee (Revision 2, 10 January 1995).  Also it is
recommended for the user to refer to Ogden (1994) for an overview of the
implicit channel routing formulation and numerical scheme.  Note that for
explicit channel routing, the same channel input file may be used provided that
only link types 1 and 4 are present. 

12) dis_profile & wat_surf_profile: These two files hold, respectively, the
discharge profile and the water surface profile of all nodes within the stream
network, including internal boundary condition nodes.  These files are created
by running r.hydro.CASC2D with the -i option AND either -d or -b.  After
creation, these files are used to initialize the implicit channel routing
scheme for actual watershed simulations.  They must be present for actual
simulations.  The -d flag creates initial discharge and depth files by flooding
the entire channel network with a horizontal water surface, and draining the
network using a depth vs. time relation at the watershed outlet.  This draining
proceeds until normal depth is reached at the outlet.  At this time, the
dis_profile and wat_surf_profile files are written for use in channel
initialization for later simulations.  The -b flag creates the initialization
files using the standard step backwater method.  Note that in dis_profile the
unit of discharge is in cubic meters per second and the unit of depth in
wat_surf_profile is in meters. Except for the reservoirs, the water surface
profile file actually holds the flow depth values and thus is measured
relative to the bed.  CAUTION:  The implicit channel routing routine must have
good first approximation of depth and discharge at each node in the network. 
Inaccurate values (guesses) will surely lead to a crash.  Additionally, the
implicit channel routine is for SUBCRITICAL (Froude number < 1) flow only.  A
newly created channel input file will almost always crash when first run.  It
is then the task of the user to identify the location of the problem.  Usually,
there are regions of hydraulically steep slopes which cause supercritical flow.
The channel code will warn the user of supercritical flow, including node and
link number when it occurs, and then exits.  The user should look at that
node/link combination, and alter the data file to eliminate the reach of steep
slopes.  One workable solution to prevent stability problems at low flows is to
use the so-called "Preissmann Slot" (see Cunge et al., 1980, for example).  Be
patient, as getting the channel network running is a time consuming process. 
There are a host of possible errors including: abrupt changes in cross-section,
DEM-error, etc., which can cause problems.  The implicit routing method is not
applicable to steep (mountainous or upland) streams.  If supercritical flow is
encountered in upland (1st order) streams, they can be eliminated from the
network.  The user should verify the suitability of this approach on each
watershed.

13) hyd_location: If a filename is specified, this input ascii file contains
the link and node numbers of the locations at which discharge hydrographs are
to be written to the file named in the dis_hyd_location option. The first
column in this file should contain link numbers and the second column must be
filled with the corresponding node numbers.  For a description of the output,
see the dis_hyd_location option.

14) r_gage_file: This is an ascii file which must be provided when raingage
rainfall data is being simulated.  At the top of the file, two-column lines hold
the easting and the northing for each raingage.  The number of such lines is
determined by the total number of recording raingages (num_of_raingages).  The
location of any of the gages does not have to be within the current region nor
within the current watershed mask as long as the easting and the northing are
not specified relative to the current region, but are based on absolute values
in the UTM or SP coordinates.  If a gage falls outside in a different zone to the 
left of the active region's zone, then negative values are also acceptable.  Note
however that raingages well outside the watershed under analysis generally 
provide poor rainfall estimates.  The subsequent lines at the bottom of the 
raingage file must reflect temporal variation of rainfall intensity.  The
number of columns per line is equal to the number of raingages (specified via
num_of_raingages).  The columns are separated by space.  The number of lines in
this lower portion is equal to number of instances, separated by a constant
time interval, the raingages have made a recording.  As usually is the case, 
the unit of rainfall intensity for raingage data must be in inches per hour. 
Example: For three raingages, each recording rainfall intensity every 2 minutes
for a total duration of, say, 10 minutes, a file called "rain.inp" may look 
like this:

205150.0    750212.0
20545.0     750104.0
205320.0    750173.0

0.0     0.0     0.55
1.75    2.25    0.80
1.00    1.80    1.50
0.65    0.90    0.70
0.0     0.50    0.30

In above example, the eastings and northing of the first, second, and third
raingages are (205150.0,750212.0), (20545.0,750104.0), and (205320.0,750173.0) 
respectively.  The intensities recorded by the first gage, for example, are 0.0, 
1.75, 1.00, 0.65, and 0.0 inches per hour, respectively, over 0-2, 2-4, 4-6, 6-8, 
and 8-10 minutes, etc. For this example r_gage_file=rain.inp, num_of_raingages=3, 
gage_time_step=120, and rain_duration=600. For state plane (SP) coordinate system 
the eastings and northing will have to be in feet rather than meters.

15) outlet_eastNnorthNslope: These three values determine the location of the
outlet, in terms of its easting and northing, and the outlet bed slope.  One
needs to make sure that the outlet described by its easting and northing is
not only within the active region but also inside watershed mask.  Often times
the region is not set to its original settings after zoom-in operations
(d.zoom) are performed and this may put the outlet outside the active region
thus causing the model to eventually crash.  The bed slope is equal to tangent
of the angle which is made between the bed profile at the outlet and horizontal
plane.  This slope is primarily used to calculate the outflow overland discharge
at the outlet, if any, based on normal depth boundary condition, when no
channel routing is performed (all surface flow treated as overland flow and
channels essentially assumed wide).  Normal depth is also assumed to prevail at
the outlet when explicit channel routing (-e) has been selected.

16) Manning_n: The alternative to simulating spatially varied roughness
coefficient is to provide a single value of Manning roughness coefficient n via
Manning_n parameter.  The user is warned if both roughness_map and Manning_n
have been specified.

17) unif_rain_int: This option represents the intensity of the spatially-
uniform temporally-constant (up to the rainfall duration) rainfall.  Therefore
this option may replace r_gage_file and radar_intensity_map options.  The unit 
is in millimeters per hour.

18) num_of_raingages: The total number of recording raingage.  If this variable
is set to one, no spatial interpolation is performed and the rainfall is
treated as uniform is space but could vary in time.  The temporal variation will
be then provided by r_gage_file.  Note that when num_of_raingages is set to one,
the easting and northing of the gage is irrelevant although two (arbitrary)
values must still be provided at the top of raingage file (r_gage_file).

19) time_step: This represents the duration of computational time step in
seconds and is a critical variable determining the total execution time for 
a particular simulation.  These is no firm guide for the selection of the time 
step; it comes with experience and strongly depends on watershed and rainfall 
characteristics.  The general rule for overland routing and explicit channel 
routing is that shorter time steps must be used for higher intensity storms, 
finer horizontal grid resolution (grid spacing), steeper watershed slopes, 
larger watershed areas, and smoother surfaces.  Stability of explicit routing 
depends upon Courant number.  Unfortunately, the critical condition for Courant
number limits the length of the computational time step which must be used for
the entire simulation unless variable time step algorithm is implemented in 
the future.  Shorter time steps must be used when backwater effects are 
generated, mainly in flat areas which are not part of the lake map.  If the 
time step is too long for any particular simulation the surface water depth 
in completely flat areas may show a checker-board pattern, i.e. oscillations  
are observed in the water surface level.  This eventually results in a crash.
As such, the time step should be decreased and the simulation repeated; or the
flat areas be delineated within the lake map.

20) gage_time_step: This variable represents the time interval, in seconds, 
between recording instances of rainfall intensities by raingage(s).  It is 
implied that the rainfall data has been recorded in regular intervals.  See the 
notes under r_gage_file for an example.

21) radar_time_step: A value expressing the time interval between consecutive
rainfall maps.  A uniform time step is implied.  

22) rain_duration: This is the total duration of rainfall in seconds.  If
multistorm events are simulated, the time from the beginning of the first storm
to the end of the last storm constitutes the total rainfall duration.  As such,
selection of soil moisture redistribution capability is recommended via
specifying pore index (pore_index) and residual saturation (residual_sat) maps.

23) tot_time: The total simulation time in seconds.  If the falling limb of the
discharge hydrograph is of particular interest the total simulation time must
be set to a value greater than total rainfall duration plus the expected
recession time.

24) write_time_step: This time parameter determines the frequency of writing
output raster maps and is equal to the time interval, in seconds, at which 
output raster maps are saved.  Also see depth_map, inf_depth_map, 
surf_moist_map, rate_of_infil_map, and dis_rain_map output options.

25) unit_el_conv: This conversion factor is used to convert elevation values in
DEM (elevation) map to meters.  This parameter doesn't need to be specified if 
the DEM is already in meters since the default is one.  For DEM units in cm or 
ft, unit_el_conv must be respectively set to 100 or 3.281.

26) unit_lake: This conversion factor is used to convert the water surface
elevation values in the lake_elev map to meters.  The default is 1.0.

27) unit_space: This conversion factor is used to convert the horizontal grid
spacing resolution to meters.  The default is 1.0.  For state plane coordinate
system in ft, set unit_space equal to 3.281.

28) d_thresh: This parameter represents an average step retention storage 
below which the overland depth will not be routed.  Another words, all 
depressions less than or equal to d_thresh are filled before any overland flow
could begin.  The unit must be in meters so for 2 mm of depression storage set 
d_thresh=0.002.  Higher values of depression storage would reduce the total
execution time of the model as the overland routing consumes most of the CPU
effort.

29) discharge: The discharge hydrograph computed at the outlet will be saved in
this ascii file under the current directory.  Some other information, such as
peak discharge, is also printed in this file.

30) dis_hyd_location: Whenever the hyd_location option is selected, the
discharge at individual node/link pairs will be saved in this file.  The
discharge hydrographs at the (link,node) locations specified in hyd_location
file are grouped in columns.  The number of lines in this file is determined by
the total number of iterations equal to tot_time divided by time_step.

31) depth_map, inf_depth_map, surf_moist_map, rate_of_infil_map, &
dis_rain_map: depth_map is the common filename prefix given to the time series
of output raster maps containing surface depth values in millimeters. At the
channel cells the channel flow depth will be recorded in the maps. The surface
depth maps, and all other output maps, are saved at regular intervals
determined by write_time_step option. If write_time_step is not set, no output
raster map will be saved. The first map always corresponds to the initial
condition and  naturally shows the water surface profile corresponding to the
base flow discharge within the channel network when implicit channel routing is
performed.  Similarly the last depth map corresponds to the end-of-simulation
time, or to the time at which the program finished abnormally, for example due
to selection of a long step which generated oscillations leading to a crash. 
Abnormal program termination caused by oscillating depths may show negative
depths in the overland plane.  There is a hard-coded limit of 2000 output
raster maps for each simulation.  inf_depth_map and rate_of_infil_map are two
options to save the output raster maps of cumulative infiltration depth, in
tenth of mm, and rate of infiltration in mm/hr, respectively.  These two
options can only be selected when infiltration is being computed via either the
Green & Ampt or redistribution methods.  surf_moist_map output contains the
soil moisture values at the soil surface and it may solely be selected
with continuous infiltration option (pore_index and residual_sat maps are
specified).  dis_rain_map option saves the instantaneous rainfall intensities,
in mm/hr,  at write_time_step intervals and may be set for the simulations
involving spatially distributed rainstorms; i.e. raingage rainfall data or
radar (or other sources of rainfall raster maps) data.   Example: If one sets
depth_map=depth.out, tot_time=1000, and write_time_step= 100, then a total of
11 raster depth maps will be saved in a normally-terminated simulation:
depth.out.00, depth.out.01, depth.out.02 through  depth.out.10, respectively
corresponding to times equal to 0, 100, 200,  through 1000 seconds.  These maps
may be viewed sequentially in animation form using the GRASS animator program
xganim.

REFERENCES:

Bras, R. L., 1990, Hydrology: An introduction to hydrologic science, Addison-
     Wesley, Reading, Mass., 643 p.

Crum, T. D., and R. L. Alberty, 1993, The WSR-88D and the WSR-88D operational
     support facility, Bulletin of the American Meteorological Soc., 74(9), pp.
     1669-1687.

Cunge, J.A., F.M. Holly, and A. Verwey, 1980, Practical Aspects of Computational
     River Hydraulics, Iowa Institute of Hydraulic Research, 404HL The
     University of Iowa, Iowa City, IA 52242. 420 p.

Gray, D.M., 1970, Handbook on the Principles of Hydrology, National Research
     Council of Canada, Water Information Center Inc., Water Research Building,
     Manhasset Isle, Port Washington, N.Y., 11050.

Julien, P. Y., and B. Saghafian, 1991, CASC2D users manual - A two dimensional
     watershed rainfall-runoff model, Civil Engr. Report, CER90-91PYJ-BS-12,
     Colorado State University, Fort Collins, CO.

Julien, P. Y., Saghafian, B., and F. L. Ogden, 1995, "Raster-Based Hydrologic 
     Modeling of Spatially-Varied Surface Runoff", Water Resources Bulletin,
     AWRA, 31(3), pp. 523-536.

Ogden, F.L., 1994, de-St Venant channel routing in distributed hydrologic
     modeling., Proc. Hydraulic Engineering `94, ASCE Hydraulics Specialty
     Conference, G.V. Cotroneo and R.R. Rumer, eds., Vol. 1, pp. 492-496.

Rawls, W. J., Brakensiek, D. L., and N. Miller, 1983, Green-Ampt infiltration
     parameters from soils data, J. of Hydraulic Engineering, ASCE, 109(1), pp.
     62-70.

Rawls, W. J., Brakensiek, D. L., and K. E. Saxton, 1982, Estimation of soil
     water properties, Trans. of ASAE, pp. 1316-1320.

Saghafian, B., 1992, Hydrologic analysis of watershed response to spatially
     varied infiltration, Ph.D. Dissertation, Civil Engr. Dept., Colorado State
     University, Fort Collins, CO.

Saghafian, B., 1993, Implementation of a distributed hydrologic model within
     Geographic Resources Analysis Support System (GRASS), Proceedings of the
     Second International Conference on Integrating Environmental Models and
     GIS,  Breckenridge, CO.

Smith, R. E., Corradini, C., and F. Melone, 1993, Modeling infiltration for
     multistorm runoff events, Water Resources Research, 29(1), pp. 133-144.

------------------------------------------------------------------------------
ATTACHMENT for channel_input and table_file File Options
------------------------------------------------------------------------------

GENERAL NOTES

     The naming convention associated with the Preissmann double-sweep 1-D
implicit channel routing method is based on the concept to links and nodes.
A link is a channel segment, or an internal boundary condition, which is
comprised of two or more computational nodes. All internal boundary conditions
contain two nodes, while fluvial reaches may be of any size greater than
or equal to two nodes.  The following discussion of input file format must
first distinguish between different link types.  A few of the possible link
types are presented below in Table 1.  As of August 1995, only link types 1, 
2, 4, and 8 are supported.  Development is continuing on link types 3 and 7.


                              Table 1.  Link Types


   Link   Description of Link Type                  Number of       Number of
   Type                                             Parameters         Nodes
    #

    1     Fluvial Link, Trapezoidal                      5              >=2
          Cross-Section

    2     Overflow Weir                                  8               2

    3     Culvert/Weir                                   8               2

    4     Reservoirs                                     5               2 

    7     Bridge Crossings                               8               2

    8     Look-up Table (Breakpoint) Cross-Section       4              >=2


     At present the channel model formulation accepts cross-sectional input for
only two different channel geometries, namely trapezoidal, and breakpoint via
look-up table.  Trapezoidal channel parameters which must be provided as
input at each computation node include: Manning's n, bottom width, channel 
depth, side slope, and bed elevation.  Look-up tables of cross sectional
properties must include cross-sectional area, top width, and conveyance at 
equal depth intervals.  Smooth transition in channel cross sectional properties
within links of type 8 and between all connecting fluvial links often plays
a vital role in the success of simulations.  Abrupt changes in cross-sections
can lead to numerical errors in mass conservation.

     As far as handling the reservoirs (link type 4), flow is not routed through
reservoirs in this version of the CASC2D channel routing code.  Instead the
linear reservoir approximation is used.  Among other internal boundary 
conditions link types, only weirs can be simulated at present.

     The channel_input file contains the channel bed elevation at each node,
which constructs the longitudinal profile of channels in the drainage network.
Ideally, the modeler should use surveyed cross sections and talweg profiles of
the channel network.  However, extensive surveys are often impossible for the
entire drainage networks on large watersheds.  In lieu of an extensive survey,
there are existing tools for extracting channel topology from digital
elevation models (DEM).  However, if the channel network is extracted from a
DEM, a smoothing algorithm must be applied (e.g. Ogden et al., 1994) to produce
physically realistic longitudinal profiles because of errors inherent in any
DEM.


EXAMPLE OF INPUT FILE FORMAT AND CONSTRUCTION

NOTE: The channel_input file and table_file both follow SI unit convention. 
All units of length are in meters, including elevations.

     In this example, a channel input data file is constructed for a fictitious
watershed.  Note that this particular example is merely for demonstration and
has not been tried in any simulation run.  The stream network will consist of 
trapezoidal and look-up table fluvial links, an internal reservoir, and an 
overflow weir.  Regarding the MASK map (watershed_mask option), note that all 
watershed cells must be marked with 1, while all raster cells outside the 
watershed boundary are marked with 0. Also all the cells in the lake should 
carry the value 1 on the LAKE map (lake_map  option).  If there was another 
lake in this example, it would be denoted with  the number 2, etc.

     The channel link numbering scheme typically employed in  double-sweep
routing was explained in the main text.  With reference to the LINK map shown
below, (links_map option), assume that links 1  and 2 drain into link 3,
which in-turn drains in to the lake, which is assigned link number 4.  Also
links 7 and 8 drain into link 9.  Link 5 originates at the outlet of the
reservoir.   Link 5 is split into link 6 because of a change in some 
cross-section property.  Links 6 and 9 flow into link 10, which is immediately 
upstream from a weir which must be considered link 11.  Finally, link 12, the 
most downstream link, lies below the weir (link 11).  Note that the LINK map 
contains continuous sequence  of link numbers, except for the internal 
boundary conditions such as the weir (link 11) and lakes (link 4) which does 
not appear in the LINK map.

                      EXAMPLE LINK MAP

 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0 
 0  0  0  1  0  0  0  0  0  0  0  0  0  0  2  0  0  0  0  0
 0  0  0  1  0  0  0  0  0  0  0  0  0  2  2  0  0  0  0  0
 0  0  0  1  1  0  0  0  0  0  0  0  2  2  0  0  0  0  0  0  
 0  0  0  0  1  1  1  0  0  0  0  0  2  0  0  0  0  0  0  0
 0  0  0  0  0  0  1  1  1  0  0  0  2  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  1  0  2  2  2  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  1  1  3  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  3  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  3  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
 0  0  7  7  7  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
 0  0  0  0  7  7  0  0  0  0  5  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  7  7  0  0  0  5  5  0  0  0  0  0  0  0  0
 0  8  8  8  0  0  7  0  0  0  0  5  6  0  0  0  0  0  0  0
 0  0  0  8  8  8  9  9  0  0  0  0  6  6  0  0  0  0  0  0
 0  0  0  0  0  0  0  9  9  9  0  0  0  6  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  9  9  9  9 10 10 10  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0 12  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0 12 12 12 12  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0 12  0


     Now, refer to the NODE map (nodes_map option) shown below.  In the NODE
map, each link is numbered from 1 to the number of grid cells spanned by that
link, with the exception of the internal boundary conditions.  Conceptually,
internal boundary conditions (including reservoirs) have two nodes but they are
not given any node numbers in the NODE map.  This is how the program recognizes
internal boundary conditions.  Furthermore, all links except the one leading to
the watershed outlet must have an extra node to provide connectivity to the
downstream link.  Therefore, even though the NODE map may show link 1 to have
13 nodes, it actually has 14.  This implied extra node for link 1, shared 
between the most downstream node of link 1 and the most upstream node of link 
3, provides the connection between link 1 and link 3. The number of nodes in 
each link in this example are shown below in Table 2.  Note that the node map 
entries for the lake (link 4) are 0.

                      EXAMPLE NODE MAP

 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0 
 0  0  0  1  0  0  0  0  0  0  0  0  0  0  1  0  0  0  0  0
 0  0  0  2  0  0  0  0  0  0  0  0  0  3  2  0  0  0  0  0
 0  0  0  3  4  0  0  0  0  0  0  0  5  4  0  0  0  0  0  0  
 0  0  0  0  5  6  7  0  0  0  0  0  6  0  0  0  0  0  0  0
 0  0  0  0  0  0  8  9 10  0  0  0  7  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0 11  0 10  9  8  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0 12 13  1  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  2  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  3  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
 0  0  1  2  3  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
 0  0  0  0  4  5  0  0  0  0  1  0  0  0  0  0  0  0  0  0
 0  0  0  0  0  6  7  0  0  0  2  3  0  0  0  0  0  0  0  0
 0  1  2  3  0  0  8  0  0  0  0  4  1  0  0  0  0  0  0  0
 0  0  0  4  5  6  1  2  0  0  0  0  2  3  0  0  0  0  0  0
 0  0  0  0  0  0  0  3  4  5  0  0  0  4  0  0  0  0  0  0
 0  0  0  0  0  0  0  0  0  6  7  8  9  1  2  3  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  1  0  0  0  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  2  3  4  5  0
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  6  0


   Table 2. Number of Nodes in each Link for Example Watershed Stream Network


         Link Number         Number of Nodes          Number of Nodes as
                             as in nodes_map         in channel_input file

             1                    13                        14

             2                    10                        11

             3                     3                         4

             4 (reservoir)         0                         2

             5                     4                         5

             6                     4                         5 

             7                     8                         9

             8                     6                         7

             9                     9                        10

            10                     3                         4

            11 (weir)              0                         2

            12 (most downstream)   6                         6
                link)



     The first portion of the channel input file is used to pass physical
constants and simulation  parameters  to  the  model. These  include  the
gravitational acceleration "g", kinetic energy  correction factor "alpha", the
friction slope weighting factor "beta", the spatial derivative weighting
coefficient "theta", the length  of each node "dx", the computational time step
"dt" (seconds), the total simulation time "tt" (seconds), and the discharge in
all first order  streams "qmin" (m3/s).  At present, the time step "dt" must be
identical to the  computational time step used in the overland flow routing
portion of  r.hydro.CASC2D.  The program must be told the number of links, and
the largest  number of nodes in any link in the network for dynamic memory
allocation.  In our example problem, the number  of links is 12, and the
maximum number of nodes is 14 (in link 1).  Remember that all links which are
not at the outlet or not immedietly upstream of a reservoir must have an
extra node for connectivity purposes.  The total number of links is called 
"nlinks", and the largest number of nodes in any link in the network is called
"maxnodes".  In this example, we will use the constants and parameters given 
in Table 3:


             Table 3. physical constants and simulation  parameters


                     "g"               9.81 m/s2

                     "alpha"           1.0

                     "beta"            0.5

                     "theta"           0.55

                     "dx"              100.0 m

                     "dt"              30.0 s

                     "tt"              3600.0 s

                     "qmin"            0.07 cms

                     "nlinks"          12

                     "maxnodes"        14


     This data constitutes the first portion of channel_input file and is 
arranged into a header which must have the form (note floating point and 
integers):



9.81
1.0  0.5  0.55
100.0
30.0  3600.0
0.07
12
14


     The second portion of the input file describes link types as well as 
the network topology and connectivity.  This is accomplished using a 
line-input format, one line for each link in the network.  Each line contains
6 values arranged in columns, as shown in Table 4.


                   Table 4. Connectivity information format


           Column     Data Description

              1       Link number (INT).

              2       Link type (INT).

              3       Number of  upstream  dependencies  (maximum  2,
                      minimum 0) (INT).

              4       Upstream dependency #1 (INT). (0 if no upstream dep.)

              5       Upstream dependency #2 (INT). (0 if 0 or 1 upstream dep.)

              6       Downstream dependency (zero for outlet) (INT).



     As far as link types in the current example, assume that links 1 through 9,
except reservoir link 4 (link type 4), are well-described as trapezoidal (type
1), and we are  using look-up table data to describe the cross-sections of
links 10 and 12  (type 8).  The weir (link 11) is of link type 2.  Thus the
second portion of input file for describing link types and  connectivity looks
like:

1   1   0   0   0   3
2   1   0   0   0   3
3   1   2   1   2   4
4   4   1   3   0   5
5   1   1   4   0   6
6   1   1   5   0  10
7   1   0   0   0   9
8   1   0   0   0   9
9   1   2   7   8  10
10  8   2   6   9  11
11  2   1  10   0  12
12  8   1  11   0   0

Note that only the outlet link has 0 as a downstream dependency.  It is
important that this be the only link with 0 as a downstream dependency.  Also,
the location and topology of internal boundary condition links (4 and 11)
with respect to other links are known via above connectivity information in
the channel_input file.  As an interpretation, examine link number 10 above.  
It is of link type 8 (look-up table cross-section data), has 2 upstream 
dependencies (links 6 and 9), and flows into link 11.

     The third portion of the  input  file contains the  individual  hydraulic
property information for each node in the network.  Assume for now that all the
trapezoidal channels in the network have the properties shown in Table 5.


      Table 5. Cross-Sectional Properties of Example Trapezoidal Channels


                  Manning coefficient      varies

                  Bottom width (m)         varies

                  Channel depth (m)        1.75

                  Side slope H:V           varies 

                  Bed elevation            dependent upon location



Now, lets build the input file section for link #1 which has 13 nodes on the
NODE map, plus an extra for connectivity at the upstream end of link 3  (total
of 14 nodes).  This input file section will look like:

1  14
0.035  2.10  1.75  2.00  264.40
0.035  2.10  1.75  2.00  263.85
0.035  2.10  1.75  2.00  263.41
0.035  2.10  1.75  2.00  262.98
0.035  2.10  1.75  2.00  262.75
0.035  2.10  1.75  2.00  262.54
0.035  2.10  1.75  2.00  262.37
0.035  2.10  1.75  2.05  262.02
0.035  2.20  1.75  2.05  261.87
0.035  2.20  1.75  2.10  261.75
0.035  2.20  1.75  2.10  261.67
0.035  2.20  1.75  2.15  261.52
0.035  2.30  1.75  2.15  261.25
0.035  2.40  1.75  2.15  261.00

The 1 and 14 on the first line indicate that it is link 1, with 14 nodes.  The
columns represent Manning's n, bottom width, channel depth, trapezoidal side
slope H/V, and talweg elevation, respectively.

Link 2 might have an entry which looks like:

2  11
0.035  1.80  1.75  1.80  264.21
0.035  1.80  1.75  1.80  264.10
0.035  1.90  1.75  1.90  263.81
0.035  1.90  1.75  1.90  263.56
0.035  2.00  1.75  1.90  263.34
0.035  2.10  1.75  1.90  262.86
0.035  2.10  1.75  2.00  262.24
0.035  2.10  1.75  2.00  261.76
0.035  2.20  1.75  2.10  261.48
0.035  2.30  1.75  2.10  261.26
0.035  2.30  1.75  2.10  261.00

The cross-section entry for link 3 would then look like:

3  4
0.035  2.60  1.75  2.20  261.00
0.035  2.60  1.75  2.40  260.20
0.035  2.80  1.75  2.90  259.67
0.035  2.80  1.75  2.90  259.17

     The elevation of the downstream end of links 1 and 2 must be equal to the
bed elevation of the upstream end of link 3. It is required that the bed
elevation of all channel inverts at each junction be equal.  Even though they
are not exactly the same points in space, they are assumed close enough to have
the same elevation.

                    Flow                 Flow
                     \                    /
                  \   \    \         /   /     /
                   \   v    \       /   v     /
                    \        \     /         /
                     \ link 1 \   / link 2  /
                      \ node 14\ / node 11 /
                       \                  /
                        \                /
                         \              /
                          \            /
                           |          |
                           |  link 3  |
                           |  node 1  |
                           |          |

     The input for other links with trapezoidal cross section is similar to 
the input for link 1 (see the next section for the complete input file).

     Additionally, assume that the reservoir (link 4) has a surface area of
0.498 square km, a rectangular spillway width of 12m, a spillway discharge
coefficient of 0.97, an initial water surface elevation of  260.10m, and a
spillway crest elevation of 260.50m.  The resulting input file entry is shown
below.

4  2
0.498  12.0  0.97  260.10  260.50
0.000   0.0  0.00    0.00    0.00

The number of nodes (line entries) in the channel_input file per reservoir link
is two, but the numbers entered in the second row entry are for further
improvements and for now their value is irrelevant.  Also note that the bed
elevation at the downstream limit of link 3 MUST be lower than the initial
water surface elevation in the reservoir (link 4). This is manditory at all
downstream boundaries between channels flowing into the reservoirs.  Reservoirs
serve as downstream boundary conditions at upstream links.  The elevation of
reservoirs should therefore never be allowed to fall below critical depth in
any channels which flow into the reservoir.  If this happens, the code will
crash.

     The input for links 5, 6, 7, 8, and 9 will be similar to links 1, 2, and
3.  See the constructed input file at the end of this text.  Trapezoidal
channel links are simple in terms of input.  The channel depth field is 
intended to represent the average bank-full depth of the channel.  This number
is not used in the present version of the code, but will be in the future when
the overland flood plane and channel flows are coupled iteratively.  At present
the flows are not fully coupled.  Water can flow only from the overland flow
plane into the channels, not from the channels back to the flood plane.

     If look-up table data are used (link type 8), the look-up tables are stored
in a seperate file.  The GRASS command line option for this look-up table file
is table_file.  If there are any link type 8 in the channel_input data file,
the program will attempt to open the file table_file (typically called
"table.dat").  If this file is not present, the program will terminate.  In
channel_input file, all that is needed is the table number for a particular
cross section, and the talweg elevation.  Assume that the 4 nodes in link
10 are approximated by one cross-section, which is given as table entry 1, then
the channel_input file entry for link 10 would look like:

10  4
1  244.0
1  243.5
1  243.0
1  242.5

In this format, the first column represents the look-up table number for the
given node, and the second column represents the bed elevation for that node. 
Table numbers can be mixed within a link.  However, abrupt changes in
cross-section should be avoided because they cause significant continuity
errors in the formulation.  The format of the table_file is discussed later in
this document.

     Link 11 is an overflow weir link.  While this link has no nodes which
appear in the node map for overland flow connectivity, it does have two nodes
in terms of channel topology.   The meaning of the columns in the weir node
input section is presented in the Table 6:
   
            Table 6.  Parameter Description for Weirs

    Line Entry     Column      Parameter Description
    ----------     ------      ---------------------------------------------
        1            1         forward direction weir discharge coefficient
    
        1            2         reverse direction weir dischagre coefficient
 
        1            3         0.0 (reserved for future use)

        1            4         crest length, meters

        1            5         elevation of weir crest, meters

        2           1-4        0.0 (reserved for future use)

        2            5         downstream bed elevation, meters


The first (upstream) node represents the crest of the rectangular weir.  The
second (downstream) node represents the bed of the channel just downstream from
the weir.  Assume that this weir has a crest elevation of 244.4 m, a crest
width of 8 m, a discharge coefficient in the forward direction of 0.92, a
discharge coefficient for flow in the reverse direction equal to 0.85, and the
channel bed elevation immediately downstream from the weir is 239.8m.  The
entry for this weir in the channel_input file would thus appear as:

11  2
0.92   0.85  0.00  8.00  244.4
0.00   0.00  0.00  0.00  239.8 

     Link 12 uses table entry 2 for the its first four nodes and entry 4 for the
remaining two nodes.  Note that link 12 has 6 nodes in the node map, and 6
nodes in the channel_input file.  Because link 12 is the outlet link, we do not
add an extra node at the downstream end for connectivity purposes.  The
portion of the channel_input file for link 12 looks like:

12  6
2  239.80
2  239.47
2  239.33
2  239.05
3  238.54
3  238.44

Hence, 238.44 is the talweg elevation at the outlet of the catchment.  Also
notice that the upstream end of link 12 and the downstream node of link 11 have
the same bed elevation.

      Weirs cannot be used as the outlet boundary condition for this channel
model.  If your watershed has a weir at the outlet, just place a short link
downstream from the weir with appropriate characteristics. 

FINAL CHANNEL FILE FORMAT

     The example channel data file (typically called chn.dat) developed for
this example looks like:



----------------------BEGIN channel_input FILE HERE----------------------------
9.81
1.0  0.5  0.55
100.0
30.0  3600.0
0.07
12
14

1   1   0   0   0   3
2   1   0   0   0   3
3   1   2   1   2   4
4   4   1   3   0   5
5   1   1   4   0   6
6   1   1   5   0  10
7   1   0   0   0   9
8   1   0   0   0   9
9   1   2   7   8  10
10  8   2   6   9  11
11  2   1  10   0  12
12  8   1  11   0   0

1  14
0.035  2.10  1.75  2.00  264.40
0.035  2.10  1.75  2.00  263.85
0.035  2.10  1.75  2.00  263.41
0.035  2.10  1.75  2.00  262.98
0.035  2.10  1.75  2.00  262.75
0.035  2.10  1.75  2.00  262.54
0.035  2.10  1.75  2.00  262.37
0.035  2.10  1.75  2.05  262.02
0.035  2.20  1.75  2.05  261.87
0.035  2.20  1.75  2.10  261.75
0.035  2.20  1.75  2.10  261.67
0.035  2.20  1.75  2.15  261.52
0.035  2.30  1.75  2.15  261.25
0.035  2.40  1.75  2.15  261.00

2  11
0.035  1.80  1.75  1.80  264.21
0.035  1.80  1.75  1.80  264.10
0.035  1.90  1.75  1.90  263.81
0.035  1.90  1.75  1.90  263.56
0.035  2.00  1.75  1.90  263.34
0.035  2.10  1.75  1.90  262.86
0.035  2.10  1.75  2.00  262.24
0.035  2.10  1.75  2.00  261.76
0.035  2.20  1.75  2.10  261.48
0.035  2.30  1.75  2.10  261.26
0.035  2.30  1.75  2.10  261.00

3  4
0.035  2.60  1.75  2.20  261.00
0.035  2.60  1.75  2.40  260.20
0.035  2.80  1.75  2.90  259.67
0.035  2.80  1.75  2.90  259.17

4  2
0.498  12.0  0.97  260.10  260.50
0.000   0.0  0.00    0.00    0.00

5  5
0.035  2.50  1.75  2.10  249.20
0.035  2.50  1.75  2.10  248.65
0.035  2.50  1.75  2.15  247.94
0.035  2.50  1.75  2.20  247.31
0.035  2.50  1.75  2.20  246.97
0.035  2.50  1.75  2.25  246.42

6  5
0.035  2.50  1.75  2.00  246.42
0.035  2.50  1.75  2.00  245.97
0.035  2.50  1.75  2.00  245.24
0.035  2.50  1.75  2.00  244.73
0.035  2.50  1.75  2.00  244.00

7  9
0.035  1.75  1.75  2.00  254.20
0.035  1.75  1.75  2.00  253.55
0.035  1.75  1.75  2.00  252.92
0.035  1.90  1.75  2.00  252.29
0.035  1.90  1.75  2.00  251.71
0.035  1.90  1.75  2.00  251.24
0.035  2.00  1.75  2.00  250.82
0.035  2.00  1.75  2.00  250.34
0.035  2.00  1.75  2.00  250.08

8  7
0.035  1.60  1.75  2.00  253.71
0.035  1.90  1.75  2.00  253.21
0.035  1.90  1.75  2.00  252.94
0.035  2.00  1.75  2.00  252.55
0.035  2.10  1.75  2.00  251.80
0.035  2.10  1.75  2.00  251.11
0.035  2.10  1.75  2.00  250.08

9  10
0.035  3.10  1.75  2.90  250.08
0.035  3.20  1.75  2.90  249.16
0.035  3.30  1.75  3.00  248.63
0.035  3.40  1.75  3.00  248.02
0.035  3.40  1.75  3.10  247.33
0.035  3.20  1.75  3.10  246.65
0.035  3.10  1.75  3.10  246.05
0.035  3.20  1.75  3.10  245.88
0.035  3.20  1.75  3.10  245.52
0.035  3.50  1.75  3.10  245.24
0.035  3.70  1.75  3.40  244.74
0.035  3.50  1.75  3.40  244.51
0.035  3.10  1.75  3.40  244.00

10  4
1  244.00
1  243.50
1  243.00
1  242.50

11  2
0.92   0.85  0.00  8.00  244.40
0.00   0.00  0.00  0.00  239.80

12  6
2  239.80
2  239.47
2  239.33
2  239.05
3  238.54
3  238.44
--------------------- END OF channel_input FILE ---------------------------



TABLE_FILE INPUT FORMAT

     If link type 8 (look-up table x-sections) are present in the channel_input
file, we require a file typically called "table.dat", to store all look-up
table values.  This file must begin with an integer equal to the number of
tables contained within the file.  In our example this number is 3.  Then we
require 3 tables.  The first line of each table is an integer equal to the
table number. The second line in the table entry contains two numbers, an
integer, and a floating point (real) value.  The first number is equal to the
number of entries (rows) in each particular table, designated by "numhts". The
second number is the vertical distance between hydraulic property points, which
must be a constant for each table.  For instance, if you describe the variation
of cross-sectional area, topwidth, and conveyance at 0.5 m vertical intervals,
this number will be 0.5.

     Each table entry must then contain "numhts" lines, each with four
entries.  The first line must be:

0.0   0.0   0.0   0.0

subsequent lines must contain the following:

height   topwidth   x-section_area  x-section_conveyance.

     For instance, lets assume we know geometric variables for table entries 1,
2, and 3.  The file "table.dat" (table_file option) may look like:

3
1
5  1.0
0.0   0.0    0.0    0.0
1.0   2.1    5.9   13.5
2.0   6.9   22.3  122.2
3.0  14.7   72.1  312.8
4.0  19.6  145.6  789.4

2
8  0.5
0.0   0.0    0.0    0.0
0.5   1.1    1.5    7.5
1.0   1.7    3.4   17.1
1.5   3.1   11.2   43.9
2.0   5.2   32.4   98.5
2.5   7.2   49.2  187.4
3.0   9.2   86.4  312.5
3.5  12.1  143.1  624.9

3
5  1.0
0.0   0.0    0.0    0.0
1.0   2.2    5.4   15.5
2.0   6.6   15.3  132.2
3.0  15.7   81.8  352.8
4.0  21.4  155.2  839.6


For further clarification, consider table 2 above, corresponding to cross
sectional properties of the four most upstream nodes of link 12.  This table
has 8 entries, each  separated by 0.5 meter of depth.  At a depth of 3.0 m, for
example, the channel has a top-width of 9.2m, a cross-sectional area of 86.4 
m2, and a conveyance of 312.5 m3/s.  The conveyance K is used to calculate the
discharge using:

                    Q=K*sqrt(Slope)

Where using Manning's equation, K is defined as:

                    K=(1.0/n) * Area * Hydraulic_Radius^(2/3)

These tables can be produced easily using a spreadsheet using measured channel
cross-section data.


REFERENCES

Cunge, J.A., F.M. Holly, and A. Verwey, 1980, Practical Aspects of Computational
     River Hydraulics, Iowa Institute of Hydraulic Research, 404HL The
     University of Iowa, Iowa City, IA 52242. 420 p.

Ogden, F.L., 1994, de-St Venant channel routing in distributed hydrologic
     modeling., Proc. Hydraulic Engineering `94, ASCE Hydraulics Specialty
     Conference, G.V. Cotroneo and R.R. Rumer eds., August  1-5,  1994, Buffalo,
     N.Y., pp. 492-496.

Ogden, F.L., Saghafian, B., and W.F.  Krajewski, 1994, GIS-based  channel
     extraction and smoothing  algorithm for  distributed hydrologic  modeling,
     Proc. Hydraulic Engineering `94,  ASCE Hydraulics Specialty  Conference, 
     G.V. Cotroneo and R.R. Rumer eds., August  1-5,  1994, Buffalo,  N.Y.,  pp.
     237-241.

