Itopkapi Manual Eng

AUTHOR
Dr. Cinzia Mazzetti
SOFTWARE VERSION
I.TOPKAPI v. 02.15.00
cinzia.mazzetti@progea.net
TOPKAPI
v. 06.14.08
LAST REVIEW
April 2014
ITOPKAPI USERS MANUAL
Acknowledgments
ITOPKAPI Users Manual

Copyright 2014 PROGEA srl
All rights reserved.
The information in this document is furnished for informational use only, is subject to change without notice, and
should not be construed as a commitment by the author. The author assumes no responsibility or liability for any
errors or inaccuracies that may appear in this document. The software described in this document is furnished
under license and may only be used or copied in accordance with the terms of such license.
Contacts:
Dr. Cinzia Mazzetti
Progea srl
Via Santo Stefano, 6
40125 Bologna, Italy
Tel
+39 051 6389099
Email cinzia.mazzetti@progea.net
Email segreteria@progea.net
Contents
Contents:
1.
ITOPKAPI VISUAL INTERFACE ........................................................................................................ 4

1.1.
Introduction ............................................................................................................................ 4
1.2.
Settings tab: General Settings................................................................................................ 6
1.3.
Time-State tab: Simulation Time Period Settings ............................................................... 9
1.4.
Stations tab: Station Coordinates and Data ....................................................................... 12
1.5.
Maps tab: Meteo Maps Settings .......................................................................................... 15
1.6.
Width tab: Rectangular Channel Widths ........................................................................... 18
1.7.
Initial Cond tab: Initial Conditions ..................................................................................... 20
1.8.
Soil tab: Soil Parameters ...................................................................................................... 21
1.9.
Land Use tab: Land Use Parameters .................................................................................. 23
1.10. Channel tab: Drainage Network Parameters ..................................................................... 26

1.11. Outputs tab: Model Output Points ..................................................................................... 29
1.12. Temperature tab: Average Monthly Temperatures .......................................................... 30
1.13. ET-Snow tab: Evapo-transpiration and Snowmelt parameters ....................................... 32
1.14. Reservoirs tab: Reservoirs Settings and Data .................................................................... 34
1.15. Interbasin tab: Inter-basin Contribution ........................................................................... 39
1.16. Inflow tab: Inflow Points Settings and Data ...................................................................... 41
1.17. Outflow tab: Outflow Points Settings and Data ................................................................. 42
2.
STEP BY STEP SET-UP OF TOPKAPI MODEL PARAMETERS INPUT FILE..................... 44

2.1.
Reno river demo ................................................................................................................... 44
2.2.
Reno river demo: General Settings ..................................................................................... 45
2.3.
Reno river demo: Simulation Time Period Settings .......................................................... 45
2.4.
Reno river demo: Stations Coordinates and Data ............................................................. 47

2.4.1. Rainfall data ............................................................................................................. 47
2.4.2. Temperature data ..................................................................................................... 47
2.4.3. Discharge data.......................................................................................................... 47
2.5.
Reno river demo: Soil Parameters ...................................................................................... 48
2.6.
Reno river demo: Model Output Points ............................................................................. 49
2.7.
Reno river demo: Evapo-Transpiration and Snowmelt Parameters ............................... 50
2.8.
Reno river demo: Reservoirs ............................................................................................... 51
2.9.
Reno river demo: Interbasins Contribution ....................................................................... 53
2.10. Reno river demo: Inflow ...................................................................................................... 56

2.11. Reno river demo: Outflow (withdrawal) ............................................................................ 58
2.12. Running TOPKAPI model ................................................................................................... 59
II
List of Figures
List of Figures:
Figure 1 - Picture of the tab Settings of TOPKAPI Visual Interface .......................................................................... 6
Figure 2 - Picture of the tab Time-State of TOPKAPI Visual Interface ...................................................................... 9
Figure 3 - Picture of the tab Stations of TOPKAPI Visual Interface ........................................................................ 12
Figure 4 - Picture of the tab Maps of TOPKAPI Visual Interface ............................................................................ 15
Figure 5 - Picture of the Rainfall Maps area in tab Maps of TOPKAPI Visual Interface ......................................... 16
Figure 6 - Picture of the Rainfall Maps area in tab Maps of TOPKAPI Visual Interface ......................................... 16
Figure 7 - Picture of the Temperature Maps area in tab Maps of TOPKAPI Visual Interface ................................. 17
Figure 8 - Picture of the Temperature Maps area in tab Maps of TOPKAPI Visual Interface ................................. 17
Figure 9 - Picture of the tab Width of TOPKAPI Visual Interface ............................................................................ 18
Figure 10 - Picture of the tab Initial Cond of TOPKAPI Visual Interface ................................................................ 20
Figure 11 - Picture of the tab Soil of TOPKAPI Visual Interface ............................................................................. 21
Figure 12 - Picture of the tab Land Use of TOPKAPI Visual Interface ................................................................... 23
Figure 13 - Picture of the tab Channel of TOPKAPI Visual Interface ...................................................................... 26
Figure 14 - Picture of the tab Outputs of TOPKAPI Visual Interface ...................................................................... 29
Figure 15 - Picture of the tab Temperature of TOPKAPI Visual Interface............................................................... 30
Figure 16 - Picture of the tab ET-Snow of TOPKAPI Visual Interface .................................................................... 32
Figure 17 - Picture of the tab Reservoir component of TOPKAPI Visual Interface ................................................. 34
Figure 18 - Picture of the tab Interbasins of TOPKAPI Visual Interface ................................................................. 39
Figure 19 Scheme of TOPKAPI interbasins couplet with a Hydraulic model ....................................................... 40
Figure 20 - Picture of the tab Inflow of TOPKAPI Visual Interface ......................................................................... 41
Figure 21 - Picture of the tab Outflow of TOPKAPI Visual Interface ...................................................................... 42
Figure 22 Select Reno.tpk file ................................................................................................................................ 44
Figure 23 The General Settings tab ........................................................................................................................ 45
Figure 24 The Simulation time period and settings tab .......................................................................................... 46
Figure 25 the station coordinates and data tab ....................................................................................................... 48
Figure 26 Change default values in Sub-basin Outlet column of the table. ........................................................... 49
Figure 27 - Evapo-transpiration and snowmelt parameters ....................................................................................... 50
Figure 28 Display of TPK_CELL_POLYGON, STRAHLER (in pink) and TPK_LAKES (in green) layers. .......... 51
Figure 29 Add points to a shapefile ....................................................................................................................... 53
Figure 30 Find out raster numbers for upstream (a) and downstream (b) cell of inter-basin contribution area. .... 54
Figure 31 Insert an inter-basin contribution area to the table ................................................................................. 54
Figure 32 - Insert the inter-basin contribution in Model Output Points table ........................................................... 55
Figure 33 Running TOPKAPI model dialog window ............................................................................................ 59
Figure 34 Setting information for TOPKAPI model simulation ............................................................................ 59
Figure 35 End of simulation dialog box ................................................................................................................. 60
III
1.
ITOPKAPI Visual Interface
1.1.
Introduction
1. ITOPKAPI Visual Interface
TOPKAPI is a distributed and physically based hydrological model. It simulates the main component of the
hydrological cycle such as surface flow, soil drainage, evapo-transpiration, snow melting, ect.. Although the model
has been developed with a special attention to the number of parameters needed to run a simulation, TOPKAPI
requires much more parameters than a conceptual model.
ITOPKAPI is a very simple and intuitive interface that is used to prepare parameters input file for TOPKAPI
model. Although it is possible to manage input file manually, ITOPKAPI makes the work easier and it includes a
large number of default parameters that can be used by Users with less modelling experience.
The Visual Interface of TOPKAPI model includes three different programs:

1) ITOPKAPI for managing models parameters and running simulations
2) TPKVIEW for displaying models results
3) TPKMAPS for displaying models state maps
4)
The present document describes ITOPKAPI Visual Interface and it explains how to use it.
ITOPKAPI Visual Interface can be launched in many different ways:

o
You can run it from PreTPK visual interface using the button ITOPKAPI
You can run it from Progeas drop down menu inside your Map Window project (select Topkapi
Parameters Manager)
You can run it from your desktop icon
When you launch ITOPKAPI, a window appears asking you to select a *.tpk file, namely one of TOPKAPIs
parameters input file.
Select an existing tpk file and it will open inside the Visual Interface.
The following paragraphs describe ITOPKAPI Visual Interface in details.
The present document is not intended as a description of TOPKAPI

models features!
It is recommended that the User reads TOPKAPI Models Reference before using
I.TOPKAPI Visual Interface.
1.2.
Settings tab: General Settings
The tab Settings contains information on the general settings of the model, such as the dimension of the working
area, the dimension of the models pixels, the number of outlets, etc.. Some of the fields are fixed and they can be
modified during the pre-processing stage only.
Figure 1 - Picture of the tab Settings of TOPKAPI Visual Interface

Topkapi Grid Info
This area contains the general settings of the model. Input data are read from the *.tpk file where they are stored by
PreTPK. Information in this area cannot be changed manually: use MapWindowGIS and PreTPK Visual Interface
to modify cells dimension and location.
Total Cells Number:
Total number of pixels of the basin
Cell Size:
Dimension of the model pixels in m
Number of Columns:
Number of columns in the model window
Number of Rows:
Number of rows in the model window
X Lower Left:
X coordinate of the South-West corner of the model window
Y Lower Left:
Y coordinate of the South-West corner of the model window
Global Position
This area is used to set global positioning of the catchment. It is not necessary to be very accurate: general
coordinates of the center of the catchment will be fine. These information is used in some of the components of the
model. For instance, if the TOPKAPI model is run using the evapo-transpiration component and/or the snowmelt
component, it uses information on the daylight duration. This information is stored inside the model using a table
that associates specific daylight duration to Latitude of the globe. For this reason the model requires the Latitude of
the basin.
Latitude:
Latitude of the basin [DD]
Longitude:
Longitude of the basin [DD]
Drainage Network Info

This area of the Visual Interface contains the general characteristics of the drainage network. Some of information
can be changed, other are fixed and need PreTPK visual interface to be modified.
Outlet Raster Number:
Raster number of the basin outlet. If the basin has more than one outlet then
this box shows the total number of pixels in the basin. This box cannot be
changed using ITOPKAPI, it can be modified using PreTPK and
MapWindowGIS.
Outlet Row:
Row number of the basin outlet. If the basin has more than one outlet then this
box shows the total number of rows in model window. This box cannot be
changed using ITOPKAPI, it can be modified using PreTPK and
MapWindowGIS.
Outlet Column:
Column number of the basin outlet. If the basin has more than one outlet then
this box shows the total number of columns in model window. This box cannot
be changed using ITOPKAPI, it can be modified using PreTPK and
MapWindowGIS.
Number of Outlets:
Total number of outlets of the basin. This box cannot be changed using
ITOPKAPI, it can be modified using PreTPK and MapWindowGIS.
Threshold Area [Km2]:
Threshold area drained by a pixel to be a channel. The default value is the pixel
area which corresponds to having a channel on each pixel of the basin. This box
can be changed using ITOPKAPI, but it is strongly suggested to modify this
value using PreTPK and MapWindowGIS, because changes to the drainage
network may occur.
Flow Partition Coeff.
Flow partition coefficient. It is the percentage of surface flow and soil flow
discharge that goes directly to the channel if it is present on the pixel. The
default value is 0.5. This value is not used with automatic flow partition
coefficients (see TOPKAPI model Reference Manual and PreTPK manual for
details).
Input Data Type

This part of the Visual Interface is used to set the type of input data to be used in simulations.
Rainfall Data:
It is used to select the type of rainfall input data. There are two possible
options:
o Station based, for using rain-gauges input data;
o Fully distributed, for using rainfall maps.
Depending of the selected type of data the sections referring to rainfall data in
the tabs Stations and Maps will be activated or not.
Temperature Data:
If the evapo-transpiration component is active, then the box for entering

temperature data type is active. There are two options:
o Station based, for using thermometers input data;
o Fully distributed, for using temperature maps.
Depending of the selected type of data the sections referring to temperature
data in the tabs Stations and Maps will be activated or not.
Active Model Components

This part of the Visual Interface is used to activate the different component of the model.
Evapo-transpiration:
The Evapo-transpiration box is used to activate the evapo-transpiration

component of the model. In order to correctly estimate evapo-transpiration, it is
necessary to fill in Mean Monthly Temperature data in Temperature Tab.
Snow accumulation and melting: The Snow component box is used to activate the snow component of
the model. It is not possible to run the snow model without temperature data,
either as point data or maps.
Percolation:
The Percolation component box is used to activate percolation from the soil of
the model to a deeper soil layer outside of the model. If the percolation
component is active it is necessary to fill in data regarding percolation in the
Soil tab.
Reservoir:
The Reservoir component box is used to activate the reservoir model inside
TOPKAPI. If the Reservoir component is active, it is necessary to fill in data
regarding reservoirs in the Reservoir tab.
Working directory
The box contains the path of the directory of the *.tpk file that the Visual Interface is showing. It reminds to the
User of the location of TOPKAPIs input file.
1.3.
Time-State tab: Simulation Time Period Settings
The tab Time-State contains information on time settings and state file storing of the model simulation, namely on
the simulation period and how to use and/or save state file.
Figure 2 - Picture of the tab Time-State of TOPKAPI Visual Interface

Dates and Time Steps
Computation Time Step Length [min]:
It stores the time steps used for running the model in minutes.
The time step of the model must coincide with the time step of input data
(rainfall and temperature).
Simulation Start Date:
It stores the starting date of the simulation.
Simulation End Date:
It stores the ending date of the simulation
Forecasting End Date:
It stores the ending date of the forecasting period. It is not used by the model in
Off-line simulations.
Computation Time Step for Channel Component [min]: It stores the time step used to solve the non-linear
reservoir equation for the channel component in minutes. This value must be a
sub multiple of the time step used for running the model. (The default value is
15).
Sub-basin
In the process sub-basin menu it is possible to select whether to run TOPKAPI on the entire catchment (All) or to
select one of the sub-basin and run the model on the sub-basin only. In this case only the pixels that belong to the
sub-basin will be considered by TOPKAPI model.
In the TOPKAPI model the order in which each model pixel is computed is set by the order in which pixels are
stored in the file *.rot. From the topmost part of the basin (namely the topmost part of file *.rot) each pixel will be
processed. This organization of the model pixels makes it possible to process only a part of the basin, for example
a sub-basin, skipping the remaining pixels. In this way the time requested for a simulation on a sub-basin is
reduced and even large basins can be calibrated in a reduced amount of time dividing the calibration into subbasins.
Select Initial State File
The TOPKAPI model can run a simulation starting from average conditions for soil moisture, channels, snow, etc.
(sometimes called cold start) or it can run a simulation starting from an existing hydrologic condition, namely a
State file (sometimes called hot start).
Every time a simulation is launched, the model automatically searches for a state file in the State folder (the state
file corresponding to the time step immediately before the starting time step of the simulation is searched by the
model) and if it does not find it, then it starts the simulation using a medium state.
The State file corresponding to the hot start of the model can already be available inside the State folder or it can
be created by the User using the setting boxes contained in the Initial State area.
If the Use Custom Initial State File box is selected, then the User can select its own starting state for the
simulation: the User must select a starting state file using the Browse button. This file will be automatically
copied into the State folder and it will be automatically renamed to IniSate.stt. The model will use it and then
cancel it.
State file can be automatically stored during a simulation run using settings in the State File Storing area.
State File Storing
Options in this area are used to define how and where to store state file. There are two different types of state file:
1) State file used as hot start for TOPKAPI model. They are in binary format and file name is set
according to the date (YYYYMMddhhmm.stt). These type of state file are always store if the State File
Storing Start Date is set to any time after the beginning of the simulation run.
This type of state file can be used as a custom state file for TOPKAPI model.
2) State file used by TPKMaps to display the hydrological state of the catchment in time (2D maps). They
are ESRI ASCII GRID file, file name is set according to the date and the extension is set according to the
hydrological quantity stored in the file. These type of state file are stored only if the corresponding box is
checked in the Print area and if the State File Storing Start Date is set to any time after the beginning of
the simulation run.
This type of state file cannot be used as a custom state file for TOPKAPI model.
State File Storing Start Date:
It is the starting date for storing state file during a simulation run.
State File Storing End Date:
It is the ending date for storing state file during a simulation run.
State File Storing Frequency:
It is the frequency used for storing state files in minutes. The minimum
value is the dimension of the model time step.
State File Storing Mode:
It defines how to store state file. Two options are available:

o
Use unique dir: it stores state file in one directory
Use Sub_dir: it stores state file in different directories

according to the year and month. This option is particularly
useful when storing large amount of file.
10
Print
Options in this area are used to define which state file (2D maps for TPKMaps visual interface) are going to be
stored during model runs. File are stored in ESRI ASCII GRID format, file name is set according to the date and
the extension is set according to the hydrological quantity stored in the file.
ESRI ASCII Meteo maps: This check box is used to select whether to print meteo maps during simulation.
Meteo maps are rainfall and temperature maps. Since the TOPKAPI model is a
distributed model, one value of rainfall and one value of temperature (where
available) are set for each pixel of the model.
Soil Moisture maps:
This check box is used to activate printing of soil moisture maps
Snow Water Equivalent maps: This check box is used to activate printing of snow water equivalent maps
Overland Flow maps:
This check box is used to activate printing of overland flow maps
Channel Flow maps:
This check box is used to activate printing of channel flow maps
Potential Evapo-Transpiration (ETP) maps: This check box is used to activate printing of ETP maps
Actual Evapo-Transpiration (ETA) maps:
This check box is used to activate printing of ETA maps
NOTE: Printing 2D state maps for a long time period can occupy a large amount of
space on your hard disk!
11
1.4.
Stations tab: Station Coordinates and Data
The tab Stations contains information on point input data of the model, such as rainfall, temperature, evapotranspiration (not fully functional at the moment) and discharge. The tab is divided into three parts: Rainfall data,
Temperature Data and Discharge Data.
The Rainfall data and Temperature Data areas are active only if the option Station based has been selected in
General Tab.
Figure 3 - Picture of the tab Stations of TOPKAPI Visual Interface

Rainfall Data
This area of the tab is used to set paths, names and file formats of the rainfall data files.
Coordinates File:
This box contains the path and the name of the file containing the coordinates
of the rain-gauges.
Rainfall Data File:
This box contains the path and the name of the file containing rainfall data from
rain-gauges.
Data Unit:
This drop down menu is used to select measurement units for rain-gauges data
contained in the data file.
Data File Format:
These check boxes are used to select file format of rainfall data file. There are
two possible options:
o csv file format,
o table file format.
12
Spatialization Mode:
These check boxes are used to select the type of interpolation technique that is
going to be used to interpolate rain-gauges data. There are two possible options:
o Thiessen polygons
o Inverse Squared Distance (ISD)
Inverse Square Distance (ISD) Parameters The boxes in this area are used to select parameters for ISD
interpolation method.
Maximum Stations:
This box is used to set the maximum number of rain-gauges that is going to be
used for interpolating rainfall data on a TOPKAPI models cell. The first
Maximum Stations closer to the cell are going to be used for interpolation.
Default value is 5.
Search Distance (m):
This box is used to set the maximum distance from TOPKAPI models cells for
a rain-gauge to be used for data interpolation. If one or more of the first
Maximum Stations is more distant from TOPKAPI models cell than Search
Distance, the rain-gauge is not used for data interpolation on that cell.
Default value is 15000 m.
Max Interpolation Distance (m): This box is used to set the general maximum distance from TOPKAPI
models cells for a rain-gauge to be used for data interpolation. If a rain-gauge
is more distant than Max Interpolation Distance, it will not be used for data
interpolation in any case. If all rain-gauges are more distant than Max
Interpolation Distance from TOPKAPI models cells, no data will be available
for interpolation.
Temperature Data
If the evapo-transpiration component is active and Stations Based is chosen in the temperature data menu, the
Temperature Data area appears in the Stations tab. This area of the tab is used to set paths, names and file formats
of thermometers data files.
Coordinates File:
This box contains the path and the name of the file containing the coordinates
of the thermometers.
Rainfall Data File:
This box contains the path and the name of the file containing temperature data
from thermometers.
Data Unit:
This drop down menu is used to select measurement units for temperature data
Data File Format:
These check boxes are used to select file format of temperature data file. There
are two possible options:
o csv file format,
Spatialization Mode:
These check boxes are used to select the type of interpolation technique that is
going to be used to interpolate temperature data. There are two possible
options:
o Thiessen polygons
o Inverse Squared Distance (ISD)
Inverse Square Distance (ISD) Parameters The boxes in this area are used to select parameters for ISD
interpolation method.
Maximum Stations:
This box is used to set the maximum number of thermometers that is going to
be used for interpolating temperature data on a TOPKAPI models cell. The
first Maximum Stations closer to the cell are going to be used for
interpolation.
Default value is 3.
Search Distance (m):
This box is used to set the maximum distance from TOPKAPI models cells for
a thermometer to be used for data interpolation. If one or more of the first
13
Maximum Stations is more distant from TOPKAPI models cell than Search
Distance, the thermometer is not used for data interpolation on that cell.
Max Interpolation Distance (m): This box is used to set the general maximum distance from TOPKAPI
models cells for a thermometer to be used for data interpolation. If a
thermometer is more distant than Max Interpolation Distance, it will not be
used for data interpolation in any case. If all thermometers are more distant
than Max Interpolation Distance from TOPKAPI models cells, no data will
be available for interpolation.
Discharge Data
This area of the tab is used to set paths, names and formats of the observed discharges file. This file is used to
compare simulated discharges computed by the model to the real ones. If discharge data are not available the
Discharge box should be left blank.
Discharge Data File:
This box contains the path and the name of the file containing discharge data.
Data Unit:
This drop down menu is used to select measurement units for discharge data
Data File Format:
These check boxes are used to select file format of discharge data file. There
are two possible options:
o csv file format,
14
1.5.
Maps tab: Meteo Maps Settings
The tab Maps contains information on raster input data of the model, such as rainfall, temperature and evapotranspiration (not fully functional). The tab is divided into three parts: Rainfall maps, Temperature maps and
Evaporation Maps (that is not working at the moment).
Areas in Maps Tab become active only if the option Fully Distributed has been selected in General Tab.
Figure 4 - Picture of the tab Maps of TOPKAPI Visual Interface

Rainfall Maps
If Fully distributed has been selected from the rainfall data menu in General Tab, the Rainfall map area is active.
This area of the tab is used to set paths, names and file formats of the rainfall raster input files.
Path:
This box contains the path of the maps containing rainfall data.
Map Format:
This drop down menu is used to select the format of input maps. There are four
options:
o Binary:
Maps are provided in binary format and they are
stored into one directory.
o ESRI ASCII
Maps are provided in ESRI ASCII GRID format
and they are stored into one directory.
o Binary (Sub-Dir) Maps are provided in binary format and they are
stored into different directories according to the
year and month.
o ESRI ASCII (Sub-Dir)
Maps are provided in ESRI ASCII GRID
format and they are stored into different directories
according to the year and month.
15
Map File Extension:
This box is used to set the file extension of input data.
Data Unit:
This drop down menu is used to select measurement units for rainfall maps.
If Binary has been selected from the Map Format drop down menu, the area for describing binary maps appears in
the rainfall maps area.
Cell size (m):
This box contains the dimension of the raster pixel in m. It can be different
from the model pixels.
N Columns:
This box contains the number of columns in the binary map.
N Rows:
This box contains the number of rows in the binary map.
X Lower Left:
X coordinate of the South-West corner of the binary map.
Y Lower Left:
Y coordinate of the South-West corner of the binary map.
The coordinate of the South-West corner of the binary map can be different from the coordinates of the model
window.
Figure 5 - Picture of the Rainfall Maps area in tab Maps of TOPKAPI Visual Interface
Figure 6 - Picture of the Rainfall Maps area in tab Maps of TOPKAPI Visual Interface
Temperature Maps
If Fully distributed has been selected from the temperature data menu in General Tab, the Temperature map area is
active. This area of the tab is used to set paths and formats of the temperature raster input files.
Path:
This box contains the path of the maps containing temperature data.
Map Format:
This drop down menu is used to select the format of input maps. There are four
options:
o Binary:
Maps are provided in binary format and they are
stored into one directory.
o ESRI ASCII
Maps are provided in ESRI ASCII GRID format
and they are stored into one directory.
o Binary (Sub-Dir) Maps are provided in binary format and they are
stored into different directories according to the
year and month.
o ESRI ASCII (Sub-Dir)
Maps are provided in ESRI ASCII GRID
format and they are stored into different directories
according to the year and month.
16
Map File Extension:
This box is used to set the file extension of input data.
Data Unit:
This drop down menu is used to select measurement units for temperature
maps.
If Binary has been selected from the Map Format drop down menu, the area for describing binary maps appears in
the rainfall maps area.
Cell size (m):
This box contains the dimension of the raster pixel in m. It can be different
from the model pixels.
N Columns:
This box contains the number of columns in the binary map.
N Rows:
This box contains the number of rows in the binary map.
X Lower Left:
X coordinate of the South-West corner of the binary map.
Y Lower Left:
Y coordinate of the South-West corner of the binary map.
The coordinate of the South-West corner of the binary map can be different from the coordinates of the model
window.
Figure 7 - Picture of the Temperature Maps area in tab Maps of TOPKAPI Visual Interface
Figure 8 - Picture of the Temperature Maps area in tab Maps of TOPKAPI Visual Interface
17
1.6.
Width tab: Rectangular Channel Widths
The Width tab contains the values of the parameters describing the Width of Rectangular Channels and the
Threshold Slope for the Muskingum-Cunge component.
Figure 9 - Picture of the tab Width of TOPKAPI Visual Interface

General (Based on drained area)
This area contains the general settings of the model regarding the width of rectangular channels. Input data are read
from the *.tpk file where they are stored during pre-processing phase.
Max River Width [m]:
It stores the maximum width for rectangular channels in m.
Min River Width [m]:
It stores the minimum width for rectangular channels in m.
These values cannot be changed using ITOPKAPI visual interface. The User can modify them using PreTPK
visual interface and MapWindowGIS.
Custom
This area contains the settings of the model regarding the width of rectangular channels. By default the table stores
one value corresponding to the width of the rectangular channel at the outlet section of the basin. Other values can
be entered manually. Note that one value is always necessary, even using triangular channel sections.
If more than one outlet is used into the model, it is necessary to add all outlets and to specify channel widths.
The parameters of the table refer to the elements of the non-linear reservoir equation for rectangular channels,
namely the width of rectangular channels (B):
18
s A
Vc
rc Qcu 0 x
t
n Cx
B
X
Vc
In the present version of TOPKAPI model it is possible to fix the width of rectangular channels in different
sections of the river network, according to real dimensions of the river. This is done using the Width Custom
Table. In order to fix the dimension of a section the corresponding raster number must be entered in the table,
together with its width value. As a consequence the model will compute the dimension of the rectangular channel
for the entire river network. The width of the channel between two fixed sections will be computed on the basis of
the drained area, using the following equation:
Wi Wmax
W
Wmin
max
A A
th
tot
Adri Atot
where: Wmax = maximum fixed width of the channel;

Wmin = minimum fixed width of the channel
Ath
= drainage area of the minimum width river section;
Atot
= drainage area of the maximum width river section;
Adri
= drainage area of the computed section of the river network.
The Custom table contains the following values:

Raster_Code:
It stores the raster code number of cell.
Channel Width [m]:
It contains the width dimension of the river section in m.
Description:
It stores a description of the river section. This part of the table does not contain
any parameter of the model but it must be always filled with some characters.
Muskingum-Cunge Threshold
Slope Threshold for application of parabolic routing (Muskingum-Cunge model):
It
stores
the
values of the slope threshold for solving the channel component using the
Muskingum-Cunge routing method.
Default value is 0.001, that correspond to the value above which the
Muskingum-Cunge routing method becomes instable.
19
1.7.
Initial Cond tab: Initial Conditions
The tab Initial Cond contains information on the state of the basin at the beginning of a simulation.
The TOPKAPI model can run a simulation starting from average conditions for soil moisture, channels, snow, etc.
(sometimes called cold start) or it can run a simulation starting from an existing hydrologic condition, namely a
State file (sometimes called hot start).
Every time a simulation is launched, the model automatically searches for a state file in the State folder (the state
file corresponding to the time step immediately before the starting time step of the simulation is searched by the
model) and if it does not find it, then it starts the simulation using a medium state, namely the state described in the
tab Initial Conditions.
For each month of the year the table describes the initial conditions regarding Soil moisture and Channel water.
Soil moisture is described as the saturation percentage divided by 100, each pixel with the same value. Channel
water is described as a water level: the table stores the ration between water level and channel width. In this way
each channel has a starting water level that is proportional to the width of the channel.
Figure 10 - Picture of the tab Initial Cond of TOPKAPI Visual Interface

Initial conditions table
Month:
it stores the month of the year.
Mean Soil Moisture:
it stores the mean soil moisture value for the corresponding month of the year.
River Level/Width:
It stores the mean water level in the channels for the corresponding month of
the year.
20
1.8.
Soil tab: Soil Parameters
The Soil Parameters Table contains the hydraulic properties of the soils of the basin. PreTPK will automatically
store the codes of the soils of the catchment in the table.
Figure 11 - Picture of the tab Soil of TOPKAPI Visual Interface

Data can be imported and exported to and from the table right clicking with the mouse on the table. The
import/export file is a csv file that stores on the first line the names of the columns of the table:
o
Code
Horizontal Permeability at Saturation
Saturated Water Content
Residual Water Content
Soil Depth
Horizontal Non-Linear Reservoir Exponent
Vertical Permeability at Saturation
Vertical Non-Linear Reservoir Exponent
Description.
21
The parameters of the table refer to the elements of the non-linear reservoir describing the soil component (see
TOPKAPI model Reference Manual):
t
C
1
X
p X
Qou Qsu
Cs S
Lks tan( )
s r
L s
and the equation describing the percolation component (see TOPKAPI model Reference Manual):
Pr k sv
sat
Soil Parameters Table

Code:
It stores soil codes, namely the codes contained in the soil type map (*.soi).
Horizontal Permeability at Saturation: It stores the values of the horizontal permeability at saturation (k s)
in m/s. This parameter is used in the soil component and regulates the amount
of water moving horizontally in the soil superficial layer.
Saturated Water Content: It stores the saturated water content in the soil (s). This parameter is used to
regulate the amount of water that can be stored in the soil superficial layer.
Residual Water Content: It stores the residual water content in the soil (r). This parameter is used to
regulate the amount of water that can be stored in the soil superficial layer.
Soil Depth:
It stores the depth of the superficial soil layer in m (L). This parameter is used
to regulate the amount of water that can be stored in the soil superficial layer
and it influences also the amount of water moving into the soil horizontally
(drainage) and vertically (percolation).
Horizontal Non-Linear Reservoir Exponent: It stores the value of exponent s in the equation of the nonlinear reservoir describing the soil component. The value depends on the type
of soil but usually it is set to a constant value equal to 2.5.
Vertical Permeability at Saturation: It stores the values of the vertical permeability at saturation (ksv) in
m/s. This parameter is used in the percolation component and regulates the
amount of water moving vertically in the soil superficial layer.
Vertical Non-Linear Reservoir Exponent: It stores the value of exponent p in the equation describing the
percolation component. The value depends on the type of soil and it is used in
the percolation to regulate the amount of water moving vertically in the soil
superficial layer.
Description:
It stores a description of the soil codes. This part of the table does not contain
any parameter of the model but it must be always filled with some characters.
22
1.9.
Land Use tab: Land Use Parameters
The Land Use Parameters Table contains the values of the parameters describing the surface of the basin:
Mannings coefficient for the soil surface roughness and land use crop factors. PreTPK will fill in the table with
land use codes included in the catchment.
Figure 12 - Picture of the tab Land Use of TOPKAPI Visual Interface

Data can be imported and exported to and from the table right clicking with the mouse on the table. The
import/export file is a csv file that stores on the first line the names of the columns of the table:
o
Code
Manning Coefficient [s/m^(1/3)]
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
23
Dec.
The parameters of the table refer to the equation of the non-linear reservoir describing the overland flow
component (see TOPKAPI model Reference Manual):
ho
C
ro o ho O
t
X
Co
tan
n0
and to the equation describing the evapo-transpiration component (see TOPKAPI model Reference Manual):
ET0 K c ( NWtaTt )
t
30 24 3600
Land Use Parameters Table

Code:
It stores land use codes, namely the codes contained in the land use map (*.lus).
Manning Coefficient [s/m^(1/3)]: It stores the values of the Mannings Coefficients for soil surface
roughness in s/m1/3 (no). This parameter is used in the overland flow component
and regulates the celerity and the shape of overland discharge waves.
Jan:
It stores the values of Crop factors for the month of January (Kc). This
parameter is used in the Evapo-transpiration component to compute actual
evapo-transpiration given the crop reference potential evapo-transpiration
value.
Feb:
It stores the values of Crop factors for the month of February (K c). This
value.
Mar:
It stores the values of Crop factors for the month of March (K c). This parameter
is used in the Evapo-transpiration component to compute actual evapotranspiration given the crop reference potential evapo-transpiration value.
Apr:
It stores the values of Crop factors for the month of April (K c). This parameter
is used in the Evapo-transpiration component to compute actual evapotranspiration given the crop reference potential evapo-transpiration value.
May:
It stores the values of Crop factors for the month of May (K c). This parameter is
used in the Evapo-transpiration component to compute actual evapotranspiration given the crop reference potential evapo-transpiration value.
Jun:
It stores the values of Crop factors for the month of June (K c). This parameter is
Jul:
It stores the values of Crop factors for the month of July (K c). This parameter is
Aug:
It stores the values of Crop factors for the month of August (K c). This
value.
Sep:
It stores the values of Crop factors for the month of September (K c). This
value.
24
Oct:
It stores the values of Crop factors for the month of October (K c). This
value.
Nov:
It stores the values of Crop factors for the month of November (Kc). This
value.
Dec:
It stores the values of Crop factors for the month of December (Kc). This
value.
Description:
It stores a description of the land use codes. This part of the table does not
contain any parameter of the model but it must be always filled with some
characters.
25
1.10. Channel tab: Drainage Network Parameters

The tab Channel contains information on the characteristics of the channels of the river network. The tab is
divided into two parts: General and Custom.
Figure 13 - Picture of the tab Channel of TOPKAPI Visual Interface

General (Based on Strahlers order numbers)
This area contains the general settings of the channels parameters. PreTPK will fill in the table with default values
corresponding to triangular channels and Strahlers orders.
The values of the parameters stored in the table General refer to the Strahlers orders of the channels and they are
used to set general channels characteristics of the river network.
The parameters of the table refer to the following equations, namely the non-linear reservoirs describing the
channel component for rectangular and triangular sections respectively:
s A
Vc
rc Qcu 0 x
t
n Cx
B
X
Vc
4
s sen 3
Vc
rc Qcu 2 0
Vc 3
4
1
t
2 3 n tan 3 X 3
26
General table
Section Type:
It is used to select the shape of the river section. There are two options
available1:
o
Triangular channels
o
Rectangular channels
StrahlerOrder:
It stores the Strahlers order of the river branch.
1st Manning Coefficient[s/m^(1/3)]: It stores the Manning coefficient for the riverbed channel roughness
(n). The initial values of parameter nc can be defined by referring to the Tables
5.5 and 5.6 in the book on Open Channel Hydraulics by Chow (1959) and a
report on Roughness Characteristics of Natural Channel by Harry. H. Barnes
(1967).
Width %:
This value is automatically set by the Visual Interface and must not be
modified.
Q Riverbed:
It stores the maximum discharge that can flow through the channel in m3/s. It
must be set to a value larger than any possible observed or simulated discharge.
Angle_Riverbed:
It stores the slope of the riverbed sides in case of triangular channels (). This
value is not an angle but a distance in m according to the following graph:
Wexc:
modified.
2nd Manning Coefficient[s/m^(1/3)]: This value is automatically set by the Visual Interface and must not
be modified
QMax:
This value is automatically set by the Visual Interface and must not be modified
Angle_FloodPlain:
This value is automatically set by the Visual Interface and must not be modified
Custom Table
This area contains the settings of the channels parameters for custom branches of the river network. The channel
parameters set on the basis of Strahlers order might be not sufficient for describing the river network because in
some cases the parameters assigned to a branch by its Strahlers order might be different from the real parameters
of the branch. In this case the Custom Table can be used. The raster number of the extreme sections of the branch
must be entered in the Custom Table (the order is not fixed) together with the parameters of the branch.
Section Type:
It is used to select the shape of the river section. The type of section can be
chosen from the menu between Triangular and Rectangular. Note that many
other options are available in the menu but they are not functional in the present
version of the TOPKAPI model.
Ctrl_Pnt1:
Raster number of one extreme of the custom river branch.
Ctrl_Pnt2:
Raster number of one extreme of the custom river branch.
Note that many other options are available in the drop down menu, but they are not functional in the present
version of the TOPKAPI model.
27
1st Manning Coefficient[s/m^(1/3)]: It stores the Manning coefficient for the riverbed channel roughness
(n). The initial values of parameter nc can be defined by referring to the Tables
5.5 and 5.6 in the book on Open Channel Hydraulics by Chow (1959) and a
report on Roughness Characteristics of Natural Channel by Harry. H. Barnes
(1967).
Width %:
modified.
Q Riverbed:
It stores the maximum discharge that can flow through the channel in m3/s. It
must be set to a value larger than any possible observed or simulated discharge.
AngleAlvMin:
It stores the minimum slope of the riverbed sides in case of triangular channels
(). The minimum sides slope corresponds to the custom branch extreme that
has the smallest drained area. Between the extremes of the custom branch the
slope of the riverbed sides varies gradually on the basis of the drained area. The
value stored for the slope of the riverbed sides is not an angle but a distance in
m according to the following graph:
AngleAlvMax:
It stores the maximum slope of the riverbed sides in case of triangular channels
(). The maximum sides slope corresponds to the custom branch extreme that
has the largest drained area. Between the extremes of the custom branch the
slope of the riverbed sides varies gradually on the basis of the drained area.
Wexc:
modified.
2nd Manning Coefficient[s/m^(1/3)]: This value is automatically set by the Visual Interface and must not
be modified.
Qmax:
modified.
AngleGolMin:
modified.
AngleGolMax:
modified.
Name:
It stores a description of the land use codes. This part of the table does not
contain any parameter of the model but it must be always filled with some
characters.
28
1.11. Outputs tab: Model Output Points

The tab Outputs contains information on the Output points of the model, namely the river network points in which
the TOPKAPI model will write the results of the simulations. PreTPK will fill in the table with points from a
selected shape file. More output points can be added manually.
Figure 14 - Picture of the tab Outputs of TOPKAPI Visual Interface

Model Output Points table
Raster Code:
It stores the raster code of the output section of the river network.
Station Code:
It stores the station code of the measurement station corresponding to the

output section. The code used here must coincide with the code stored in the
discharge input file (see the description of the Station tab).
Station Name:
It stores the name of the output point.
Sub-basin Outlet:
This box is used to select the type of output the model will write for an output
point. There are three options:
1
if the box contains 1 the model writes all possible information about the
sub-basin closed by that river section including: observed discharge,
simulated discharge, mean rainfall, mean snow cover, mean evapotranspiration, mean soil saturation, ect.
If the box contains 0 the model writes only information on simulated

discharge.
If the box contains 2, this sets an interbasin section. In this case raster
code contains a reference number used to indicate the interbasin (usually
29
the raster number of the downstream point is used), station code contains
a number used to identify the interbasin (usually it is a negative number).
1.12. Temperature tab: Average Monthly Temperatures

The tab Temperature contains information on the average monthly temperature values used inside the evapotranspiration component. PreTPK will fill in the table with monthly average temperature area codes included in the
catchment.
The parameters of the table refer to the elements of the equation used to compute potential evapo-transpiration (see
TOPKAPI model Reference Manual):
ET0 K c ( NWtaTt )
t
30 24 3600
Figure 15 - Picture of the tab Temperature of TOPKAPI Visual Interface

Average Monthly Temperatures
Area Code:
It stores the codes of the areas where mean monthly temperature values have
been computed, namely the codes contained in the Thiessen polygons map
(*.tht).
Elevation:
It stores the elevation of the thermometers used to compute the mean monthly
temperature of the area.
Area Name:
It stores the name of the thermometer used to compute the mean monthly
temperature of the area.
Jan:
It stores the mean monthly temperature values computed in January in C.
Feb:
It stores the mean monthly temperature values computed in February in C.
Mar:
It stores the mean monthly temperature values computed in March in C.
30
Apr:
It stores the mean monthly temperature values computed in April in C.
May:
It stores the mean monthly temperature values computed in May in C.
Jun:
It stores the mean monthly temperature values computed in June in C.
Jul:
It stores the mean monthly temperature values computed in July in C.
Aug:
It stores the mean monthly temperature values computed in August in C.
Sep:
It stores the mean monthly temperature values computed in September in C.
Oct:
It stores the mean monthly temperature values computed in October in C.
Nov:
It stores the mean monthly temperature values computed in November in C.
Dec:
It stores the mean monthly temperature values computed in December in C.
31
1.13. ET-Snow tab: Evapo-transpiration and Snowmelt parameters

The tab ET-Snow contains information on the parameters of the Snowmelt component and parameters of the
Evapo-transpiration component.
Figure 16 - Picture of the tab ET-Snow of TOPKAPI Visual Interface

Evapo-transpiration
This area contains information on evapo-transpiration parameters. The parameters refer to equations used to
compute actual evapo-transpiration from potential evapo-transpiration:
ETa 0
ETa ET0
ETa ET0
V
Vsat
for
V Vsat
for
Vsat V Vsat
for
V Vsat
where: Eta = actual evapo-transpiration for a specified time step t [mm].

ET0 = reference evapo-transpiration for a specified time step t [mm].
V = actual volume of water stored into the soil [m3].
Vsat = local saturation volume [m3].
32
In the present version of TOPKAPI model it is possible to compute potential evapo-transpiration according to two
different formulas:
o
Thortwaite formula (default)
Blaney-Criddle formula
In general Thortwaite formula works fine, but in highest mountain regions it may underestimate evapotranspiration especially when it is used above 2000 m s.l.m.. For this reason at high elevation it is possible to use
Blaney-Criddle formula.
The Evapo-transpiration area includes the following options:
Use Blaney-Criddle formula
This check box is used to activate computation of potential evapotranspiration using Blaney-Criddle formula.
Blaney-Criddle elevation limit
This box is used to select the elevation value above which the BlaneyCriddle formula will be used.
Minimum value of soil moisture to have ETA: It stores the minimum value of soil moisture that is
necessary in order to have evapo-transpiration ().
Minimum value of soil moisture in order to have ETA equal to ETP: It stores the value of soil moisture
above which actual evapo-transpiration is equal to potential evapo-transpiration
().
ETP rate due to air humidity table: It stores a coefficient to be used to reduce ETP computation because of
air humidity. The table stores one value for each month of the year. Default
values, when no ETP reduction is necessary, is 1.
Snow
This area contains information on the parameters used in the snowmelt component.
Rainfall/Snowfall Temperature threshold [C]:
It stores the temperature value corresponding to

snowfall during precipitation events in C.
Default value is 0C.
Temperature Lapse Rate with elevation [C/m]:
It stores the value of lapse rate for temperature in

C/m.
Default value is 0.0065 C/m.
Minimum Temperature for shallow snow pack [C]: It stores the minimum temperature that the snowpack
can reach in the topmost part (snow pack with
variable temperature).
Default value is -10C.
Maximum snow pack height with variable temperature [mm]: It stores snow pack depth that changes its
temperature because of sun and air temperature.
Default value is 2000mm.
Soil Frost Threshold [C]:
It stores the air temperature value bellow which the

soil is considered to be frozen.
Default value is -20C.
Albedo [0.0 1.0]
It stores values for albedo.

Default value is 0.4.
Compute mountains shadows
This check box is used to activate computation of the

effects of mountains shadows on snowmelt.
33
1.14. Reservoirs tab: Reservoirs Settings and Data

The water storage of a lake or a reservoir is the summation of the single water storage of each cell within the lake
or the reservoir. The simple lake/reservoir model included in the TOPKAPI model for an uncontrolled lake or
reservoir is based on the mass balance law as:
V
Qi Qo
t
where: V
Qi
water volume of the lake/reservoir
inflow discharge to the lake/reservoir
Qo =
release discharge from the lake/reservoir, which can be expressed on the basis of the
type and geometry of the sluice gates or on the basis of a water level-released
discharge curve.
As described in Chapter 2.10 of TOPKAPI manual, TOPKAPI model can run different types of reservoir models.
1) Using external data (data provided by the User) for:
water level or stored water volume
released discharge
water level or volume and released discharge
2) Using an automatic simulation based on mass balance equation
In any case, whatever the reservoir model simulation is, the water level-stored volume curve (H-V) of the reservoir
must be provided to TOPKAPI: a table describing reservoir water storage volume as a function of reservoir watersurface elevation must be provided.
Figure 17 - Picture of the tab Reservoir component of TOPKAPI Visual Interface
34
TOPKAPI Visual Interface can be used to provide inputs to the different reservoir models. The Tab Reservoir
Component contains information on reservoirs. The table contained in Tab Reservoir component is used to manage
the characteristics of the different lakes, one for each line of the table.
If external data are used to simulate reservoir behavior, an automatic type of modeling must be set in any case to
face situations in which external data are missing.
Reservoir Info Tables
These tables contain general geometric information on the reservoirs. They must be provided in any case, whatever
the reservoir simulation type is, as they are used for both automatic and external data driven simulations.
Level-Volume
This box contains path and name of the file containing the water level-water
volume curve. The curve describes the amount of water stored in the reservoir
(V in m3) as a function of surface water level (H in m).
Level-Discharge
This box contains path and name of the file containing the water level-released
discharge curve. This curve describes the amount of water that is released from
the reservoir (Q in m3/s) as a function of reservoir water level (H in m). It
describes a very general operating rule for the reservoir.
The Level-Discharge curve is used when SimMode is set to 1.
Level-MaxDischarge
This box contains path and name of the file containing the water levelmaximum released discharge curve. This curve describes the maximum
amount of water that can be released from the reservoir (Q in m3/s) as a
function of reservoir water level (H in m). It depends on sluice gates and
spillways geometry and it is used to avoid unrealistic water releases during
reservoir modeling.
Spillways
This box contains path and name of the file containing the geometric
description of gateways. Information are used when SimMode is set to 0,
namely when performing a fully automatic reservoir simulation.
NOTE: Water level values in H-Q, H-Qmax and H-V curves can be absolute elevation values or relative ones, but
THEY MUST BE ALL OF THE SAME TYPE. Water level data can also be absolute elevation values or
relative ones, but THEY MUST BE OF THE SAME TYPE as in H-Q, H-Qmax and H-V curves. Only in
case absolute elevation values are used for H-Q, H-Qmax and H-V curves it is possible to provide water
level data as relative elevation values and use Level Data Reference value as a conversion factor.
Reservoirs Parameters Table
This table contains settings for reservoirs simulations. One row MUST be added to the table for each reservoir. For
those reservoirs that are modeled using external data (water level and/or discharge), the table is used to set the type
of modeling to be adopted in case external data are missing and during forecasting periods.
The Reservoir Parameters Table includes the following fields:
Active:
This check box is used to activate/deactivate the reservoir. Each reservoir in the
model can be deactivated at any time.
Land Use Code:
It stores the land use code corresponding to the reservoir. This value is
substituted to normal land use codes inside TOPKAPI land use map. Usually
land use code for lakes is stored as 6000 + ID in order to easily recognize them.
In order to make the model work correctly, the land use code of each lake
must be added to the land use table in Tab Land Use, where Manning
coefficients and crop factors parameters for water bodies will be also added. It
is also necessary to add a soil type code which describes characteristics of the
soil beneath the water. Soil code is 999999 and it MUST be added in Tab
Soil.
ID:
This box contains the identifying number of the reservoir (ID). It must be equal
to the lake code used in file *.lake (see pre-processing instructions).
35
Raster Code:
This box contains TOPKAPI raster code of the closing cell of the reservoir,
namely the pixel where the dam is located.
Name:
This box contains the name of the reservoir.
Initial Volume:
This box contains the initial water volume stored in the reservoir at the
beginning of the simulation (in m3).
Minimum Outflow:
This box contains the minimum discharge that must be released by the
reservoir. It represents environmental flow, namely the minimum quantity, of
water flow required to sustain freshwater and downstream river water life.
Level Data Reference:
This box contains reference elevation value that is used when observed water
level data are relative data while all other elevation quantities are absolute
values. Set it to 0 when using absolute elevation or relative elevation
everywhere.
Max Water Level:
This box contains the maximum value for water level in the reservoir. In any
case water level will never overcome this value during reservoir modeling. This
measure is adopted to avoid unrealistic reservoir water levels when dealing
with automatic simulation and data in very uncertain contexts.
Max Water Level value for each reservoir MUST never be larger than the
last water level value stored in Level-Volume Info Table.
Simulation Mode:
This box is used to store the type of reservoir modeling TOPKAPI is going to
use during simulations. There are the following possibilities:
0
Compute water release from sluiceways and spillways

This type of reservoir functioning offers the simplest of all routing
situations: output discharge from the reservoir is a function of watersurface elevation and spillways geometry. Such a reservoir may have
un-gated sluiceways and/or uncontrolled spillways. Reservoir having
sluiceway or spillway gates can be treated as simple reservoirs if the
gates remain at fixed openings.
User must provide to TOPKAPI a geometric description of
sluiceways and spillways. The model will automatically compute
water release on the basis of inflow, reservoir water level and gates
geometry.
Compute water release using a water level-discharge table

This type of reservoir uses a surface water level-released discharge
table in order to compute outflow from the reservoir.
User must provide to TOPKAPI a discharge table describing the
outflow from the reservoir as a function of water-surface elevation
(release rule) and a table describing the maximum possible outflow
from the reservoir as a function of water-surface elevation. At each
time step TOPKAPI will compute the released discharge which will
be in any case smaller than the maximum possible one.
Use last measured water release as constant

TOPKAPI will use the last measured released discharge provided by
the user as a constant release. The model will NOT update water
level according to water inflow to the reservoir.
Water release equal to water inflow to the reservoir

TOPKAPI will set water release from the reservoir equal to water
inflow to the lake. Inflow does not include rainfall fallen on the lake
surface. Inflow is immediately transformed into outflow with no
delay or routing.
36
Input Data
The reservoir component of TOPKAPI model can be used also with observed data:
If outflow data are available , the reservoir component will use them to compute the storage volume in
the reservoir at the end of time step t as:
V t I O
where: V = volume of water stored (or released) in the reservoir during the time step t
I = inflow to the reservoir computed using TOPKAPI on upstream pixels
O = outflow from the reservoir provided as observed data
If surface water level data are available, the reservoir component will use them to compute the average
outflow from the reservoir during time step t as:
OI
V
t
where: V = volume of water stored (or released) in the reservoir during the time step t. It is
obtained from observed surface water level data using the level-storage curve of the
reservoir.
I = inflow to the reservoir computed using TOPKAPI on upstream pixels
O = outflow from the reservoir
If both outflow data and surface water level data are available, the reservoir component will use them.
Input Data Reservoir Water Level

Path:
This box contains the path and the name of the file containing reservoir water
level data.
Data Unit:
This drop down menu is used to select measurement units for reservoir water
level data contained in the data file.
Data File Format:
These check boxes are used to select file format of reservoir water level data
file. There are two possible options:
o csv file format,
Reservoir water level data can be provided in both absolute and relative values. In case the data are provided as
relative elevations while Reservoir Info Tables and Reservoir Parameter Table provide as absolute elevations,
Level Data Reference in Reservoir Parameter Table can be used to set the reference elevation value. Set it to 0
when all elevation information and data are of the same type.
Input Data Reservoir Water Volume
Path:
volume data
Data Unit:
volume data contained in the data file.
Data File Format:
These check boxes are used to select file format of reservoir water volume data
o csv file format,
37
Input Data - Release

Path:
release data.
Data Unit:
release data contained in the data file.
Data File Format:
These check boxes are used to select file format of reservoir water release data
o csv file format,
38
1.15. Interbasin tab: Inter-basin Contribution

The Tab Interbasins contains information on the computation of interbasins contribution to river flow. The
present version of TOPKAPI model can be coupled to a hydraulic model and provide distributed discharge on a
stretch of the river. TOPKAPI can be used to provide interbasins contributions: an upstream and a downstream
point must be provided in order to select a stretch of the river and define the interbasin delimited by the two points
(namely the intersection of downstream sub-basin and the upstream sub-basin).
The model will find all the pixels belonging to the defined stretch of the river and it will sum discharges provided
to these river pixels from the surrounding basin pixels. The computed inflow to the river can be divided by the
length of the river and the time series of the distributed inflow to the river can be used in a hydraulic model.
Figure 18 - Picture of the tab Interbasins of TOPKAPI Visual Interface

Interbasin Contribution table
Station code:
This box stores the codes of interbasins. The code stored in this area must be
the same used in Tab Outputs as Station code for type 2.
The Station code has no particular meaning, it is only used to identify
interbasins outputs.
Upstream raster code
It stores TOPKAPI raster code of the upstream pixel of the stretch of the river.
Downstream raster code
It stores TOPKAPI raster code of the downstream pixel of the stretch of the
river.
39
Length
It can store two different values:

o the length of the river stretch measured on the real river using the
hydraulic model
o 1 In this case the model does not provide a distributed flow value
but a cumulated one.
Figure 19 Scheme of TOPKAPI interbasins couplet with a Hydraulic model
40
1.16. Inflow tab: Inflow Points Settings and Data

The Tab Inflow contains information on inflow discharge to TOPKAPI model. The present version of TOPKAPI
model can take an inflow at a specific pixel and route the discharge through the catchment. Inflow data are
overwritten to TOPKAPI outputs on the pixels where the inflow is located.
Figure 20 - Picture of the tab Inflow of TOPKAPI Visual Interface

Inflow Table
ID
This box contains the ID of the inflow points (code). The ID are also used in
the Inflow data file in order to associate each point to its discharge value.
Raster code
This box contains the raster code of the pixel where the inflow is located.
Name
This box contains a description of the inflow point.
Inflow data file

Path:
This box contains the path and the name of the file containing inflow discharge
Data Unit:
This drop down menu is used to select measurement units for inflow discharge
data contained in the data file.
Data File Format:
These check boxes are used to select file format of inflow discharge data file.
There are two possible options:
o csv file format,
41
1.17. Outflow tab: Outflow Points Settings and Data

The Tab Outflow contains information on water withdrawal from TOPKAPI model catchment. In the present
version of TOPKAPI model, the User can withdraw water at a specific pixel and eventually return water to another
pixel.
Figure 21 - Picture of the tab Outflow of TOPKAPI Visual Interface

Outflow Table
ID
This box contains the ID (code) of the outflow points. The IDs are also used in
the Outflow data file in order to associate each point to its water withdrawal
value.
ID-Cell-Out
This box contains the raster code of the pixel where the withdrawal is located.
ID-Cell-In
This box contains the raster code of the pixel where water return is located. If
there is no water return, the box is set to -9999.
Min. Flow
This box contains minimum discharge value to be left in the river after water
withdrawal.
Name
This box contains the name of water withdrawal point.
Outflow data file

Path
This box contains the path and the name of the file containing withdrawal
discharge.
Data Unit:
This drop down menu is used to select measurement units for withdrawal
discharge data contained in the data file.
42
Data File Format:
These check boxes are used to select file format of withdrawal discharge data
o csv file format,
43
2.
2. Step by Step set-up of TOPKAPIs Parameters Input File
STEP BY STEP SET-UP OF TOPKAPI MODEL PARAMETERS

INPUT FILE
2.1.
Reno river demo
Once you have completed pre-processing work using PreTPK Visual Interface, you can press ITOPKAPI button
inside PreTPK visual interface and run ITOPKAPI.
A new window will appear asking you to select a tpk file, namely a TOPKAPI parameters input file. Select the one
you created during pre-processing work:
\RENO_MWDEMO\TOPKAPI\Reno.tpk
Figure 22 Select Reno.tpk file

ITOPKAPI Visual Interface will open.
In order to run your first TOPKAPI simulation, all parameters must be set-up using the visual interface. Some of
them are already there, for this reason they will not be described in the following paragraphs
44
2.2.
Reno river demo: General Settings
When ITOPKAPI opens for the first time after completing the pre-processing phase (PreTPK), it shows some of
the parameters that are necessary for running TOPKAPI model. The blank boxes must be filled in before running
the first simulation.
Start filling in boxes in General Settings Tab:
o
Set the latitude and longitude of the catchment (you can get them from Map Window project)
Activate model components: Evapo-transpiration, Snow, Percolation and Reservoirs
Select the type of input data you are going to use: Station based rainfall data and Station based
Temperature data.
Figure 23 The General Settings tab
2.3.
Reno river demo: Simulation Time Period Settings
The settings for simulation time period and state file storing must be filled in before you can run a TOPKAPI
model simulation.
Start filling in boxes for dates and time steps of your simulation:
o
Set the computation time step length of your simulation to 60 minutes. It is the time step of point input
data for rainfall and temperature.
Set the simulation start date to 01/01/2000 01:00
Set the simulation end date to 31/12/2000 23:00
45
Set the computation time for channel component to 15 minutes
Since you are running a new simulation from scratch, there is no state file ready to use. The model will start using
a default hydrological state for the catchment that is set according to the season.
Start filling in boxes for state file storing:
o
Set the state data storing start date to 01/11/2000 01:00
Set the state data storing end date to 11/11/2000 23:00
Set state data storing frequency to 60 minutes. This will set the model to save a new state file every hour
within the selected time period.
Start filling in boxes for printing state file:

o
Select the type of state file you wish to save. Select them all: one map will be saved for each hydrological
quantity.
Figure 24 The Simulation time period and settings tab
46
2.4.
Reno river demo: Stations Coordinates and Data
You must set rainfall and temperature input data. Basic hydro-meteorological data for the Demo application are
provided. They can be found in folder CaseStudy\BASICDATA\ of the installation CD.
Unzip file Basic_data_HydroMeteoData.zip and save its contents to RENO_MWDEMO\HydroMeteoData\
2.4.1.
Rainfall data
You can now fill in information regarding rainfall data:

o
Use the button to select the rain-gauges coordinates file: \RENO_MWDEMO\HydroMeteoData\

Reno_Raingauges.csv.xyz
Use the button to

Reno_Rain_2000.csv
Set the Data Unit to [mm*100]
Select Csv File Format
Select ISD interpolation method
2.4.2.
select
the
rain-gauges
data
file:
\RENO_MWDEMO\HydroMeteoData\
Temperature data
You can now fill in information regarding temperature data:

o
Use the button to select the thermometers coordinates file: \RENO_MWDEMO\HydroMeteoData\

Reno_Thermometers.csv.xyz
Use the button to select the

Reno_Temp_2000.csv
Set the Data Unit to [C*100]
Select ISD interpolation method
2.4.3.
thermometers data
file: \RENO_MWDEMO\HydroMeteoData\
Discharge data
You can now fill in information regarding discharge data at predefined river points:
o
Use the button to

Reno_Qobs_2000.csv
Set the Data Unit to [m3/s*100]
select
the
discharge
data
file:
\RENO_MWDEMO\HydroMeteoData\
47
Figure 25 the station coordinates and data tab
2.5.
Reno river demo: Soil Parameters
Default values are present in this tab. PreTPK has set the values using Look-up tables and soil codes. You can
leave them as they are if you wish to run a simulation with default parameters.
In order to get better results from your first simulation on the Reno river demo catchment, you should modify some
of the soil parameters as follows. The soil types to be modified are highlighted in blue.
Table 1 Soil type coefficients
Code
Horizontal
Permeability
at Saturation
[m/s]
Saturated
Water
Content
Residual
Water
Content
Soil
Depth
[m]
Horizontal
NonLinear
Reservoir
Exponent
Vertical
Permeability
at Saturation
[m/s]
Vertical
NonLinear
Reservoir
Exponent
Description
6410
5.47E-05
0.433
0.263
1.055
2.5
5.47E-06
13.8
6441
4.92E-05
0.432
0.312
0.725
2.5
4.92E-06
20
Be128-2/3bc
6443
4.92E-04
0.432
0.312
1.268
2.5
4.92E-07
20
Be130-2/3bc
6445
4.92E-05
0.432
0.312
1.25
2.5
4.92E-06
20
Be133-2/3a
6539
4.92E-05
0.432
0.312
1.25
2.5
4.92E-06
20
Je86-2/3a
6567
8.19E-04
0.423
0.303
1.5
2.5
8.19E-06
23.8
Lo71-3ab
6604
1.46E-04
0.412
0.172
0.935
2.5
1.46E-07
12.8
Po28-1bc
6632
4.92E-05
0.432
0.312
1.25
2.5
4.92E-06
20
6997
0.05
2.5
12.8
Bd68-2bc
Re86-2/3b
WATER
48
2.6.
Reno river demo: Model Output Points
Default values are already present in this tab. They are output points defined in PreTPK. Let us modify the type of
output for some of the points.
The column called Sub-basin Outlet is used to define the type of output point:
1
Sub-basin output point:
the model writes all possible information about the sub-basin closed
by the river section including: observed discharge, simulated
discharge, mean rainfall, mean snow cover, mean evapo-transpiration,
mean soil saturation, ect.
Discharge output point:
the model writes information on simulated discharge only.
Let us change default values in column Sub-basin Outlet:
Station Name
Sub-basin Outlet
Calcara
Casalecchio_Chiusa
Castenaso
Forcelli
Mordano
Ponte_Bastia
Sesto_Imolese
Vergato
Figure 26 Change default values in Sub-basin Outlet column of the table.
49
2.7.
Reno river demo: Evapo-Transpiration and Snowmelt Parameters
The Evapo-Traspiration and Snowmelt tab shows some empty boxes that must be filled in.
Start filling in boxes for evapo-transpiration component of the model:
o
Set the minimum value of soil moisture to have ETA to 0.2
Set the minimum value of soil moisture to have ETA=ETP to 0.8
You can leave all other boxes to their default values.
Figure 27 - Evapo-transpiration and snowmelt parameters
50
2.8.
Reno river demo: Reservoirs
The Tab Reservoirs contains information on the reservoirs that are going to be added to the model. Information on
reservoirs for the Demo application are provided. It can be found in folder CaseStudy\BASICDATA\ of the
installation CD.
Unzip file Basic_data_Reservoirs.zip and save its contents to RENO_MWDEMO\Reservoirs\
In order to add Suviana reservoir to the Reno river TOPKAPI demo, the outlet cell of the lake must be located:
o
Turn on the TPK_CELL_POLYGON, STRAHLER and TPK_LAKES layers in Topkapi group
Figure 28 Display of TPK_CELL_POLYGON, STRAHLER (in pink) and TPK_LAKES (in green)
layers.
o
Locate the outlet pixel of the reservoir in TPK_LAKES layer and check it is on a pixel with the right
Strhalers order
Find out the raster number using labels in layer TPK_CELL_POLYGON. For the Reno river demo, the
reservoir outlet pixel is number 4500
Add the raster pixel number to the Reservoir tab.
Insert other requested information in Reservoir tab (see paragraph 1.14 for a detailed description of
tables fields)
51
Insert other requested information in Reservoir tab (see paragraph 1.14 for a detailed description of
tables fields)
Set the ID box to 12. The ID box contains the identifying number of the reservoir (ID). It is equal to the
lake code in layer TPK_LAKES.
Set the Land Use Code to 6012. The Land Use Cod stores the land use code corresponding to the
reservoir. This value is substituted to normal land use codes inside TOPKAPI land use map. Usually land
use code for lakes is stored as 6000 + ID in order to easily recognize them.
Add the Suviana reservoir Land Use Code to the Land Use Tab.
Add the reservoir Soil code (999999) to the Soil Tab.
Fill in the boxes in the bottom part of Reservoirs Tab using file in folder RENO_MWDEMO\Reservoirs\
52
2.9.
Reno river demo: Interbasins Contribution
The Tab Interbasins contains information on the computation of inter-basins contribution to river flow. The
present version of TOPKAPI model can be coupled to a hydraulic model and provide distributed discharge on a
stretch of the river. TOPKAPI can be used to provide interbasins contributions: an upstream and a downstream
point must be provided in order to select a stretch of the river and define the interbasin delimited by the two points
(namely the intersection of downstream sub-basin and the upstream sub-basin).
Let us define one inter-basin contribution area:
o
Open your map window project and activate layers TPK_CELL_POLYGON and STRAHLER
Add upstream and downstream locations to a shapefile:
1.
Use
to open a new shapefile.
2.
Set its name to \RENO_MWDEMO\Hydrography\Inter-basin_contribution.shp and its type to

Point and click OK. If you get a warning about no projection, click OK to take the default action
of setting the new shapefiles projection to the project projection. Click OK on the warning about
the extents of the new shapefile.
3.
Use
to add upstream and downstream points for inter-basin contribution areas. Move the
mouse on upstream and downstream cells to input coordinates and click left mouse button to add
the point to the shapefile.
Figure 29 Add points to a shapefile

o
Zoom in to upstream and downstream points to get cells raster numbers:
53
a) Upstream point
b) Downstream point
Figure 30 Find out raster numbers for upstream (a) and downstream (b) cell of inter-basin
contribution area.
o
Insert the inter-basin contribution in Interbasin Contribution table. Input raster numbers of upstream and
downstream cells in the table and define a Station Code.
Figure 31 Insert an inter-basin contribution area to the table

o
Insert the inter-basin contribution in Model Output Points table. Use the following information:
Raster Code = 1597
Its raster code number of upstream point
Station Code = 1001
Its the Station Code entered in in Interbasin Contribution table
Station Name = Interbasin1
Its the name of the interbasin area
Sub-basin Outlet = 2
Its the value to define Interbasins
54
Figure 32 - Insert the inter-basin contribution in Model Output Points table
55
2.10. Reno river demo: Inflow

The Tab Inflow contains information on inflow points locations. Information on inflow location for the Demo
application are provided. It can be found in folder CaseStudy\BASICDATA\ of the installation CD.
Unzip file Basic_data_InOutflow.zip and save its contents to RENO_MWDEMO\InOutflow\
Let us define one inflow point for Reno river demo.
o
Turn on layer Fake_Inflow in Basic Thematic Maps group
Turn on layers TPK_CELL_POLYGON and STRAHLER
Locate the position of the inflow point and check the raster number of the pixel where you wish to locate
it. In the Reno river demo, the raster number is 4734.
Insert the raster number in the table on the left hand side of the Inflow Tab. Set the ID number to 33
which is the code used for this inflow in the inflow data file.
Insert the name of the file containing discharge data for the inflow point in Inflow Tab.
56
Insert the raster number of the pixel containing the inflow into the Output Points Tab.
57
2.11. Reno river demo: Outflow (withdrawal)

The Tab Outflow contains information on withdrawal points locations. Information on withdrawal location for the
Demo application are provided. It can be found in folder CaseStudy\BASICDATA\ of the installation CD.
Unzip file Basic_data_InOutflow.zip and save its contents to RENO_MWDEMO\InOutflow\
Let us define one withdrawal point for Reno river demo.
o
Turn on layer ValSetta_withdrawal in Basic Thematic Maps group
Turn on layers TPK_CELL_POLYGON and STRAHLER
Locate the position of the withdrawal point and check the raster number of the pixel where you wish to
locate it. In the Reno river demo, the raster number is 2633.
Insert the raster number in the table in Outflow Tab. Set the ID number to 55 which is the code used for
this withdrawal in the outflow data file.
Insert the name of the file containing withdrawal discharge data for the outflow point in Outflow Tab.
Insert the raster number of the pixel containing the withdrawal point into the Output Points Tab.
58
2.12. Running TOPKAPI model

Once all boxes have been filled in, you can save your tpk file and run a TOPKAPI simulation using the Run
Topkapi button.
If the directory for storing state file is not available yet, the visual interface will prompt you with a dialog box
asking you if you wish to create it. Answer Yes.
Figure 33 Running TOPKAPI model dialog window

The next window will ask you to fill in data for your simulation. You can write a short description for it, so that it
will be easier to locate it in future.
Fill in the boxes:
o
Insert your name as the users name
Insert a short description for the simulation. You can write First simulation run with default parameters.
Check the View Run box in order to have a DOS window showing you the progresses of your simulation.
Click Run button to start your simulation
Figure 34 Setting information for TOPKAPI model simulation
59
Once you click the Run button the simulation starts and you must wait a few minutes. At the end of the simulation
run a window appears to let you know that the simulation has finished successfully.
Figure 35 End of simulation dialog box

Use the View Output button to display TOPKAPI models results.
REFER TO CHAPTER 2 STEP BY STEP VISUALIZATION OF TOPKAPI
MODEL RESULTS OF TPKVIEW USERS MANUAL TO CONTINUE
IMPLEMENTING THE REMO RIVER DEMO.
60
[End of document.]
61

Itopkapi Manual Eng

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Itopkapi Manual Eng

Uploaded by

Copyright:

Available Formats

AUTHOR

Dr. Cinzia Mazzetti

ITOPKAPI USERS MANUAL

ITOPKAPI Users Manual

ITOPKAPI USERS MANUAL

ITOPKAPI VISUAL INTERFACE ........................................................................................................ 4

Settings tab: General Settings................................................................................................ 6

Time-State tab: Simulation Time Period Settings ............................................................... 9

Stations tab: Station Coordinates and Data ....................................................................... 12

Maps tab: Meteo Maps Settings .......................................................................................... 15

Width tab: Rectangular Channel Widths ........................................................................... 18

Initial Cond tab: Initial Conditions ..................................................................................... 20

Soil tab: Soil Parameters ...................................................................................................... 21

Land Use tab: Land Use Parameters .................................................................................. 23

1.10. Channel tab: Drainage Network Parameters ..................................................................... 26

STEP BY STEP SET-UP OF TOPKAPI MODEL PARAMETERS INPUT FILE..................... 44

Reno river demo ................................................................................................................... 44

Reno river demo: General Settings ..................................................................................... 45

Reno river demo: Simulation Time Period Settings .......................................................... 45

Reno river demo: Stations Coordinates and Data ............................................................. 47

Reno river demo: Soil Parameters ...................................................................................... 48

Reno river demo: Model Output Points ............................................................................. 49

Reno river demo: Evapo-Transpiration and Snowmelt Parameters ............................... 50

Reno river demo: Reservoirs ............................................................................................... 51

Reno river demo: Interbasins Contribution ....................................................................... 53

2.10. Reno river demo: Inflow ...................................................................................................... 56

ITOPKAPI USERS MANUAL

ITOPKAPI USERS MANUAL

ITOPKAPI Visual Interface

1. ITOPKAPI Visual Interface

The Visual Interface of TOPKAPI model includes three different programs:

ITOPKAPI Visual Interface can be launched in many different ways:

ITOPKAPI USERS MANUAL

1. ITOPKAPI Visual Interface

You can run it from your desktop icon

The following paragraphs describe ITOPKAPI Visual Interface in details.

The present document is not intended as a description of TOPKAPI

ITOPKAPI USERS MANUAL

1. ITOPKAPI Visual Interface

Settings tab: General Settings

Figure 1 - Picture of the tab Settings of TOPKAPI Visual Interface

Total number of pixels of the basin

Dimension of the model pixels in m

Number of columns in the model window

Number of rows in the model window

X coordinate of the South-West corner of the model window

Y coordinate of the South-West corner of the model window

ITOPKAPI USERS MANUAL

1. ITOPKAPI Visual Interface

Latitude of the basin [DD]

Longitude of the basin [DD]

Drainage Network Info

Threshold Area [Km2]:

Flow Partition Coeff.

Input Data Type

If the evapo-transpiration component is active, then the box for entering

ITOPKAPI USERS MANUAL

1. ITOPKAPI Visual Interface

Active Model Components

The Evapo-transpiration box is used to activate the evapo-transpiration

ITOPKAPI USERS MANUAL

1. ITOPKAPI Visual Interface

Time-State tab: Simulation Time Period Settings

Figure 2 - Picture of the tab Time-State of TOPKAPI Visual Interface