Model help:TopoFlow-Diversions

The CSDMS Help System


This is the diversions component for a D8-based, spatial hydrologic model.

Model introduction

This process component is part of a spatially-distributed hydrologic model called TopoFlow, but it can now be used as a stand-alone model. TopoFlow supports three different types of flow diversions: sources, sinks and canals. Sources are locations such as natural springs where water enters the watershed at a point by some process other than those that are otherwise modeled. Similarly, sinks are locations where water leaves the watershed at a point. Canals are generally man-made reaches such as tunnels or irrigation ditches that transport water from one point to another, typically without following the natural gradient of the terrain that is indicated by the DEM. The upstream end is essentially a sink and the downstream end a source.

Model parameters


Parameter Description Unit
Component status Enabled / Disabled [-]
Input directory The location of the input files [-]
Output directory The location for the output files [-]
Site prefix [-]
Case prefix [-]
Use sources toggle Option to use sources [-]
Sources file source information file [-]
Use sinks toggle Option to use sinks [-]
Sinks file sink information file [-]
Use canals toggle Option to use canals [-]
Canal file canal information file [-]

Uses ports

• Channels (surface water flow in a network of channels with trapezoidal cross-section)

Provides ports

• Diversions (sources, sinks and canals)
• Configure (tabbed dialog GUI to change settings)
• Run (only if used as the Driver)

Main equations

A list of the key equations. HTML format is supported; latex format will be supported in the future


All variables and their units can be seen by expanding the Nomenclature section above.

To use flow diversions, you must provide the required information in specially-formatted text files (see examples below). Where required, vector-valued input variables such as discharges are specified as a list of space-delimited numbers on one line (i.e. terminated by a single end-of-line character). Keys that end with "_ID" refer to the integer value that is assigned to a given pixel (i.e. grid cell) when all pixels in the corresponding DEM are numbered sequentially in calendar order, that is, from top row to bottom row and from left to right within each row. Pixel IDs start at zero and are read and processed as long (4-byte) integers.

Format of a Sources or Sinks File

A "sources" file is a plain text file that starts with 3 key-value pairs that provide information for all sources. This is followed by n_sources blocks (with 3 more key-value pairs each) which each provide information for one of the sources. The six keys are defined as follows. A "sinks" file has the same format as a sources file except the keys "n_sources" and "source_ID" are replaced by "n_sinks" and "sink_ID". A source could be a natural spring where flow enters the system from underground. Flow that enters a sink is assumed to flow underground and leave the system.

n_sources number of sources
nt_max max number of times for which discharge values are provided (out of all the sources).
dt timestep between successive values
source_ID long-integer, calendar-style ID of the grid cell that contains the source
nt number of timesteps for the corresponding source_ID
Discharge volumetric discharge that comes from the source, in units of m3/s

n_sources: 2
nt_max: 10
dt: 0.0
source_ID: 65
nt: 10
Discharge: 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05
source_ID: 62
nt: 5
Discharge: 0.05 0.05 0.05 0.05 0.05

Format of a Canals File

A "canals" file is a plain text file that starts with 1 key-value pair that provides the number of canals. This is followed by n_canals blocks (with 4 more key-value pairs each) which each provide information for one of the canals. Canals are currently assumed to be lossless, so that the flow rates at the two ends are identical, but lagged by the travel time. The five keys are defined as follows.

n_canals number of canals
canal_in_ID long-integer, calendar-style ID of the grid cell that contains the upstream end of the canal
canal_out_ID long-integer, calendar-style ID of the grid cell that contains the downstream end of the canal
Q_fraction fraction of discharge (Q, m3/s), between 0 (none) and 1 (100%) which is to be removed from canal_in_ID and routed to canal_out_ID
travel_time the time, in seconds, for the flow to travel from canal_in_ID to canal_out_ID

n_canals: 1
canal_in_ID: 216
canal_out_ID: 203
Q_fraction: 0.5
travel_time: 240.0 [seconds]


An example run with input parameters, BLD files, as well as a figure / movie of the output

Follow the next steps to include images / movies of simulations:

See also: Help:Images or Help:Movies


Scott Peckham


Key papers