THe wflow_wave Model

Warning

The documentation of this model is incomplete

Introduction

An experimental implementation of the full dynamic wave equations has been implemented. The current implementation is fairly unstable and very slow.

However, in flat of tidal areas and areas that flood the dynamic wave can provide much better results. The plot below is from the Rio Mamore in Bolivia in the lower partes of the river with extensive wetlands that flood nearly each year.

(Source code, png, hires.png, pdf)

Dependencies

This module is setup to be run in an existing case and runid of a wflow_sbm or wflow_hbv model. In order for wflow_wave to run they must have saved discharge and waterlevel for each timesteps. This output will be used as a forcing for the dynamic wave module. The wflow_wave module will also use the existing ldd and DEM

Configuration

It needs anumber of settings in the ini file. The default name for the file is wflow_wave.ini. it is also possible to insert this section in the wflow_sbm or wflow_hbv ini file and point to that file.

See below for an example:

[inputmapstacks]
# Name of the mapstack with discharge (output from the hydrological model)
Q = run
# Name of the mapstack with waterlevel (output from the hydrological model)
H = lev

[dynamicwave]

# Number of timeslices per dynamic wave substep
TsliceDyn=100

# number of substeps for the dynamic wave with respect to the model timesteps
dynsubsteps=24

# map with level boundary points
wflow_hboun = staticmaps/wflow_outlet.map

# Optional river map for the dynamic wave that must be the same size or smaller as that of the
# kinematic wave
wflow_dynriver = staticmaps/wflow_dynriver.map

# a fixed water level for each non-zero point in the wflow_hboun map
# level > 0.0 use that level
# level == 0.0 use supplied timeseries (see levelTss)
# level < 0.0 use upstream water level
fixedLevel = 3.0

# if this is set the program will try to keep the volume at the pits at
# a constant value
lowerflowbound = 1

# instead of a fixed level a tss file with levels for each timesteps and each
# non-zero value in the wflow_hboun map
#levelTss=intss/Hboun.tss

# If set to 1 the program will try to optimise the timestep
# Experimental, mintimestep is the smallest to be used
AdaptiveTimeStepping = 1
mintimestep =0.1

A description of the implementation of the dynamicwave is given on the pcraster website.

In addition to the settings in the ini file you need to give the model additional maps or lookuptables in the staticmaps or intbl directories:

• ChannelDepth.[map|tbl] - depth of the main channel in metres
• ChannelRoughness.[map|tbl] - 1/n n = manning roughness coefficient (default = 1/0.03)
• ChannelForm.[map|tbl] - form of the channel (default = 1.0)
• FloodplainWidth.[map|tbl] - width of the floodplain in metres (default = 0)

The following variables for the dynamicwave function are set as follows and are taken from the hydrological model run by default:

• ChannelBottomLevel - Taken from the dem (wflow_dem.map in the staticmaps dir)
• ChannelLength - Taken from the length in the kinematic wave (DCL.map from the outsum dir)
• ChannelBottomWidth - taken from the wflow_riverwidth map from the outsum dir

wflow_wave module documentation

Definition of the wflow_wave model.

Runs the pcraster dynamic wave based on the output from the kinematic wave.

The wflow_sbm|hbv model must have saved mapstacks for water level and discharge for each timestep (run*****.*** and lev*****.***). If the name of you Q and/or H maps are different specify these in the [inputmapstacks] section, e.g:

[inputmapstacks]
Q = run
H = lev

The Settings for the dynamic wave itself should be put in the [dynamicwave] section of the ini file.

[dynamicwave]
# Switch on dynamic wave for main rivers
    
# Number of timeslices per dynamic waven substep
TsliceDyn=900

# number of substeps for the dynamic wave with respect to the model timesteps
dynsubsteps=24

# map with level boundary points
#wflow_hboun = staticmaps/wflow_outlet.map

# Optional river map for the dynamic wave that must be the same size or smaller as that of the
# kinematic wave
wflow_dynriver = staticmaps/wflow_dynriver.map

# a fixed water level for each non-zero point in the wflow_hboun map 
# level > 0.0 use that level
# level == 0.0 use timeseries
# level < 0.0 use upstream water level
fixedLevel = -8.0

# If this is set to one the program will try to keep the volume at the pits at a constant level
lowerflowbound=1

# instead of a fixed level a tss file with levels for each timesteps and each 
# non-zero value in the wflow_hboun map
#levelTss=intss/Hboun.tss
#AdaptiveTimeStepping=1

Usage: wflow_wave -C case -R Runid -c inifile -h

-C: set the name of the case (directory) to run

-R: set the name runId within the current case

-I: generate initial conditions from scratchs

-c name of the config file (in the case directory)

-F: if set wflow is expected to be run by FEWS. It will determine

the timesteps from the runinfo.xml file and save the output initial conditions to an alternate location. The runinfo.xml file should be located in the inmaps directory of the case. Also set fewsrun=1 in the .ini file!

-h displays help information

-l: loglevel (most be one of DEBUG, WARNING, ERROR)

$Author$ $Id$ $Rev$

class wflow_wave.WflowModel(cloneMap, Dir, RunDir, configfile)

Bases: pcraster.framework.dynamicPCRasterBase.DynamicModel

The user defined model class. This is your work!

dynamic()

Required

This is where all the time dependent functions are executed. Time dependent output should also be saved here.

Variables:

• self.FloodPlainVol – Volume of water in the floodplain [m^3]
• self.ChannelVol – Volume of water in the channel [m^3]
• self.WaterLevelDyn – Water Level [m]
• self.SurfaceRunoffDyn – Discharge [m^3/s]

initial()

Required

Initial part of the model, executed only once. It reads all static model information (parameters) and sets-up the variables used in modelling.

This function is required. The contents is free. However, in order to easily connect to other models it is advised to adhere to the directory structure used in the other models.

resume()

reads the initial conditions:

Variables:

• self.WaterLevelDyn – Dynamic wave waterlevel [m]
• self.SurfaceRunoffDyn – Dynamic wave surface runoff [m^3/s]

runDynamicWave()

Runs the dynamic wave for the main river Beware: Experimental, very slow and unstable

stateVariables()

Required

Returns a list of state variables that are essential to the model. This list is essential for the resume and suspend functions to work.

This function is specific for each model and must be present. This is where you specify the state variables of you model. If your model is stateless this function must return and empty array (states = [])

Variables:

• SurfaceRunoffDyn.map – Discharge in m^3/sec
• WaterLevelDyn.map – Discharge in m

supplyCurrentTime()

Optional

Supplies the current time in seconds after the start of the run This function is optional. If it is not set the framework assumes the model runs with daily timesteps.

Ouput:

• time in seconds since the start of the model run

suspend()

Suspends the model to disk. All variables needed to restart the model are saved to disk as pcraster maps. Use resume() to re-read them

wflow_wave.main(argv=None)

Optional

Perform command line execution of the model. This example uses the getopt module to parse the command line options.

The user can set the caseName, the runDir, the timestep and the configfile.

wflow_wave.usage(*args)