Package: doublemanning
doublemanningPackage contentsThis package contains two command-line utilitiesdoublemanning-fitinverts stage—discharge data to generate a rating curve and the associated double-Manning-equation parameters:A Manning's-equation relationships for an approximately rectangular channelA generalized Manning's equation (power-law) relationship for flows across the floodplaindoublemanning-calcuses this fit to perform forward computations:Stage → dischargeFlow depth → dischargeDischarge → stageDischarge → flow depthInstallationFrom PyPI using PipThis command will install the most recent stable release ofdoublemanning.pipinstalldoublemanningEditable, from a local directoryThese instructions allow you to use the most recent version ofdoublemanningand 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 standardgitcommand.ghrepocloneMNiMORPH/doublemanningcddoublemanning
pipinstall-e.Running the double-Manning softwareYou 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-fitNote:Although many command-line options exist to fit the data, I recommend using theYAMLconfiguration-file option alone. This will allow you to access the full functionality ofdoublemanning-fit(the command-line options include only a smaller subset) and will self-document your work.>>doublemanning-fit-h
usage:doublemanning-fit[-h][-yCONFIGFILE][-fDATAFILE][--delimiterDELIMITER][-bCHANNEL_WIDTH][-HCHANNEL_DEPTH][-sSLOPE][-oOUTFILE][--use_depth][--us_units][--plot][-v]Passchannelandflowcharacteristicstoobtaina"Double Manning"--
Manning\'sEquation(channel)+genericpower-law(floodplain)stage--discharge
--relationship.

options:-h,--helpshowthishelpmessageandexit-yCONFIGFILE,--configfileCONFIGFILEYAMLfilefromwhichallinputsareread.-fDATAFILE,--datafileDATAFILEfilewithtwocolumns:Discharge,Stage--delimiterDELIMITER"tab","comma",or"semicolon"-bCHANNEL_WIDTH,--channel_widthCHANNEL_WIDTHriver-channelwidth-HCHANNEL_DEPTH,--channel_depthCHANNEL_DEPTHriver-channeldepth(notflowdepth)-sSLOPE,--slopeSLOPEchannelslope-oOUTFILE,--outfileOUTFILEStoresfitparameters.--use_depthUseflowdepthinsteadofhydraulicradius.--us_unitsConvertimporteddatafromcfsandfeet--plotPlotstage-dischargerelationship-v,--verbosePlotstage-dischargerelationshipdoublemanning-calcThedoublemanning-calcprogram returns a scalar value tostdout.>>doublemanning-calc-h
usage:doublemanning-calc[-h][-pPARAMFILE][-zQSTAGE_DISCHARGE][-hQDEPTH_DISCHARGE][-QzDISCHARGE_STAGE][-QhDISCHARGE_DEPTH]Returnstageordischargebasedonadouble-Manningfit.AllvaluesareSI(mks).

options:-h,--helpshowthishelpmessageandexit-pPARAMFILE,--paramfilePARAMFILECSVfilefordouble-Manningparameters.-zQSTAGE_DISCHARGE,--stage_dischargeSTAGE_DISCHARGECalculatedischargefromthisstage.-hQDEPTH_DISCHARGE,--depth_dischargeDEPTH_DISCHARGECalculatedischargefromthisflowdepth.-QzDISCHARGE_STAGE,--discharge_stageDISCHARGE_STAGECalculatestagefromthisdischarge.-QhDISCHARGE_DEPTH,--discharge_depthDISCHARGE_DEPTHCalculateflowdepthfromthisdischarge.Physical and mathematical basisCore equationThe 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 R_h^{2/3} S^{1/2} + k_\mathrm{fp} \left(h - h_\beta \right)^{P_\mathrm{fp}}$$VariablesVariableDescriptionUnits [SI]$Q$Dischargem$\mathrm{m}^3 \text{ s}^{-1}$$b$Channel widthm$B$Valley-bottom widthm$B-b$Floodplain widthm$z_b$River-bed elevation (compared to an arbitrary datum)m$z_s$River stage: water-surface elevation (compared to the same arbitrary datum)m$h$Flow depth: $h = z_s - z_b$m$h_b$Channel-bank heightm$R_h$Hydraulic radius; for the assumed rectangular channel, $R_h = b \cdot h / (b + 2 (h \wedge h_\beta) )$m$n_\mathrm{ch}$Manning's roughness coefficient within the channelm$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—ExampleBecause playing a game is usually quicker and more fun than reading the rules, we provide data and a YAML configuration file for theMinnesota River near Jordan, MN, USA, USGS gauge05330000.config.yamlis commented and hopefully self-documented well enough; please open an "Issue" if you need some clarification.Runningdoublemanning-fit: obtaining the coefficients and plotting the resultcdto theexamples/MinnesotaJordandirectory.doublemanning-fit-yconfig.yamlconfig.yamlThis is the sameconfig.yamlfilefrom the example.river:Minnesotastation:Jordanauthor:Andy Wickertdata:# Filename expected with columns "Q", "Stage"filename:'MinnesotaJordan.tsv'# tab, space, or commadelimiter:'tab'# If data set uses US cfs (Q) and feet (Stage), converts these to metric.us-units:Truechannel:# meters; if ommitted, will be solved for as a free variablewidth:100# meters; if omitted, will be solved for as a free variable# depth:# unitlessslope:1E-4# Use depth instead of hydraulic radius for calculations. True/False.use_depth:Falsebounds:# 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.05mannings_n_bounds:-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# k_fp = (B-b)/n * S^(1/2) = 17.9#floodplain_coeff_bounds:#    - 0#    - 200floodplain_exponent_bounds:-1-4stage_offset_bounds:# On Google Sheet, I have + 7 cm for 2020 onwards.# And 10 cm from the start, to which this is now referenced--1-1channel_depth_bounds:-4-10#channel_width_bounds:#    - 60#    - 100plotting:# If this is present, the plot will be saved.# Format set by file extension.# Path may be relative or absolutesavepath:'MinnesotaRiver_Jordan.pdf'# True/False Boolean flagshow:True# Optional fixed plotting boundsstage_min:-0.001stage_max:12#discharge_min:discharge_max:3500# Plot curve even if discharge is negative (nonphysical)display_negative_rating_curve:False# Markers and lines for stage offsets and bank heightsstage_offset_hash_bottom:Falsestage_offset_hash_top:Falsestage_offset_dotted_line:Truebank_height_hash_bottom:Falsebank_height_hash_top:Falsebank_height_dotted_line:Trueoutput:# CSV output file name or full pathoutfile:'doublemanning_params_MinnesotaJordan.csv'# True/False Boolean flagverbose:TrueOutputs from the double-Manning inversiondoublemanning-fitoutputs the following table displaying the parameter estimation.Manning's nFloodplain discharge coefficientFloodplain discharge exponentStage at Q = 0 [m]Bank height [m]Channel width [m]Channel slopeSD: Manning's nSD: Floodplain discharge coefficientSD: Floodplain discharge exponentSD: Stage at Q = 0 [m]SD: Bank height [m]SD: Channel width [m]SD: Channel slopeFit RMSE [m^3/s]Use flow depth instead of Rh0.033831468015063926138.366388421575381.61667498032105740.470643639916129735.797468642861781100.00.00011.830532636088621e-13163822.522801913444.139278869596877e-054.002253904290435e-069.715555430266482e-050044.612476854901466FalseIn addition,doublemanning-fitwith the providedconfig.yamloutputs a figure. Here, we have alteredconfig.yamlfrom the version provided here in order to output asvginstead of apdf.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 ($z_b$), and (right) the stage at which flow enters the floodplain, $z_s = z_b + z_\beta$.Runningdoublemanning-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).# 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-pdoublemanning_params_MinnesotaJordan.csv-zQ7633.0231625564036# Next, let's pass this discharge to recover our 7-meter stage.doublemanning-calc-pdoublemanning_params_MinnesotaJordan.csv-Qz633.02316255640367.000000000000001# Yay!AcknowledgementsCampbell Dunn created an early version of the command-line interface todoublemanning-fit.Jabari Jones assembled the USGS data for the Minnesota River gauge near Jordan.FundingFunding for this project comes from:The Alexander von Humboldt-Stiftung through aHumboldt-Forschungsstipendiumprovided to A. Wickert.The U.S. National Science foundation via Award [1944782: CAREER: Alluvial river dynamics through watershed networks] to A. Wickert.