Using the Routing Model

The routing model was developed by Dag Lohmann, please refer to the references given below for the methodology. The model transports grid cell surface runoff and baseflow produced by VIC-Nl within each grid cell to the outlet of that grid cell then into the river system. The within cell routing uses a Unit Hydrograph approach and the channel routing uses the linearized Saint-Venant equation. The river routing model assumes all runoff exits a cell in a single flow direction.

Topics on this page include:

Input File Setup
Editing the Source Code for Specific Basins
Calibration
Initializing Routing Model State
References

Click here to download the current routing model code

Note: This version of the code uses a default value of UH_DAY=96, defined in rout.f. This was set to ensure the routing code would work in large basins, where routed flows take longer to exit the system (the previous default was 48). All .uh_s files created with one value of UH_DAY will not work if a new value is used in the routing code, and so .uh_s files must be re-created if they were originally made with the previous versions of the code.

Input File Setup

The input file contains the parameter file names and parameter values require by the routing model. This file is passed as a command line argument to the routing model (ie rout <infile>). Note, some of the parameter files are optional, if these are not provided a constant value must be specified instead. The format of the input file and an example are given below:

MAIN TITLE
TEXT
<flow direction file>
TEXT
boolean (.TRUE. or .FALSE.)
<flow velocity file> or float
TEXT
boolean (.TRUE. or .FALSE.)
<diffusion file> or float
TEXT
boolean (.TRUE. or .FALSE.)
<xmask file> or float
TEXT
boolean (.TRUE. or .FALSE.)
<contributing fraction file> or float
TEXT
station location file
TEXT
location of vic input files and prefix
No. of decimal places used in VIC input filenames
TEXT
output directory
TEXT
start and stop year/month of the VIC simulation
first and last year/month to write output
TEXT
<unit hydrograph file>

# INPUT FILE FOR THE COLUMBIA BASIN.
# NAME OF FLOW DIRECTION FILE
direc.cmb
# NAME OF VELOCITY FILE
.false.
1.5
# NAME OF DIFF FILE
.false.
800
# NAME OF XMASK FILE
.false.
25000
# NAME OF FRACTION FILE
.true.
./rout_input/fraction.cmb
# NAME OF STATION FILE
stations.cmb
# PATH OF INPUT FILES AND PRECISION
./vic/vic_out/fluxes_
3
# PATH OF OUTPUT FILES
rout_out/
# MONTHS TO PROCESS
1969 1 1979 12
1969 1 1979 12
# NAME OF UNIT HYDROGRAPH FILE
uh_all

The following files may be required by the model, depending on the flags set in the above input file:

Flow Direction File §
Flow Velocity File
Flow Diffusion File
Xmask File
Contributing Fraction File
Station Location File
UH File §

§ compulsory

The start and stop year and month refer to the period over which the VIC simulation, which is the input to the routing model, was run.
The first and last year refer to the period for which the results of the routing are to be written to output.

Flow Direction File

The flow direction file tells the routing model how all of the grid cells are connected in the routing net. It is also the only input file with a header. The header tells the routing model the lower left latitude and longitude, the number of rows and columns, and the grid cell resolution. An example of a flow direction file is shown below:


ncols           22
nrows           20
xllcorner       -97.000
yllcorner       38.000
cellsize        0.50
NODATA_value    0
0 0 0 5 5 5 6 5 0 0 0 0 0 0 0 0 0 0 0 0 0 0 
0 0 0 4.0 4.0 5 0 0 0 0 0 0 0 0 0 0 0 0 0 0 
0 0 5 3 5 5 6 7 5 0 0 0 0 0 0 0 0 0 0 0 0 0 
0 0 5 4.0 5 5 5 5 6 7 5 5 5 7 5 0 0 0 0 0 0 
0 0 5 4.0 5 4 5 5 7 7 5 6 7 5 6 0 0 0 0 0 0 
4.0 5 7 4.0 3 5 5 7 5 5 7 4 5 6 0 0 0 0 0 0 
4.0 3 4.0.4.0.4 3 5 6 7 7 4 5 6 0 0 0 0 0 0 
0 4.0 4.0 3 1 2 4.0 4 5 7 5 5 0 0 0 0 0 0 0 
0 0 3 4 3 1 8 4 5 4.0 5 5 3 5 6 5 0 0 0 0 0 
0 0 0 3 4 5 5 4 5 4 3 5 6 7 7 5 5 7 0 0 0 0 
0 0 0 4 3 5 5 3 4.0.4 3 4 3 5 5 7 7 0 0 0 0 
0 0 0 4.0 5 4.0.4 3 4.0.4 5 3 5 7 7 0 0 0 0 
0 0 0 0 4.0 4.0 4.0 4 5 3 6 7 7 5 5 6 0 5 7 
0 0 0 0 0 4.0 3 4 3 5 3 6 7 6 5 7 7 7 7 7 7 
0 0 0 0 0 0 0 0 4.0 4 5 7 5 6 7 1 7 1 7 0 0 
0 0 0 0 0 0 0 0 3 4.0 5 5 6 7 7 7 6 0 0 0 0 
0 0 0 0 0 0 0 0 0 4.0 4 5 7 1 7 7 0 0 0 0 0 
0 0 0 0 0 0 0 0 0 3 2 4 5 7 7 1 0 0 0 0 0 0 
0 0 0 0 0 0 0 0 0 0 0 4.0 5 0 0 0 0 0 0 0 0 
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

Where:

xlcorner is the longitude of the lower left corner of the grid,
ylcorner is the latitude of the lower left corner,
rows is the number of rows in the file,
cols is the number of columns in the file,
size is the resolution of the grid, and
imiss is the value that represents missing or unused grid cells.

Flow from each grid cell is given by a by a number:

= north
= northeast
= east
= southeast
= south
= southwest
= west
= northwest

The awk script read_rout.awk will convert the routing direction file into an ASCII 2 column xy file, which can be used to generate a plot of the routing network using GMT. The plotting script upmiss.rout.script.clr shows how to use the awk script to generate the plot. It also uses the file mask.xy to mask out the basin area.

Flow Velocity File

This file contains information about the velocity (m/s) for the river routing component of the model. An example file, in which all velocities are assummed 1, is shown below:


 0 0 0 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 0 0 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 0 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0
 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0
 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0
 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0
 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0
 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0
 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0
 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0
 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 1 1
 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 0 0
 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 0 0 0 0
 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 0 0 0 0 0
 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 0
 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 0 0
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

The awk file velo.awk creates a velocity file from the flow direction file:

awk -f velo.awk direction_file > velocity_file

Use nawk on the Sun systems

Flow Diffusion File

This file contains the flow diffusion (m²/s) parameter used in river routing component of the model. An example file, in which the diffusion coefficient is assummed a constant value of 1000, is shown below:


    0    0    0 1000 1000 1000 1000 1000    0    0    0    0    0    0    0    0    0    0    0    0    0    0
    0    0    0 1000 1000 1000 1000 1000    0    0    0    0    0    0    0    0    0    0    0    0    0    0
    0    0 1000 1000 1000 1000 1000 1000 1000    0    0    0    0    0    0    0    0    0    0    0    0    0
    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0    0    0
    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0    0    0
 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0    0    0
 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0    0    0
    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0    0    0    0
    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0    0
    0    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0
    0    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0
    0    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0
    0    0    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0 1000 1000
    0    0    0    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000
    0    0    0    0    0    0    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0
    0    0    0    0    0    0    0    0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0
    0    0    0    0    0    0    0    0    0 1000 1000 1000 1000 1000 1000 1000 1000    0    0    0    0    0
    0    0    0    0    0    0    0    0    0 1000 1000 1000 1000 1000 1000 1000    0    0    0    0    0    0
    0    0    0    0    0    0    0    0    0    0    0 1000 1000 1000    0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0    0    0    0    0    0    0    0    0    0    0    0    0    0    0

The awk file diff.awk creates a diff file from the flow direction file:

awk -f diff.awk direction_file > diff_file

Use nawk on the Sun systems

Xmask File

The values in the xmask file are related to the size (in metres) of a cell. In the example below a constant value of 25,000 has been chosen (cell size 0.5 decimal degrees):


   0      0     0 25000 25000 25000 25000 25000     0     0     0     0     0     0     0     0     0     0     0     0     0     0
   0      0     0 25000 25000 25000 25000 25000     0     0     0     0     0     0     0     0     0     0     0     0     0     0
   0      0 25000 25000 25000 25000 25000 25000 25000     0     0     0     0     0     0     0     0     0     0     0     0     0
   0      0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0     0     0
   0      0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0     0     
25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0     0     0
25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0     0     0
   0  25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0     0     0     0
   0      0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0     0
   0      0     0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0
   0      0     0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0
   0      0     0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0
   0      0     0     0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0 25000 25000
   0      0     0     0     0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000
   0      0     0     0     0     0     0     0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0
   0      0     0     0     0     0     0     0 25000 25000 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0
   0      0     0     0     0     0     0     0     0 25000 25000 25000 25000 25000 25000 25000 25000     0     0     0     0     0
   0      0     0     0     0     0     0     0     0 25000 25000 25000 25000 25000 25000 25000     0     0     0     0     0     0
   0      0     0     0     0     0     0     0     0     0     0 25000 25000 25000     0     0     0     0     0     0     0     0
   0      0     0     0     0     0     0     0     0     0     0     0     0     0     0     0     0     0     0     0     0     0

The program create_xmask.c creates an xmask file from the flow direction file, and uses a calculation of the actual horizontal, vertical, and diagonal flow distances for each grid cell to produce an xmask file:

compile with: gcc -o create_xmask create_xmask.c -lm
run with: create_xmask "direction file" "xmask file"

Contributing Fraction File

The contributing fraction file is gridded information about the fraction of each grid cell that flows into the basin being routed. This allows the user to more accurately define the basin area, since edge cell can contribute more or less than 100% of their runoff and baseflow components to the basin. An example of a contributing area file is shown below:


0.00 0.00 0.00 0.11 0.38 0.63 0.65 0.33 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 
0.00 0.00 0.00 0.78 1.00 1.00 1.00 0.83 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 
0.00 0.00 0.64 1.00 1.00 1.00 1.00 0.87 0.35 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 
0.00 0.00 0.83 1.00 1.00 1.00 1.00 1.00 0.93 0.73 0.90 0.64 0.39 0.49 0.44 0.33 0.00 0.00 0.00 0.00 0.00 0.00 
0.00 0.00 0.90 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.91 0.00 0.00 0.00 0.00 0.00 0.00 
1.00 0.99 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.75 0.00 0.00 0.00 0.00 0.00 0.00 
0.52 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.29 0.00 0.00 0.00 0.00 0.00 0.00 
0.00 0.57 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.98 0.00 0.00 0.00 0.00 0.00 0.00 0.00 
0.00 0.00 0.57 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.73 0.21 0.40 0.00 0.00 0.00 0.00 0.00 
0.00 0.00 0.00 0.26 0.82 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.56 0.00 0.00 0.00 0.00 
0.00 0.00 0.00 0.41 0.99 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.82 0.00 0.00 0.00 0.00 
0.00 0.00 0.00 0.34 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.84 0.00 0.00 0.00 0.00 
0.00 0.00 0.00 0.00 0.57 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.96 0.15 0.00 0.28 0.28
0.00 0.00 0.00 0.00 0.00 0.48 0.97 0.99 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.88 0.83 0.65 0.43 
0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.53 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.91 0.99 0.65 0.00 0.00 
0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.13 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 0.42 0.00 0.00 0.00 0.00 
0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.93 1.00 1.00 1.00 1.00 1.00 1.00 0.42 0.00 0.00 0.00 0.00 0.00 
0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.52 0.86 1.00 1.00 0.87 0.56 0.30 0.00 0.00 0.00 0.00 0.00 0.00 
0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.31 0.57 0.05 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 
0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00

The program calc_area.c uses the subroutine new_get_dist.c to compute the area of the routed basin. The program uses the direction file to get the latitude and longitude of active cells (those with values not equal to the NODATA_value). The resulting cell area are multiplied by the drainage fraction and summed for the total basin area.

Note that this file has no header. Values in the file are 1 for 100% contributing area. Values greater than 1 indicate more than 100% contribution, while values less than 1 indicate less than 100% of the grid cell contributes.

Station Location File

The station location file tells the routing model from which grid cells to produce output flow data. Any number of stations may be defined within the basin, as well as a single basin outlet, where the routing network leaves the defined basin. Each line defining a station is followed by another that tells the routin model whether or not a uh_s file has been generated for the current station location. If set to NONE the routing model generates a new uh_s file in the current directory, otherwise it will read the defined uh_s file. An example station location file is shown below:

1 UPMIS               14  2  -9999
NONE
1 WISCR               14 11  -9998
WISCR.uh_s
1 ANOKA                8 15  -9998
store/ANOKA.uh_s

The file contains information in the following columns:

The first column indicates whether the station is active (1 = active, 0 = inactive),
the second column is the basin name which will be used for all of the output files (the first 5 characters are used to form the root of the output files),
the third column is the column, from the left, in the gridded direction file where the station is located,
the fourth column is the row, from the bottom, in the gridded direction file where the station is located, and
the fifth column is the basin area (required, but not used at present).

UH File

This file contains the grid cell impulse response function. An example file is shown below:

   0   0.0100
   1   0.2400
   2   0.3300
   3   0.1800
   4   0.1200
   5   0.0500
   6   0.0200
   7   0.0100
   8   0.0100
   9   0.0100
   10 0.0100
   11 0.0100

This file may be used unmodified if only flows on the monthly scale are required. (Note, the sum of the second column must equal 1.)

Editing the Source Code for Specific Basins

The routing code uses hard coded array dimensions. Before compilation the user should check in rout.f that NROW and NCOL are greater than or equal to the number of rows and columns specified in the direction file header, and that NYR is greater than the number of years over which flows are to be routed. Also, make sure PMAX exceeds the total number of grid cells to be routed. If the dimensions are insufficient a warning will be generated and the program will terminate.

Calibration

Lohmann et al. (1996) suggest velocity values in the range of 1 to 3 m/s and diffusivity of 200 to 4000 m²/s for the Weser basin in Germany.
Nijssen et al. ( 1997) quote velocity values of 0.5 to 2.0 for the Columbia basin and 1.0 for the Delaware.

If only monthly mean flows are required then diffusivity of 800 m²/s and velocity of 1.5 m/s are deemed acceptable, if daily values are required then the calibration methodology outlined in Lohmann et al. 1996, 1998a and 1998b should be followed.

References

Nijssen, B., Lettenmaier, D.P., Liang, X., Wetzel, W. and Wood, E.F., "Stream simulation for continental-scale river basins", Water Resources Research, 33(4), April 1997, pp711-724.

Lohmann , D., Nolte-Holube, R. and Raschke, "A large-scale horizontal routing model to be coupled to land surface parameterization schemes", Tellus, 48A,5 1996, pp708-721.

Lohmann, D., E. Raschke, B. Nijssen, and D. P. Lettenmaier, "Regional Scale Hydrology: I. Formulation of the VIC-2L Model Coupled to a Routing Model", Hydrological Sciences Journal, 43(1), February 1998a, pp 131-141.

Lohmann, D., E. Raschke, B. Nijssen, and D. P. Lettenmaier, "Regional Scale Hydrology: II. Application of the VIC-2L Model to the Weser River, Germany", Hydrological Sciences Journal, 43(1), February 1998b, pp 143-157.

VIC Administrator

Last modified: Fri Jul 20 10:43:37 PDT 2001