User Manual for Distributed flow routing model: 1K-FRM
Version 1.38, November 10, 2016

Yasuto TACHIKAWA and Duong Duc Toan
Dept. of Civil and Earth Resources Eng., Kyoto University, Kyoto 615-8540, Japantachikawa@hywr.kuciv.kyoto-u.ac.jp

1. Introduction
1K-FRM is a distributed flow routing model based on kinematic wave theory. The input
topography data is generated using HydroSHED 30 second digital elevation model and flow
direction data. Forcing data to drive 1K-FRM is supposed to be hourly gridded data such as
20 km resolution MRI-GCM simulation runoff generation data. At first, a method to develop
topography data to drive 1K-FRM is described. Then, by using the developed data, anexample of rainfall-runoff simulation is demonstrated. Figure 1 is a supposed structure of thecoordinate system used for 1K-FRM flow routing simulation.

Figure 1: Geographic relation of flow routing simulation area and forcing data grid region.

2. Preparation of Topographic Information for 1K-FRM1) Hydroshed2topo
Hydroshed2topo is a program to generate input topography data for 1K-FRM, which isobtained from 1K-FRM homepage.
2) Input topography data
The topographic information for a flow routing model 1K-FRM is generated by using theHydroSHED (http://hydrosheds.cr.usgs.gov/) 30-second digital elevation and flow direction
data. The DEM and flow direction data with ESRI grid format data for entire Asia (55E,-10S
to 180E, 60N) from HydroSHED were downloaded and they were converted to short integer
2-bite binary data format to reduce the file size. These two files:
as_dem_30s_clipped_55—10-180-60.bin (246MB)
as_dir_30s_clipped_55—10-180-60.bin (246MB)
are obtained from 1K-FRM homepage. These two data are input files for hydroshed2topo.
3) Parameter data
All Necessary topographic input files to run the 1K-FRM are created by executing thehydroshed2topo.cc. The program creates additional ESRI ASCII files and those files can beimported to ArcGIS to prepare maps of the study area. First, you need to specify the study area byediting the parameter data filehydroshed2topo/clipArea.dat

The first row specifies the number of columns for the study region. The value must be an
integer value.
The second row specifies the number of rows for the study region. The value must be an
integer value.
The third row specifies Longitude (degree) of South West (lower left) corner of the study
area. The value is a real value.
The forth row specifies Latitude (degree) of South West (lower left) corner of the study
area. The value is a real value.

The grid size is supposed to 30 second. The longitude (second) of j-th cell center is set as
follows:
longitude = (int)(SWlon*3600) + 30*j + 15;

1206013835.5
Figure 2: Setting study area. An example of clipArea.dat.

4) Generation of topographic information for 1K-FRM
Compile hydroshed2topo.cc and run hydroshed2topo.exe.
5) Output files
All output files used for the 1K-FRM are created in the folder:hydroshed2topo/output
The files generated are below:
 modDem.bin: This is the corrected (pit removed) elevation information of the study area.
The data was written in real 4-byte binary data format.

Figure 3: A sample of modem.bin.

flowDir.bin: Flow direction information. The direction convention is shown in Figure 3.
The data format is integer 4-bite binary.

Figure 4: A sample of flowDir.bin.
81762354

Figure 5: Flow direction specified by the integer value.
flowAcc.bin: Flow accumulation information. The data format is integer 4-bite binary.

Figure 6: A sample of flowAcc.bin.

riverNum.bin: Each river basin is numbered starting from 1 and then each grid cell is
assign a value corresponding to the basin number which the cell is belongs to. The dataformat is integer 4-bite binary.

Figure 7: A sample of riverNum.bin.
riverNumList.txt: This is a text file which contains:
Column 1: river basin number of the study area,Column 2: the basin area (acmulated number of grids).
Column 3: column number starting from 1 (starting from West),
Column 4: row number starting from 1 (starting from South),
Column 5: longitude (second),
Column 6: latitude (second),
Column 7: longitude (degree), andColumn 8: latitude (degree)
If you want to calculate the discharge data only at some selected basins using 1K-FRMevent or 1K-FRM, you can delete all the other basins from this text file and keep only thenecessary basins.

All data begins from the South-West grid and lining to East, then, moving to the North in thenext line, which are typical GrADS data format. Sample GrADS control files are attached inhydroshed2topo to visualize the data.

1 5 10 59 497085 129555 138.079 35.9875
2 3 14 59 497205 129555 138.113 35.9875
3 4 16 59 497265 129555 138.129 35.9875
4 4 17 59 497295 129555 138.137 35.9875
5 4 18 59 497325 129555 138.146 35.9875…

Figure 8: An example of riverNumList.txt.

Additional files are also created, which are ESRI ASCII files to be imported to ArcGIS tovisualize the study region:

cutDem.asc: The DEM data for the study region. This is the original data clipped for thestudy region.
cutDir.asc: The DIR data for the study region. This is the original data clipped for thestudy region.
modDem.asc: The DEM data for the study region. This is the corrected (pit removed)
elevation information of the study area, which corresponds to moDem.bin.
flowDir.asc: The Flow Direction data for the study region, which corresponds toflowDir.bin.
flowAcc.asc: Flow accumulation value information, which corresponds to flowAcc.bin.
riverNum.asc: The river basin numbers of the study area, which corresponds toriverNum.bin.
distance.asc: The distance from the river mouth.

3. Preparation of Forcing Data
Input data is supposed to be hourly effective forcing data arranged for each month, which is, forexample, temporally downscaled surface and sub surface flow data from MRI-AGCM3.1S. Four typesof input data are available. Which data format is adopted is to uncomment unnecessary functions inthe source code of 1k-frm.cc and recompile the source program. All input data file should be placed in
1k-frm-\input folder.
As default, the grid center latitude is set as follows:

longitude = ROF_WLON + j*Delta_x; // set longitudelatitude = ROF_WLAT + i*Delta_y; // set longitude
where Delta x and y are the resolution of input data in longitudinal and latitudinal directions.
In case that the distance between two grid points in the Y direction (latitude direction) is not equal,
you have to create a file containing the center latitude of each row (Y direction) and also switch
functions to read grid data file on in the main source code. The file should be placed in the 1k-frm\topoData\ directory. Name of the file is “dataLatitude.dat” Please see the folder; \1kfrm\ topoData\, and also Figure 9.
35.32535.51335.70035.88836.07536.262

Figure 9: An example of dataLatitude.dat.

The geographic structure is shown in Figure 10. The forcing data represents the intensityof each grid center. The longitude of grid center is calculated in the program as the aboveequation. The latitude of grid center is read from the file “dataLatitude.dat”.The time intervalof the rainfall intensity should be hour. For flow routing simulation, the nearest grid ofrainfall intensity is selected.

Figure 10: Structure of coordinate of the rainfall grid system.
The forcing input data types are following three types. GrADS format binary two dimensional
monthly data is recommended.
1) GrADS format binary two dimensional monthly data

This is a default data format. The original 1k-frm is supposed to use the data format. The
hourly intensity values (mm/hr) for each month are stored beginning from the South-Westgrid and lining to East, then, moving to the North in the next line, which is the Grads data
format with 4 byte float binary floating data.

1k-frm-event/input/198001_rain.bin
File naming rule is:
YearMonth_ rain.bin
For example, 198001_rain.bin.
Sample data are included in the folder “input/”.
To use the data format, the function in “1k-frm.cc”
read2DValueGrads(ROF** fROF, int n_year, int n_month, int ROFnum_row, int ROFnum_col)must be used The function
ROF::readValue(int n_year, int n_month)which is used for ascii input file, should be commented out.

2) Ascii format two dimensional monthly data

A part of a sample data file is shown in Figure 11. The rainfall data file name is “rain.dat”
and should be placed at
1k-frm-event/input/198001_rain.dat
The first line of “198001rain.dat” is Year, Month, Day, Hour, Column Number, and Row
Number of spatially gridded rainfall data. From the next line, hourly intensity values (mm/hr)
are stored beginning from the North-West grid and lining to East, then, moving to the Southin the next line. Each data is delimited by white space characters (SPACE, TAB, or CR). You
can change the rainfall intensity data for your study purpose.
Be careful that the ascii data format begins from the North-West grid, which is opposite fromthe GrADS data format.

1979 12 1 1 5 60.1 0.2 0.3 0.4 0.5
0.6 0.7 0.8 0.9 1.0
1.1 1.2 1.3 1.4 1.5
1.6 1.7 1.8 1.9 2.0
2.1 2.2 2.3 2.4 2.5
2.6 2.7 2.8 2.9 3.0…

Figure 11: Part of rain.dat. The 1st Row is: Year, Month, Day, Hour, Column Number, Row
Number. From the 2nd to 7th Rows, effective rainfall intensities (5 columns and 6 rows) inmm/hr are stored.

File naming rule is:
YearMonth_ rain.dat
For example, 198001_rain.dat.
Sample data are included in the folder “input/monthly2DasciiDataSample”. To use the data format,the function in “1k-frm.cc”
read2DValueAsc(ROF** fROF, int n_year, int n_month, int ROFnum_row, int ROFnum_col)is used The function
ROF::readValue(int n_year, int n_month)which is used for binary input file, should be commented out.

3) Ascii format one dimensional monthly data
This uses text files containing hourly forcing data for each month at each data grid for entire
simulation period. The file naming convention is shown below and the part of a sample data file isshown in Figure 12.
File naming rule is
YearMonth_ColumnNumber_RowNumber_ rain.dat

For example, 197912_001_001_rain.dat, 198001_001_001_rain.dat
The origin number of ColumnNumber and RowNumber are specified in the parameter file param.dat
int pO_y = 1; Origin number of y-direction used to recognize input data.
int pO_x = 1; Origin number of x-direction used to recognize input data.
For 1-dimensional input data, data file name for each grid is supporsed to be (i=0, 1, ..., j=0, 1, ...)./input/%04d%02d_%03d_%03d_rain.dat", n_year, n_month, pO_x+i, pO_y+jSample data are included in the folder “input/monthly1DasciiDataSample”. To use the data format,
the function in roffunc.cc
ROF::readValue(int n_year, int n_month)is used.
1979

11

1

12.0

1979

11

122.0

1979

11

1

32.0

1979

11

1

4

2.0

1979

11

1

5

2.0

1979

11

1

62.0

1979

11

1

72.0

1979

11

1

82.0

1979

11

1

92.0

1979

11

1

102.0

1979

11

1

112.0

1979

11

1

12

2.0

1979

11

1

13

2.0

1979

11

1

14

2.0

1979

11

1

15

2.0

Figure 12: Part of a sample data file (197911_001_001_rain.dat)(Columns are; Year, Month, Day, Hour and Effective Rainfall in mm/hr, respectively)

4. Flow Routing Simulation Using 1K-FRM
The procedures for runoff simulation are as follows:

1) Topography data setting: Copy the topographic information files (above mentioned fivefiles)
from hydroshed2topo/output/ to 1k-frm/topoData/2) Rainfall data setting: Set the rain data and place rainfall data files at
1k-frm-event/input/198001_rain.bin.
3) Runoff simulation parameter setting: Edit the runoff simulation parameter file
1k-frm-event/param.datby using any text editor. Delimiter of each data is white space characters.
10

scale ratio of topography data. 1 means 3 second, 10 means 30 seconds.

120

Number of columns in the study area

60

Number of rows in the study area

138.0

Longitude (degree) of South West corner of the study area

35.5

Latitude (degree) of South West corner of the study area.

5

Number of columns of the input forcing data

6

Number of rows in the input forcing data

1

Origin column number of the input forcing data of x-direction.

1

Origin row number of the input forcing data of y-direction.

137.8125

West side longitude of input forcing data (degree)

3600

input forcing data time step (sec). If you change the value, source code
must be modified.

1979

simulation start year

1980

simulation end year

12

simulation start month5

simulation end month

600

simulation time step (sec)20

number of spatial divisions

0.65

0.5 < theta <= 1.0

0.7

Manning’s roughness coefficient for slope

0.03

Manning’s roughness coefficient for river250

grid accumulated number to differentiate slope and river

0.0

Initial runoff height for kinematic wave model (mm/hr)

Figure 13: An example of param-event.dat.

The parameter values to set in param.dat are as follows:(1) Parameters for study area.
int TopoScale = 10// Topography scale. 1 means 3 second.
int Col=120// number of column for study area.
int Row=60// number of row for study area.
double SWLON=138.0// Longitude (degree) of south west corner of the study area.
double SWLAT=35.5// Latitude (degree) of south west corner of the study area.
(2) Parameters for input data.
int ROFnum_col = 5// Number of column of input rainfall data
int ROFnum_row = 6// Number of row of input rainfall data
int pO_x = 1 // Origin column number of the input Rainfall data of x-direction used to// recognize input data. The default value is 1. The value is used// for recognizing for reading one-dimensional input data.
// For 1-dimensional input data, data file name for each grid is supporsed to// be (i=0, 1, ..., j=0, 1, ...)// ./input/%04d%02d_%03d_%03d_rain.dat", n_year, n_month,// pO_x+i, pO_y+j// The values are not used when reading two dimensional data.
int pO_y = 1 // Origin row number of the input Rainfall data of y-direction used to// recognize input data. The default value is 1. The value is used// for recognizing for reading one-dimensional input data.
double Delta_x = 0.1875// Input data grid size of x-direction (degree)
double Delta_y = 0.1875// Input data grid size of y-direction (degree)
double ROF_WLON = 137.8125// West side longitude of input data (degree)

double ROF_WLAT = 35.5// South side latitude of input data (degree)

int InputData_Time_Step = 3600// input data time step [sec]. If you change the value, source//code must be modified.

(3) Parameters for simulation term.
int startYear = 1979;// start year
int endYear = 1980;// end year
int startMonth = 12;// start monthint endMonth = 5;// end month(4) Parameters for finite difference condition.
int Time_Step = 600// Simulation time step (sec)int Nspace = 20// Number of spatial divisions
double Theta = 0.65// weight value 0.5 < theta <= 1.0

(5) Parameters for kinematic wave model.
double Man_slope = 0.7// Manning’s roughness coefficient for slope (m-s unit)
double Man_channel = 0.03 // Manning’s roughness coefficient for river (m-s unit)
int Threshold_basin = 250 // grid accumulated number to differentiate slope and river(6) Intinial runoff height for kinematic wave model.
double initialROF = 0.0// Initial runoff height (mm/hr)

4) Rainfall-runoff simulation
Open the folder “/project/1k-frm-event” and run“1k-frm.exe”
All runoff simulation results are created in
1k-frm/output
The files created are below:
 dailyDischarge.bin: The file contains the average daily flow (m3/sec).
 maxDischargeInDay.bin: The file contains the maximum hourly flow value for eachday (m3/sec).
The data are stored in GRADS binary data format and can be visualized using GRADS(http://www.iges.org /grads/). All data arranges from west to east at the South row, thenNorth row. GrADS control file:- flowAnalysisGradsDaily.ctl
is attached. A sample program is also attached in ./output:- pointdata.cc
which extracts time series ascii data from the above binary data.

5) Compile
If you want to change the source code, compile a modified code using:Linux/Unix environment: The executable is created by using the GNU g++ compiler asfollowing commandg++ -o 1k-frm-event.exe 1k-frm-event.cc cellfunc.cc roffunc.cc

or Intel C++ compiler
icl -o 1k-frm-event.exe 1k-frm-event.cc cellfunc.cc roffunc.cc
You can use OpenMP compile option if you use parallel cpmputer.
MS Windows environment: Microsoft Visual Studio 2008 or 2010 with C++ compiler isuseful. You can download a free version of Visual C++ Express Edition from Microsoft
web site.
The solution file 1k-frm.sln should be created according to Microsoft Visual Studio.

5. Example
The study area of the example which is distributed with the 1K-FRM is shown in Figure 14.

Figure 14: Simulation area and the clipped rainfall region for the example dataset

12060138.0
35.5--- bwlow is sample --int Col=120 //number of columns for study region. The value must be integer.
int Row=60 // number of rows for study region. The value must be integer.
double SWLON=138 // Longitude (degree) of South West (lower left) corner ofthe study area.
double SWLAT=35.5 // Latitude (degree) of South West (lower left) corner of thestudy area.
Figure 15: clipArea.dat (\hydroshed2topo\input\)

35.32535.51335.70035.88836.07536.262
Figure 16: dataLattude.dat (\1k-frm\topoData\ )10scale ratio of topography data. 1 means 3 second, 10 means 30 seconds.

120

Number of columns in the study area60

Number of rows in the study area

138.0

Longitude (degree) of south west side of the study area

35.5

Latitude (degree) of south west side of the study area.

5

Number of columns in the input forcing data

6

Number of rows in the input forcing data

1

Origin number of Y-direction of the input rainfall data region

1

Origin number of X-direction of the input rainfall data region

137.8

Origin Longitude (decimal degrees) of the input rainfall data region

3600

Time step of the input rainfall data

1979

Start year of the simulation period

1980

End year of the simulation period

12Start month of the simulation period

1End month of the simulation period

600

simulation time step [sec]20

number of spatial divisions

0.65

0.5 < theta <= 1.00.7

Manning’s roughness coefficient for slope

0.03

Manning’s roughness coefficient for river250

grid accumulated number to differentiate slope and river

0.0

Initial runoff height for kinematic wave model

Figure 17: param.dat (\1k-frm\topoData\ )Figure 18: Simulated daily mean discharge using GrADS.