Package 'rivr'

Title: Steady and Unsteady Open-Channel Flow Computation
Description: A tool for undergraduate and graduate courses in open-channel hydraulics. Provides functions for computing normal and critical depths, steady-state water surface profiles (e.g. backwater curves) and unsteady flow computations (e.g. flood wave routing) as described in Koohafkan MC, Younis BA (2015). "Open-channel computation with R." The R Journal, 7(2), 249–262. <doi: 10.32614/RJ-2015-034>.
Authors: Michael C Koohafkan [aut, cre]
Maintainer: Michael C Koohafkan <[email protected]>
License: GPL (>= 3)
Version: 1.2-3
Built: 2025-03-02 04:34:15 UTC
Source: https://github.com/mkoohafkan/rivr

Help Index


Steady and Unsteady Open-Channel Flow Computation

Description

This package is designed as an educational tool for students and instructors of undergraduate courses in open channel hydraulics. Functions are provided for computing normal and critical depths, steady (e.g. backwater curves) and unsteady (flood wave routing) flow computations for prismatic trapezoidal channels. See the vignettes to get started.


Channel geometry

Description

Compute geometry relations for trapezoidal channels.

Usage

channel_geom(y, B, SS)

Arguments

y

Flow depth [LL].

B

Channel bottom width [LL].

SS

Channel sideslope [LL1L L^{-1}]. For a rectangular channel, SS = 0.

Details

Channel geometry relations are routinely calculated in numerical solutions of steady, gradually-varied and unsteady flows. This function is used extensively by internal procedures and is made accessible to the user for convenience.

Value

Named vector:

A

Flow area [L2L^2].

P

Wetted perimeter [LL].

R

Hydraulic radius [LL].

dAdy

Water surface width [LL].

dPdy

First derivative of wetted perimeter w.r.t. flow depth.

dRdy

First derivative of hydraulic radius w.r.t. flow depth.

DH

Hydraulic depth [LL].

ybar

Vertical distance from water surface to centroid of flow area [LL].

Examples

channel_geom(1.71, 100, 0) # rectangular channel
channel_geom(5.79, 6.1, 1.5) # trapezoidal channel with sideslope 3H:2V

Gradually-varied flow profiles

Description

Compute the gradually-varied flow profile of a prismatic channel.

Usage

compute_profile(
  So,
  n,
  Q,
  y0,
  Cm,
  g,
  B,
  SS,
  z0 = 0,
  x0 = 0,
  stepdist,
  totaldist
)

Arguments

So

Channel slope [LL1L L^{-1}].

n

Manning's roughness coefficient.

Q

Flow rate [L3T1L^3 T^{-1}].

y0

The water depth at the control section [LL].

Cm

Unit conversion coefficient for Manning's equation. For SI units, Cm = 1.

g

Gravitational acceleration [LT2L T^{-2}].

B

Channel bottom width [LL].

SS

Channel sideslope [LL1L L^{-1}].

z0

Elevation reference datum at control section [LL]. Default is 0.

x0

Distance reference at control section [LL]. Default is 0.

stepdist

The spatial interval used in the Standard step method [LL].

totaldist

The total distance upstream (or downstream) to compute the profile [LL].

Details

Computes the longitudinal water surface profile of a prismatic channel using the standard step method by solving the non-linear ODE

dydx=S0Sf1Fr2\frac{dy}{dx} = \frac{S_0 - S_f}{1 - Fr^2}

The standard-step method operates by stepping along the channel by a constant distance interval, starting from a cross-section where the flow depth is known (the control section). The flow depth is computed at the adjacent cross-section (target section). The computed value at the target is then used as the basis for computing flow depth at the next cross-section, i.e. the previous target section becomes the new control section for each step. A Newton-Raphson scheme is used each step to compute the flow depth and friction slope. Technically, the average friction slope of the control and target section is used to compute the flow depth at the target section.

Value

data.frame with columns:

x

Along-channel distance.

z

Elevation.

y

Flow depth.

v

Flow velocity.

A

Flow area.

Sf

Friction slope.

E

Total energy.

Fr

Froude Number.

Examples

# example M1 profile
compute_profile(0.001, 0.045, 250, 2.7, 1.486, 32.2, 100, 0, stepdist = 10, totaldist = 3000)
# example M2 profile
compute_profile(0.001, 0.045, 250, 0.64, 1.486, 32.2, 100, 0, stepdist = 10, totaldist = 3000)
# example S2 profile
compute_profile(0.005, 0.01, 250, 2.65, 1.486, 32.2, 10, 0, stepdist = 10, totaldist = 2000)
# example S3 profile
compute_profile(0.005, 0.01, 250, 0.5, 1.486, 32.2, 10, 0, stepdist = 10, totaldist = 2000)

Channel conveyance

Description

Calculate the channel conveyance.

Usage

conveyance(n, A, R, Cm)

Arguments

n

Manning's roughness coefficient (dimensionless).

A

Flow area [L2L^2].

R

Hydraulic radius [LL].

Cm

Unit conversion coefficient for Manning's equation. For SI units, Cm = 1.

Details

Channel conveyance is routinely calculated in numerical solutions of steady, gradually-varied and unsteady flows. This function is used extensively by internal procedures and is made accessible to the user for convenience.

Value

The channel conveyance.


Critical depth

Description

Calculate the critical depth.

Usage

critical_depth(Q, yopt, g, B, SS)

Arguments

Q

Flow rate [L3T1L^3 T^{-1}].

yopt

Initial guess for normal depth [LL].

g

Gravitational acceleration [LT2L T^{-2}].

B

Channel bottom width [LL].

SS

Channel sideslope [LL1L L^{-1}].

Details

The critical depth is the water depth at which a channel flow regime will transition from supercritical to subcritical (or vice versa). Calculation of the critical depth is based on a specific energy formulation, i.e.

E=y+z+Q22gB2y2E = y + z + \frac{Q^2}{2gB^2y^2}

where yy is the flow depth, zz is the elevation relative to some datum (assumed to be 0), and the last term represents kinetic energy. More specifically, the function operates by finding the point where the derivative of specific energy w.r.t. yy is zero, i.e. y=ycy = y_c when

dEdy=1Q2gA3dAdy=0\frac{dE}{dy} = 1 - \frac{Q^2}{gA^3}\frac{dA}{dy} = 0

.

Value

The critical depth ycy_c [LL].

Examples

critical_depth(250, 2, 32.2, 100, 0) # rectangular channel
critical_depth(126, 1, 9.81, 6.1, 1.5) # trapezoidal channel with sideslope 3H:2V

Shiny Demonstrations

Description

Demonstrate package functionality via Shiny apps

Usage

demo_shiny(ex)

Arguments

ex

Example to run.

Details

Demonstrations available: "gvf" Gradually-varied flow.

Examples

## Not run: 
# get list of available demos
demo_shiny()
# run the gradually-varied flow demo
demo_shiny("gvf")

## End(Not run)

Froude Number

Description

Calculate the Froude Number.

Usage

froude(Q, g, A, DH)

Arguments

Q

Flow rate [L3T1L^3 T^{-1}].

g

Gravitational acceleration [LT2L T^{-2}].

A

Flow area [L2L^2].

DH

Hydraulic depth [LL].

Details

The Froude number is a dimensionless measure of bulk flow characteristics that represents the relative importance of inertial forces and gravitational forces. For open channel flow, the Froude number of open channel flow is defined as

Fr=vgDHFr = \frac{v}{\sqrt{gD_H}}

where v=QAv = \frac{Q}{A} is the flow velocity, gg is the gravitational acceleration and DHD_H is the hydraulic depth. The Froude number is related to the energy state of the flow and can be used to identify flows as either supercritical (Fr<1Fr < 1) or subcritical (Fr>1Fr > 1).

Value

The Froude Number (dimensionless).

Examples

froude(250, 32.2, 171, 1.71) # subcritical flow
froude(250, 32.2, 57.9, 0.579) # critical flow
froude(250, 32.2, 45, 0.45) # supercritical flow

Normal depth

Description

Calculate the normal (equilibrium) depth using Manning's equation.

Usage

normal_depth(So, n, Q, yopt, Cm, B, SS)

Arguments

So

Channel slope [LL1L L^{-1}].

n

Manning's roughness coefficient.

Q

Flow rate [L3T1L^3 T^{-1}].

yopt

Initial guess for normal depth [LL].

Cm

Unit conversion coefficient for Manning's equation. For SI units, Cm = 1.

B

Channel bottom width [LL].

SS

Channel sideslope [LL1L L^{-1}].

Details

The normal depth is the equilibrium depth of a channel for a given flow rate, channel slope, geometry and roughness. Manning's equation is used to calculate the equilibrium depth. Manning's equation for normal flow is defined as

Q=CmnAR2/3S01/2Q = \frac{C_m}{n} AR^{2/3}S_0^{1/2}

where QQ is the channel flow, S0S_0 is the channel slope, AA is the cross-sectional flow area, RR is the hydraulic depth and CmC_m is a conversion factor based on the unit system used. This function uses a Newton-Raphson root-finding approach to calculate the normal depth, i.e. y=yny = y_n when

f(y)=A5/3P2/3nQCmS01/2=0f(y) = \frac{A^{5/3}}{P^{2/3}} - \frac{nQ}{C_mS_0^{1/2}} = 0

.

Value

The normal depth yny_n [LL].

Examples

normal_depth(0.001, 0.045, 250, 3, 1.486, 100, 0) # rectangular channel
normal_depth(0.0008, 0.013, 126, 5, 1, 6.1, 1.5) # trapezoidal channel with sideslope 3H:2V

Flood wave routing

Description

Route a flood wave down a prismatic channel.

Usage

route_wave(
  So,
  n,
  Cm,
  g,
  B,
  SS,
  initial.condition,
  boundary.condition,
  downstream.condition,
  timestep,
  spacestep,
  numnodes,
  monitor.nodes,
  monitor.times,
  engine = c("Dynamic", "Kinematic"),
  scheme = c("MacCormack", "Lax"),
  boundary.type = c("QQ", "Qy", "yQ", "yy")
)

Arguments

So

Channel slope [LL1L L^{-1}].

n

Manning's roughness coefficient.

Cm

Unit conversion coefficient for Manning's equation. For SI units, Cm = 1.

g

Gravitational acceleration [LT2L T^{-2}].

B

Channel bottom width [LL].

SS

Channel sideslope [LL1L L^{-1}].

initial.condition

The initial flow rate [L3T1L^3 T^{-1}], assumed constant throughout the channel.

boundary.condition

Vector specifying the upstream boundary condition for the full duration of the model. If engine = "Kinematic", values are assumed to be flow [L3T1L^3 T^{-1}]. If engine = "Dynamic", the form of the boundary condition is determined by the argument boundary.type.

downstream.condition

Only used if engine = "Dynamic". Vector specifying the upstream boundary condition for the full duration of the model. Must be the same length as boundary.condition.

timestep

Temporal resolution of the model. Also the assumed time interval [TT] between elements of boundary.condition and downstream.condition. The user is responsible for ensuring numerical stability.

spacestep

the spatial resolution of the model, interpreted as the distance [LL] between nodes in the model domain. The user is responsible for ensuring numerical stability.

numnodes

The number of nodes used to discretize the channel. The total channel extent is computed as spacestep*(numnodes - 1).

monitor.nodes

the nodes to be monitored every time step. Specified as a vector of node indices, with 1 being the upstream boundary and numnodes being the downstream boundary.

monitor.times

the time steps at which to monitor every node. Specified as a vector of indices of boundary.condition. Defaults to five equally-spaced time steps including the first and last time steps.

engine

The engine to be used for routing the flood wave. May be either "Kinematic" or "Dynamic".

scheme

Only used if engine = "Dynamic". Specifies whether to use the Lax Diffusive scheme or the MacCormack predictor-corrector scheme.

boundary.type

Only used if engine = "Dynamic". Specifies what boundary data is supplied. Possible characters are If boundary.type = "QQ", both boundary.condition and downstream.condition are assumed to be flows [L3T1L^3 T^{-1}]. If boundary.type = "Qy" the upstream boundary is assumed to be flow while the downstream boundary is assumed to be depth [LL]. Other possibilities are "yQ" and "yy".

Details

Provides implementations of a Kinematic Wave Model (KWM) and a Dynamic Wave Model (DWM) with the choice of two numerical schemes. The MacCormack scheme is a second-order accurate predictor-corrector scheme that provides efficient flood wave routing. The Lax diffusive scheme can be used to obtain smooth solutions for problems with discontinuities in the boundary conditions, e.g. sudden gate closures. The DWM implementation uses the Method of Characteristics (MOC) to compute the flow regime at the model boundaries, and allows the user to specify boundaries in terms of depths and/or flows. the KWM implementation assumes the normal depth at the upstream boundary and is only first-order accurate.

Value

data.frame with columns:

step

Time step.

node

Node index.

time

Time since start.

distance

Downstream distance.

flow

Flow rate.

depth

Flow depth.

velocity

Flow velocity.

area

Flow area.

monitor.type

Row refers to a monitored node ("node") or timestep ("timestep").

Examples

## Not run:  
# kinematic wave routing
times = seq(0, 30000, by = 25)
floodwave = ifelse(times >= 9000, 250,
  250 + (750/pi)*(1 - cos(pi*times/(60*75))))
route_wave(0.001, 0.045, 1.486, 32.2, 100, 0, initial.condition = 250, 
  boundary.condition = floodwave, timestep = 25, spacestep = 50, 
  numnodes=301, monitor.nodes = c(1, 101, 201, 301), 
  monitor.times = seq(1, length(times), by = 10), engine = "Kinematic")
# dynamic wave routing with zero-gradient downstream condition using MacCormack scheme
route_wave(0.001, 0.045, 1.486, 32.2, 100, 0, initial.condition = 250, 
  boundary.condition = floodwave, downstream.condition = rep(-1, length(times)), 
  timestep = 25, spacestep = 500, numnodes = 31, engine = "Dynamic", 
  scheme = "MacCormack", monitor.nodes = c(1, 11, 21, 31), 
  monitor.times = seq(1, length(times), by = 10))
# mixed boundary conditions (sudden gate closure) using Lax scheme
lax = route_wave(0.00008, 0.013, 1, 9.81, 6.1, 1.5, 
  initial.condition = 126, boundary.condition = rep(5.79, 2001), 
  downstream.condition = rep(0, 2001), timestep = 1, spacestep = 10, 
  numnodes = 501, monitor.nodes = c(1, 151, 251, 301, 501), 
  monitor.times = c(1, 501, 1001, 1501, 2001), 
  engine="Dynamic", scheme="Lax", boundary.type="yQ")
# extract data for a monitored point
require(dplyr)
filter(lax, monitor.type == "node", node == 151)

## End(Not run)

California Water Olympics

Description

Digitized results from the California Water Olympics. The variables are as follows:

  • t The time (in seconds) since the start of the model run.

  • Q The flow rate [ft3s1ft^3 s^{-1}].

  • x The distance downstream [ftft] at which the hydrograph was recorded.

The data can be used to validate numerical solutions to flood wave routing for a channel under the following conditions:

  • Channel width is 100 feet.

  • Channel slope is 0.001.

  • Channel extent is 150,000 feet.

  • Channel roughness (Manning's n) is 0.045.

  • Channel sideslope is 0 (rectangular channel).

  • Initial flow rate is 250 cfs.

  • Upstream boundary condition is defined as

    Q(t<9000)=250+750π(1cosπt4500)Q(t < 9000) = 250 + \frac{750}{\pi}(1 - \cos{\frac{\pi t}{4500}})

    Q(t>=9000)=250Q(t >= 9000) = 250

Usage

data(waterolympics)

Format

A data frame with 40 rows and 3 variables

References

Sobey, Rodney. "H11: Hydrograph Routing." Review of One-Dimensional Hydrodynamic and Transport Models. Bay-Delta Modeling Forum, 15 June 2001. Web. 13 Mar. 2015. <http://www.cwemf.org/1-DReview/>.