S I R E N
SImulation of flow in River channels Network
--------------------------------------------






The program SiReN runs numerical simulations of steady
or transient subcritical flows in networks of river channels
by semi-conservative form of the Saint-Venant's equations:

  ∂A     ∂Q
  --  +  --  =  q
  ∂t     ∂x

  ∂Q      ∂     2                 dH
  --  +  --  ∫ v dA  +  g A (Sf + --- )  =  0
  ∂t     ∂x                       dx

where:

   t = time [sec],
   x = longitudinal coordinate [m],
   Q = flow rate [m^3/sec],
   A = active cross-section [m^2],
   H = water level [m],
   h = flow depth [m],
   Z = bottom level [m],
   g = gravitational acceleration [m/sec^2],
   Sf= friction term after Manning [],
   q = inflow rate per unit length [m^2/sec].

Approximate solution is achieved by finite-difference method
with implicit Preissmann's scheme applied.

The river bed can have cross-sections of arbitrary shape and parameters
variable along the reach.

Modelling of the IBV problem requires initial and boundary conditions
to be defined. They should provide existence, uniqueness and
stability of solution. For dydactic purposes the package admits
some ill-posed boundary conditions. Definition of boundary
conditions should be included in the file with description
of system geometry. The model assumes, that:
  -- subcritical flow regime needs 1 boundary condition at each reach end.
  -- boundary conditions should be given at first and last node and possibly in
     internal segments between nodes.
  -- all hydrographs should be placed in separate files.

Boundary conditions possible to apply are the following:

- Stage and discharge hydrographs
- Q(H) - type dependence, given by:
       - rating curve approximated by polynomial:
                Q(H) = a0 + a1 H + a2 H^2 + a3 H^3,
       - rating curve approximated by exponential function:
                Q(H) = a0 (H-a1)^a2,
       - sharp-crested weir formula:
                Q(H) = W C Sqrt(2g) ((H-Z+Hv)^(3/2) - Hv^(3/2)),
       - wide-crested weir formula:
       - underflow gate formula:
                Q(H) = W m a Sqrt(2g) (H0-Z)^(1/2)
              with
                m = psi/(1 + (a psi)/H0)
       - characteristic signal "from infinity".
- Other dependencies:
       - mass advection,
       - depth gradient,
       - Manning's rating curve.
- Channel junctions:
       - with tributary inflow/outflow and energy loss factor,
       - junction/bifurcation based on balance equations,
       - junction/bifurcation based on energy line concept.
       - junction/bifurcation based on 2-d momentum balance.

It is possible to model flow with full dynamic equation,
with simplified diffusion wave approximation or with kinematic wave approximation.
In the latter case, downstream boundary codition is neglected,
since no backwater effects take place.

Current program version can illustrate results of computations in the form of
longitudinal flow profile, cross-section views, 3D projective views, 
series of hydrographs or phase portraits, as shown below.
It is also possible to animate sequence of previously recorded results.













For nice color resolution, it is devised to use at least 256-color interface.
The program can be run under the following operating systems:
DOS in DPMI mode with BGI interface,
OS/2 Warp with PMShell interface,
Linux with GTK+ interface, 
Win32 with GTK+ interface.
Portable GUI environment has been successfully built upon GTK+ interface
at the beginnig of 2004.

All parameters used by the code, namely:
-- geometric and hydraulic properties of the system,
-- definition of boundary conditions,
-- system state functions,
-- numerical options and parameters,
-- visualization preferences,
-- file system preferences,
can be saved and retrieved in text files. 
Now I make some decisions that would allow to read and write XML-based data.

Internal parameters have predefined default values, that are valid until explicit change.
As now, the program runs mainly in batch mode, although several parameters
can be changed interactively during the session.

Instead of transient flow modelling, the user can choose asymptotic steady solution,
one step steady solution computations, or stepwise steady solution computations
(unless the bed system creates a network).

Time-weighted Crank-Nicholson method has been used for approximate time evolution operator.
Exact Jacobi matrix is evaluated for nonlinear iterative Newton-Raphson solver.


The Shallow Water Diffusion Wave Approximation Module, named ShaDE,
has become a part of the SiReN code. It is designed to model
two-dimensional diffusive wave approximation over arbitrary surface.
Diffusion wave is the specific form of the shallow water equation
with inertial term neglected. In this case streamlines are tangent
to the free surface gradient. The discharge can be expressed as
                Q = - K(x,H) Sqrt(Grad H) .
This approximation can be used to model flow with relatively small
velocities, for example, in flood areas.

The flux field is approximated directly from the reduced dynamic equation
and substituted to the mass balance. Hence, the spatial discretization
can be considered as (H,Q)-staggered.
Totally and partially dry surfaces are allowed.


                                                Jan Jełowicki
                                                Wrocław 1997-2004