doublemanning

Package contents

This package contains two command-line utilities * doublemanning-fit inverts stage—discharge data to generate a rating curve and the associated double-Manning-equation parameters: * A Manning's-equation relationships for an approximately rectangular channel * A generalized Manning's equation (power-law) relationship for flows across the floodplain * doublemanning-calc uses this fit to perform forward computations: * Stage → discharge * Flow depth → discharge * Discharge → stage * Discharge → flow depth

Installation

From PyPI using Pip

This command will install the most recent stable release of doublemanning.

bash pip install doublemanning

Editable, from a local directory

These instructions allow you to use the most recent version of doublemanning and to make your own edits.

These instructions assume that you have the GitHub CLI installed. If you do not, just change the repository-cloning line to a standard git command.

bash gh repo clone MNiMORPH/doublemanning cd doublemanning pip install -e .

Running the double-Manning software

You should be able to run both commands by simply typing their names on the command line. Here we provide the outputs form the "-h" help flag. Such outputs are also provided if you enter the commands with no arguments.

doublemanning-fit

Note: Although many command-line options exist to fit the data, I recommend using the YAML configuration-file option alone. This will allow you to access the full functionality of doublemanning-fit (the command-line options include only a smaller subset) and will self-document your work.

```bash

doublemanning-fit -h usage: doublemanning-fit [-h] [-y CONFIGFILE] [-f DATAFILE] [--delimiter DELIMITER] [-b CHANNEL_WIDTH] [-H CHANNEL_DEPTH] [-s SLOPE] [-o OUTFILE] [--use_depth] [--us_units] [--plot] [-v]

Pass channel and flow characteristics to obtain a "Double Manning" -- Manning\'s Equation (channel) + generic power-law (floodplain) stage--discharge -- relationship.

options: -h, --help show this help message and exit -y CONFIGFILE, --configfile CONFIGFILE YAML file from which all inputs are read. -f DATAFILE, --datafile DATAFILE file with two columns: Discharge, Stage --delimiter DELIMITER "tab", "comma", or "semicolon" -b CHANNELWIDTH, --channelwidth CHANNELWIDTH river-channel width -H CHANNELDEPTH, --channeldepth CHANNELDEPTH river-channel depth (not flow depth) -s SLOPE, --slope SLOPE channel slope -o OUTFILE, --outfile OUTFILE Stores fit parameters. --usedepth Use flow depth instead of hydraulic radius. --usunits Convert imported data from cfs and feet --plot Plot stage-discharge relationship -v, --verbose Plot stage-discharge relationship ```

doublemanning-calc

The doublemanning-calc program returns a scalar value to stdout.

```bash

doublemanning-calc -h usage: doublemanning-calc [-h] [-p PARAMFILE] [-zQ STAGEDISCHARGE] [-hQ DEPTHDISCHARGE] [-Qz DISCHARGESTAGE] [-Qh DISCHARGEDEPTH]

Return stage or discharge based on a double-Manning fit. All values are SI (mks).

options: -h, --help show this help message and exit -p PARAMFILE, --paramfile PARAMFILE CSV file for double-Manning parameters. -zQ STAGEDISCHARGE, --stagedischarge STAGEDISCHARGE Calculate discharge from this stage. -hQ DEPTHDISCHARGE, --depthdischarge DEPTHDISCHARGE Calculate discharge from this flow depth. -Qz DISCHARGESTAGE, --dischargestage DISCHARGESTAGE Calculate stage from this discharge. -Qh DISCHARGEDEPTH, --dischargedepth DISCHARGEDEPTH Calculate flow depth from this discharge. ```

Physical and mathematical basis

Core equation

The double-Manning approach applies the following combination of Manning's equation for in-channel flows (left of the $+$ sign) and a power-law equation for overbank flow (right of the $+$ sign):

$$Q = \frac{b}{n\mathrm{ch}} h Rh^{2/3} S^{1/2} + k\mathrm{fp} \left(h - h\beta \right)^{P_\mathrm{fp}}$$

Variables

| Variable | Description | Units [SI] | |-----------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------| | $Q$ | Discharge | $\mathrm{m}^3 \text{ s}^{-1}$ | | $b$ | Channel width | m | | $B$ | Valley-bottom width | m | | $B-b$ | Floodplain width | m | | $zb$ | River-bed elevation (compared to an arbitrary datum) | m | | $zs$ | River stage: water-surface elevation (compared to the same arbitrary datum) | m | | $h$ | Flow depth: $h = zs - zb$ | m | | $hb$ | Channel-bank height | m | | $Rh$ | Hydraulic radius; for the assumed rectangular channel, $Rh = b \cdot h / (b + 2 (h \wedge h\beta) )$ | m | | $n\mathrm{ch}$ | Manning's roughness coefficient within the channel | $\mathrm{s} \text{ m}^{-1/3}$ | | $S$ | River-channel slope | — | | $k\mathrm{fp}$ | Floodplain-flow coefficient | $\mathrm{m}^{3 - P\mathrm{fp}} \text{ s}^{-1}$ | | $P\mathrm{fp}$ | Floodplain-flow exponent | — |

Example

Because playing a game is usually quicker and more fun than reading the rules, we provide data and a YAML configuration file for the Minnesota River near Jordan, MN, USA, USGS gauge 05330000. config.yaml is commented and hopefully self-documented well enough; please open an "Issue" if you need some clarification.

Running doublemanning-fit: obtaining the coefficients and plotting the result

cd to the examples/MinnesotaJordan directory.

bash doublemanning-fit -y config.yaml

config.yaml

This is the same config.yaml file from the example.

```yaml river: Minnesota station: Jordan

author: Andy Wickert

data: # Filename expected with columns "Q", "Stage" filename: 'MinnesotaJordan.tsv' # tab, space, or comma delimiter: 'tab' # If data set uses US cfs (Q) and feet (Stage), converts these to metric. us-units: True

channel: # meters; if ommitted, will be solved for as a free variable width: 100 # meters; if omitted, will be solved for as a free variable # depth: # unitless slope: 1E-4 # Use depth instead of hydraulic radius for calculations. True/False. use_depth: False

bounds: # Uncomment the following to set them different from the defaults # They should be given in LOWER, UPPER # Estimated from clast count: 0.365 # Range for mountain streams with gravel + few boulders: 0.03--0.05 manningsnbounds: - 0.025 - 0.06 # Floodplain characteristics: # * Approximately rectangular # * 9 m wide (- channel = 6.5 m) # * 0.8 m high above channel (so 1.6 total) -- but assume infinite # * Manning's n for heavy timber or med-to-dense brush ~0.1 # kfp = (B-b)/n * S^(1/2) = 17.9 #floodplaincoeffbounds: # - 0 # - 200 floodplainexponentbounds: - 1 - 4 stageoffsetbounds: # On Google Sheet, I have + 7 cm for 2020 onwards. # And 10 cm from the start, to which this is now referenced - -1 - 1 channeldepthbounds: - 4 - 10 #channelwidth_bounds: # - 60 # - 100

plotting: # If this is present, the plot will be saved. # Format set by file extension. # Path may be relative or absolute savepath: 'MinnesotaRiverJordan.pdf' # True/False Boolean flag show: True # Optional fixed plotting bounds stagemin: -0.001 stagemax: 12 #dischargemin: dischargemax: 3500 # Plot curve even if discharge is negative (nonphysical) displaynegativeratingcurve: False # Markers and lines for stage offsets and bank heights stageoffsethashbottom: False stageoffsethashtop: False stageoffsetdottedline: True bankheighthashbottom: False bankheighthashtop: False bankheightdottedline: True

output: # CSV output file name or full path outfile: 'doublemanningparamsMinnesotaJordan.csv' # True/False Boolean flag verbose: True ```

Outputs from the double-Manning inversion

doublemanning-fit outputs the following table displaying the parameter estimation.

|Manning's n |Floodplain discharge coefficient|Floodplain discharge exponent|Stage at Q = 0 [m] |Bank height [m] |Channel width [m]|Channel slope|SD: Manning's n |SD: Floodplain discharge coefficient|SD: Floodplain discharge exponent|SD: Stage at Q = 0 [m]|SD: Bank height [m] |SD: Channel width [m]|SD: Channel slope|Fit RMSE [m^3/s] |Use flow depth instead of Rh| |--------------------|--------------------------------|-----------------------------|-------------------|-----------------|-----------------|-------------|---------------------|------------------------------------|---------------------------------|----------------------|---------------------|---------------------|-----------------|------------------|----------------------------| |0.033831468015063926|138.36638842157538 |1.6166749803210574 |0.47064363991612973|5.797468642861781|100.0 |0.0001 |1.830532636088621e-13|163822.52280191344 |4.139278869596877e-05 |4.002253904290435e-06 |9.715555430266482e-05|0 |0 |44.612476854901466|False |

In addition, doublemanning-fit with the provided config.yaml outputs a figure. Here, we have altered config.yaml from the version provided here in order to output a svg instead of a pdf.

Here, the data points are in black and the double-Manning rating curve is in thick, solid, gray. The thin vertical dotted gray lines represent (left) the stage at which discharge = 0, corresponding to the river bed in the approximately rectangular channel ($zb$), and (right) the stage at which flow enters the floodplain, $zs = zb + z\beta$.

Running doublemanning-calc: Obtaining stage or water depth from discharge (and vice versa)

With the parameter-estimation CSV file in hand, you may next perform forward calculations to calculate either water depth (or river stage) from discharge, or compute discharge from river depth (or flow stage).

```bash

First, let's find discharge based on a provided flow stage

In this case, let's try 7 meters, which corresponds to an overbank flood.

doublemanning-calc -p doublemanningparamsMinnesotaJordan.csv -zQ 7 633.0231625564036

Next, let's pass this discharge to recover our 7-meter stage.

doublemanning-calc -p doublemanningparamsMinnesotaJordan.csv -Qz 633.0231625564036 7.000000000000001

Yay!

```

Acknowledgements

• Campbell Dunn created an early version of the command-line interface to doublemanning-fit.
• Jabari Jones assembled the USGS data for the Minnesota River gauge near Jordan.

Funding

Funding for this project comes from: * The Alexander von Humboldt-Stiftung through a Humboldt-Forschungsstipendium provided to A. Wickert. * The U.S. National Science foundation via Award [1944782: CAREER: Alluvial river dynamics through watershed networks] to A. Wickert.