TOPKAPI-

TOPKAPI-X
VISUAL INTERFACE

USER MANUAL

Riviera di Chiaia, 72
CAP 80122 Napoli (NA)
P. IVA 06568441213
iea@idrologiaeambiente.com
www.idrologiaeambiente.it
INDEX

1. STARTUP ..................................................................................................................................... 4
2. UNCOMPLETED CASES ................................................................................................................ 5
3. CREATE A NEW CASE .................................................................................................................. 6
3.1. CASE NAME ........................................................................................................................ 6
3.2. AVAILABLE DATA ................................................................................................................ 6
3.3. BASIN MAPS ....................................................................................................................... 7
3.4. EXTERNAL MAPS ................................................................................................................ 8
3.5. EDAPHOLOGY AND TEMPERATURE MAPS......................................................................... 9
3.6. SOIL TYPE ......................................................................................................................... 11
3.7. LAND USE ......................................................................................................................... 13
3.8. MEAN MONTHLY TEMPERATURES .................................................................................. 14
3.9. DRAINAGE NETWORK ...................................................................................................... 15
3.10. PERCOLATION AND GROUNDWATER .............................................................................. 16
3.11. SNOW MELTING/ACCUMULATION AND EVAPOTRANSPIRATION................................... 18
3.12. LAKES/RESERVOIRS .......................................................................................................... 19
3.13. CHANNELS........................................................................................................................ 21
3.14. INFLOWS/OUTFLOWS AND DISTRIBUTED CONTRIBUTES ............................................... 22
3.15. CONTROL POINTS ............................................................................................................ 24
4. OPEN AN EXISTING CASE .......................................................................................................... 26
4.1. GLOBAL CONTROLS .......................................................................................................... 26
4.2. GENERAL .......................................................................................................................... 27
4.3. MONTHLY TEMPERATURE ............................................................................................... 28
4.4. SOIL TYPE ......................................................................................................................... 29
4.5. LAND USE ......................................................................................................................... 30
4.6. LAKES/RESERVOIRS .......................................................................................................... 31
4.7. CHANNELS ........................................................................................................................ 33
4.8. INFLOWS AND DISTRIBUTED CONTRIBUTES .................................................................... 34
4.9. PERCOLATION AND GROUNDWATER .............................................................................. 36
4.10. SNOW MELTING/ACUMULATION AND EVAPOTRANSPIRATION ..................................... 38
4.11. CONTROL POINTS ............................................................................................................ 39
4.12. INPUT DATA ..................................................................................................................... 40
4.13. FORECAST ........................................................................................................................ 42
4.14. SIMULATION .................................................................................................................... 43
5. TOOLS ....................................................................................................................................... 45
5.1. COMPUTE EVALUATION INDEXES .................................................................................... 45
5.2. SIMULATION VISUALIZER ................................................................................................. 45
5.3. MAPS VISUALIZER ............................................................................................................ 47
5.4. PROPERTIES: SIMBOLOGY ................................................................................................ 49
5.5. PROPERTIES: LABELS ........................................................................................................ 50
5.6. COMPARE SIMULATIONS ................................................................................................. 50
1. STARTUP

To create a new case click on the CREATE A NEW CASE button (left), choose the Working Directory
and follow the steps described in Section 3. If the same river will be calibrated with different
resolutions, a suggestion is to create a folder for each project and inside it one subfolder for each
case inherent to the project. The cases should be different from each other in terms of the
resolution or in term of the drainage network (i.e. the Threshold Area to have cells with channel
component, see Section 3.9). When all the cases have been calibrated they can be compared using
the Compare Simulations Tools (see Section 5.4).
Remember that the creation can be saved at any step. Clicking on the exit button on top right the
program will ask if the created case must be saved or not. In the first case, the case creation can
be continued when the TOPKAPI-X is run by clicking on the CONTINUE AN UNCOMPLETED
WIZARD button (bottom), as described in Section 2. If the creation is not saved the working
directory and each subfolder will be deleted.

To open an existing case click on the OPEN AN EXISTING CASE button (right) and choose the
desired .topx file. Opening an existing case will redirect the user to the main form described in
Section 4.
2. UNCOMPLETED CASES

If a case creation has not been completed and it has been saved it will appear in this form after
clicking on the CONTINUE AN UNCOMPLETED WIZARD button on the bottom of the STARTUP
form. The case creation can be continued double clicking on the Case Name and the creation will
restart at the step where it has been stopped.
3. CREATE A NEW CASE

3.1. CASE NAME

The case name must be provided after choosing the working directory. This name is used as the
name of most of the configuration files, please do not use special characters that are not allowed
as file path (i.e / / | - , . ; etc...).
Clicking on the Next button, inside the working directory a file named river_name, containing the
case name, and a subfolder named Maps are created.
The user should not manually modify any file inside the working directory. This could cause
unexpected errors. The TOPKAPI-X VISUAL INTERFACE allows all the files to be managed and does
not require any manual operation.

3.2. AVAILABLE DATA

Before starting to create the case at least 5 maps must be available. All the maps must have an
ASCII GRID FORMAT, THE SAME MAP WINDOW and THE SAME CELL SIZE. If these requirements
are not satisfied the program will notify an error.
The required maps (see Section 3.3 and 3.4) are:
a) DEM
b) BASIN MASK
c) OUTLETS MAP
d) SOIL TYPE MAP
e) LAND USE MAPS

These maps must be created by the user, which may decide to provide the FILLED DEM, the FLOW
DIRECTIONS and the FLOW ACCUMULATION maps or to let the TOPKAPI-X to automatically create
them. This can be done clicking on one of the following buttons:

1. CREATE FILLED DEM, FLOW DIRECTIONS AND FLOW ACCUMULATION MAPS: In this case the
program creates the Filled DEM using a simple algorithm which iteratively checks all the cells
inside the basin mask and fills any sink it founds. The border cells elevation is increased if higher
cells are found around them and the outlet cells elevation is reduced if lower cells are found
around them. The Flow Directions and Flow Accumulation Maps are then created according to
the steepest slope directions. The user must provide the required maps as described in Section
3.3.
2. I PREFER TO PROVIDE FILLED DEM, FLOW DIRECTION AND FLOW ACCUMULATION MAPS
OBTAINED BY AN EXTERNAL SOFTWARE: In this case the user must provide also the Filled
DEM, the Flow Directions and the Flow Accumulation Maps after creating them using the
favourite external GIS software as described in Section 3.4.

3.3. BASIN MAPS

In this step the following maps must be provided. Remember that all of them must have THE
SAME MAP WINDOW and THE SAME CELL SIZE. Moreover they must be provided with the
XLLCORNER and the YLLCORNER and not with XLLCENTER and YLLCENTER.
DEM ASCII MAP: The DEM contains the elevation of each cell inside the window map or at least of
each cell inside the basin mask.

BASIN MASK ASCII MAP: The BASIN MASK is a map containing integer values equal to 1 for each
cell inside the catchment and to NoData otherwise.

BASIN OUTLETS ASCII MAP: The BASIN OUTLETS MAP must contain integer values equal to 1 for
each outlet of the catchment and to NoData otherwise.

RIVER BED ASCII MAP: The RIVER BED MAP is not necessary for the case creation, but the user can
provide it to the TOPKAPI-X to help the software to identify the desired channel network.
Using this map the software will decrease the elevation of the cells that have value equal to
1 in the River Bed Map. The elevation is reduced to the percentage written in the
Enforcement Ratio field (i.e. an elevation of 100 m will be reduced to 95 m if the
Enforcement Ratio is equal to 95)

When at least the DEM, Mask and Outlets maps are provided the Next button will be enabled and
the case creation can be continued.

3.4. EXTERNAL MAPS

In this step the following maps must be provided:

FILLED DEM ASCII MAP: The Filled DEM is a map containing the elevation of each cell of the map
window after filling the original DEM.

BASIN MASK ASCII MAP: The BASIN MASK is a map containing integer values equal to 1 for each
cell inside the catchment and to NoData otherwise.

BASIN OUTLETS ASCII MAP: The BASIN OUTLETS MAP must contain integer values equal to 1 for
each outlet of the catchment and to NoData otherwise.
FLOW DIRECTION ASCII MAP: The FLOW DIRECTION is a map containing integer values
corresponding to the flow direction of each cell inside the window map. The flow directions
are coded according to the following scheme.

FLOW ACCUMULATION ASCII MAP: The FLOW ACCUMULATION is a map containing integer values
corresponding to the number of accumulated cells for each cell inside the window map.

Remember that all of them must have THE SAME MAP WINDOW and THE SAME CELL SIZE.
Moreover they must be provided with the XLLCORNER and the YLLCORNER and not with
XLLCENTER and YLLCENTER.
When all the previous maps are provided the Next button will be enabled and the case creation
can be continued.

3.5. EDAPHOLOGY AND TEMPERATURE MAPS

In this step the following maps must be provided:

SOIL TYPE ASCII MAP: The SOIL TYPE is a map containing the integer ID SOIL CLASS value for each
cell inside catchment and NoData outside. Be sure that all the cells inside the catchment
(cells with value 1 in the Basin Mask) have a value different from NoData!

LAND USE ASCII MAP: The LAND USE is a map containing the integer ID LAND USE CLASS value for
each cell inside catchment and NoData outside. Be sure that all the cells inside the
catchment (cells with value 1 in the Basin Mask) have a value different from NoData!

The TOPKAPI-X needs the values of historical mean monthly temperatures to compute the
Potential Evapotranspiration. These values can be provided to the model using Thermometers or
Maps. In the first case, the user must provide the Thermometers Coordinates and the mean
monthly temperatures as described in Section 3.8. In the second case, the maps must be provided
as described below. Remember that the temperature unit of measure must be [°C].

I WANT TO USE MAPS INSTEAD OF GAUGES TO PROVIDE THE MEAN MONTHLY TEMPERATURE
VALUES: This box must be checked only if the user wants to use maps to provide the mean
monthly temperatures, otherwise it must be unchecked and the case creation can continue
clicking on the Next button. If this box is checked one of the following options must be
chosen:

1. I have the monthly temperature maps: This field must be checked if the user wants to
provide the mean monthly temperature maps obtained using an external software. The
software looks for the maps in the Mean Monthly Temperature ASCII MAPS folder. The
maps must be named as MM.asc, where MM is the month number with two digits.

2. I want to create the maps starting from my observed maps: If the mean monthly
temperatures maps are not available, they can be created starting from the historical
observed maps, which can have any temporal time step. The historical maps must be
placed in the Observed Temperatures ASCII MAPS folder and they must be named as
‘yyyyMMddHH.ext’, where ext is the Map File Extension. Moreover, the maps values are
multiplied by the Corrector Factor if the unite of measure is different from °C. The
software uses all the maps included between the Start Date and the End Date with a
prefixed Time Step. (i.e. if the start date is 10/01/1983 00.00 and the time step is 60
minutes, the software looks for the maps 198310010000.ext, 198310010100.ext,
198310010200.ext… until the last date)

Remember that all of them must have THE SAME MAP WINDOW and THE SAME CELL SIZE.
Moreover they must be provided with the XLLCORNER and the YLLCORNER and not with
XLLCENTER and YLLCENTER.
 3.6. SOIL TYPE

In this step the Soil Type Parameters can be provided. Firstly the user can choose the Number of
soil layers and to activate or not the Infiltration Module (Green-Ampt model is active). If the
infiltration module is activated, for each ID the values of Surface Soil Conductivity (Kv) and Suction
Head (Psi) must be provided. If the user decides to use 1 soil layer, only the first table must be
filled with the parameters of each soil ID present inside the catchment area. Otherwise, also the
parameters for the deep soil layer must be provided. Remember that the ID numbers are the
values found in the SOIL TYPE Map previously provided.
The choice of these parameters depends on the case features. The Infiltration Module is useful in
catchments whose behaviour follows the Hortonian mechanism during the dry season. The second
layer is usually very important to correctly reproduce the base flow and the recession curves at the
same time. The response of the deep layer is usually lower and it regulates the base flow during
the wetting up period. The deep layer should have a low hydraulic conductivity and a quite high
depth. When the deep layer gets saturated then the surface layer becomes the main sub-surface
flow generator and it regulates the flood events during the wet period. This layer should have a
faster response than the deep layer, this means that its conductivity should be quite high and its
depth not greater than 50 cm.

In the tables the following parameters for the surface and deep soil layers must be provided for
each Soil Type Class (ID):

SURFACE LAYER SOIL TYPE:

 ID: The soil classes found in the SOIL TYPE maps, this value can be modified only changing
the SOIL TYPE map at the end of the WIZARD procedure.
Ksh: Horizontal soil conductivity [ms-1]
Ksv: Vertical soil conductivity [ms-1] (needed only if 1 soil layer is used)
Depth: Depth of the surface soil layer [m]
Theta S: Saturated soil moisture content [0-1]
Theta R: Residual soil moisture content [0-1]
Exp H: Exponent of the horizontal flow equation
Exp V: Exponent of the percolation law (needed only if 1 soil layer is used)
Name: Name of the soil type class

If the Green-Ampt model is active, also the following parameters must be provided:

Kv: Vertical conductivity at the surface [ms-1]

Psi: Head suction [m]

DEEP LAYER SOIL TYPE:

ID: The soil classes found in the SOIL TYPE map, this value can be modified only changing the
SOIL TYPE map.
Ksh: Horizontal soil conductivity [ms-1]
Ksv: Vertical soil conductivity [ms-1]
Depth: Depth of the surface soil layer [m]
Theta S: Saturated soil moisture content [0-1]
Theta R: Residual soil moisture content [0-1]
Exp H: Exponent of the horizontal flow equation
Exp V: Exponent of the percolation law
Name: Name of the soil type class
 3.7. LAND USE

In this step the Land Use Parameters can be provided. The required parameters can be easily
obtained by the Corinne Land Use Map, which covers most of the world providing the relative land
use characteristics.
Remember that the ID numbers are the values found in the LAND USE Map previously provided.

LAND USE:
ID: The soil classes found in the LAND USE map, this value can be modified only changing the
LAND USE map at the end of the WIZARD procedure.
Manning: Surface Manning coefficient [sm-1/3]
Jan-Dec: The Krop Factor values for each month
Name: The Land Use class name

The Surface Manning coefficient can accelerate or delay the surface flow and the Krop Factors can
increase or decrease the Potential Evapotranspiration. To calibrate these parameters a suggestion
is to use the literature values and to change them only if the soil (Section 3.6) and the Channel
(Section 3.13) parameters calibration is not enough to well reproduce the river behaviour.
 3.8. MEAN MONTHLY TEMPERATURES

This step is needed only if the mean monthly temperatures are provided using thermometers
values and not maps, according to Section 3.5. For each available thermometer, its elevation and
coordinates, the mean monthly temperatures and the name must be provided. The data are then
distributed in space according to the Thiessen Polygons.
The mean monthly temperatures are used by the model to compute the Potential
Evapotranspiration and these data must be provided before continuing the case creation. They are
required during the PRE-PROCESSING to compute the 'alpha' and 'beta' coefficients of the
Doremboos formula.
A thermometer can be manually added providing its coordinates or can be added using the Maps
Visualizer (Section 5.3) clicking on the Add Thermometer From Map button. This can be done
opening and selecting the Filled DEM map and right clicking on the desired point.

In the table the following values must be provided for each available Thermometer (ID):

MEAN MONTHLY TEMPERATURE

ID: Identification Number of the thermometer
Name: Name of the gauge station
X Coordinate: X Coordinate of the thermometer location (Maps Visualizer)
Y Coordinate: Y Coordinate of the thermometer location (Maps Visualizer)
Elevation: Elevation of the thermometer (Maps Visualizer)
Jan-Dec: The mean monthly temperatures recorded by the thermometer
 3.9. DRAINAGE NETWORK

In this step the Drainage Network Parameters must be provided. The fields on left panel must be
filled before continuing the case creation, because they are required for the drainage network
identification. In the following steps the parameters for each Strahler Order, automatically
identified by the PRE-PROCESSOR on the basis of the parameters required in this step, shall be
provided.
The first parameter required to generate the Channel Network is the Threshold Area, this is the
minimum area [km2] that a cell must drain to have the channel component. If this parameter is
lower or equal than the cell size then all the cells will have the channel component. In order to
choose an adequate threshold area, the user should consider that the lower the threshold area is,
the slower the catchment response and the lower the base flow are. On the other hand, the
greater the threshold area is, the faster the catchment response and the greater the base flow.
The channel width is computed according to a linear variation between the basin outlet and the
first cell of each channel reach. For this reason the Max Channel Width is the width of the channel
at the outlets and the Min Channel Width is the channel width at the first cell of each channel
reach (i.e. cells with number of accumulated cells correspondent to the threshold area).
In the TOPKAPI-X the channel component is solved using the kinematic wave or the Muskingum-
Cunge-Todini methods. The former is used when the cell slope is higher than the Slope threshold
for MKT parameter and the latter otherwise. A common value of this parameter is 10-3.
 3.10. PERCOLATION AND GROUNDWATER
GROUNDWATER component is available only in the PROFESSIONAL VERSION

In the TOPKAPI-X the percolation from the soil component to the groundwater can be taken into
account checking the PERCOLATION IS ACTIVE option. If the percolation component is activated,
the water flowing towards the groundwater does not contribute to the flood simulation, but it can
be used to represent the groundwater balance selecting the Groundwater option. If the
groundwater component is activated also points of water withdrawal can be provided. Otherwise,
if the Water Loss option is checked the percolation is taken into account as a simple loss of water
from the soil.

The groundwater is represented by a saturated and a non-saturated zone. The percolation from
the soil flows to the non-saturated zone which recharges the saturated zone using a percolation
law functional on the groundwater soil moisture, the groundwater soil conductivity and the
vertical exponent (Exp V).
The horizontal flow direction is identified at each time step according to the hydraulic gradient
and the flow quantity depends on the groundwater soil moisture, the groundwater soil
conductivity and the hydraulic gradient itself.
On the boundary the groundwater level is assumed to be constant.

In order to activate the groundwater component the map of the groundwater bottom must be
provided. This map contains the level of the groundwater bottom in [m]. When this map is loaded
also the Groundwater Soil Type Map must be provided. This map is similar to the SOIL TYPE map
used to represent the soil component and for each soil type class (ID) the following parameters
are required:

GROUNDWATER
ID: The soil classes found in the GROUNDWATER SOIL TYPE map, this value can be modified
only loading a new map.
Ks: groundwater soil conductivity [ms-1]
Depth: Depth of the groundwater [m]
Theta S: Saturated soil moisture content [0-1]
Theta R: Residual soil moisture content [0-1]
Exp H: Exponent of the vertical flow equation
Name: Name of the groundwater soil type class

If some withdrawal points are present inside the basin area, they can be added using the Maps
Visualizer (see Section 5.3) after adding and selecting the Groundwater Bottom Map and right
clicking on the desired point. The withdrawals are taken into account in the groundwater balance
as a water loss from the cell where the withdrawal is placed. The withdrawals data must be
provided for each point added to the configuration using a CSV file, which path is the Data File.
The NoData value must be specified in the Null Value field. The first column of this file contains
the dates (with format ‘dd/MM/yyyy hh.mm’) and the other columns contain the corresponding
withdrawal data for each point added to the configuration. The CSV file must have a header which
contains the point ID for each column, as shown in the following figure.

The withdrawal table must be filled with the following values:

WITHDRAWALS:
ID: Withdrawal point ID used in the CSV file to identify the column with the corresponding
data
Name: Name of the withdrawal point
X Coordinate: X coordinate of the withdrawal point location (Maps Visualizer)
Y Coordinate: Y coordinate of the withdrawal point location (Maps Visualizer)
Raster: Raster number of the cell where the withdrawal is located (Maps Visualizer)
 3.11. SNOW MELTING/ACCUMULATION AND EVAPOTRANSPIRATION

In this step the parameters concerning the Evapotranspiration and the Snow
Melting/Accumulation modules are required.
The Evapotranspiration module can be activated checking the EVAPOTRANSPIRATION is active
option. If this module is activated and the Computed from Temperature option is checked the
TOPKAPI-X computes the actual evapotranspiration as a function of the air temperature and the
soil water content, or allows the potential evapotranspiration (ETP) to be provided as observed
value if the Observed option is checked. In the first case, the historical Monthly ETP values are
computed according to Thornthwaite and Mather (1955) using the mean monthly temperature
values previously provided. Then, through the Doorembos (1984) formula, the ETP is computed for
each simulation time step. The Actual Evapotranspiration (ETA) is then computed on the basis of
the soil water content and the Beta parameters. If the water content is lower than Beta Min, then
the ETA is null. If the water content is greater than Beta Max, then ETA is equal to ETP. In the
other cases, ETA is equal to ETP multiplied by the water content value.
If the ETP will be provided as observed value, the data type and the relative files will be asked at
the end of the WIZARD procedure in the main form (see Sections 4.12 and 4.13).

The Snow Melting and Accumulation module can be activated checking the SNOW
MELTING/ACCUMULATION is active option. If this module is activated The TOPKAPI-X computes
the Snow Melting and Accumulation through an energy balance based on the percentage of solid
and liquid precipitation. The part of solid precipitation is computed on the basis of the
temperature value applying an exponential distribution equation with mean value equal to the
Melting Temperature value. This means that if the air temperature is equal to the Melting
Temperature the precipitation will be half solid and half liquid. The available energy to melt the
snow is computed on the basis of the Potential Evapotranspiration value, multiplied by an albedo
coefficient and a radiation efficiency coefficient functional on the height of the sun with respect to
the cell slope and aspect. For this reason an approximate value of the basin Latitude and
Longitude must be provided. Moreover, if the data used to feed the model are not on local time
the shift between the data time and the local time must be provided in the Shift to Local Time
field.

3.12. LAKES/RESERVOIRS
LAKES/RESERVOIRS component is available only in the PROFESSIONAL VERSION

The TOPKAPI-X has an internal reservoir management module. If some lakes or reservoirs are
present inside the catchment area this module can be activated checking the LAKES/RESERVOIRS
COMPONENT is active option and the lake map must be provided clicking on the Load Map
button. This map contains the integer Lake ID value for each cell inside the corresponding lake and
NoData values outside the lakes.
The lake balance is computed with a time step different from the one of the simulation, this value
must be provided in the Lake Time Step field.

For each lake or reservoir in the Lake Map the following parameters are required:

LAKES/RESERVOIRS
 Lake ID: The lake ID found in the LAKE map, this value can be modified only loading a new
LAKE map.
Name: Name of the lake
Initial Volume: Water volume in the lake when the simulation starts [m3]
Min Outflow: Minimum discharge that must flow out the lake [m3s-1]
Raster: Raster number of the outlet cell (Maps Visualizer)
Observed Data: Check this option if observed data are available for the lake
Activated: Check this option if the lake must be taken into account in the simulation

The lakes/reservoirs features must be described using the following files.

INPUT FILES:
The Discharge – Level - Volume Curves are CSV files with header, where the first column
contains the LAKE ID, while the second and the third columns contain the required variables
as described below.

Discharge – Level - Volume Curves

Volume – Level File: The first column contains the Volume in [m3] and the second one
the Level in [m]
Level – Max Discharge File: The first column contains the Level in [m] and the second
one the Maximum Discharge that can flow out the reservoir in [m3s-1]
Level – Discharge File: The first column contains the Level in [m] and the second one
the Discharge [m3s-1] that flows out the reservoir depending on the management
rules

The Observed Data files are in CSV format with header. The first column contains the date
(with format ‘dd/MM/yyyy HH.mm’) and the other columns contain the observed Outflow
Discharge in [m3s-1] or Lake Level in [m] for each time step. Each column corresponds to the
lake identified by the ID in the header. The NoData value must be specified in the Null Value
field.

Clicking on the Next button the PRE-PROCESSING starts, at the end of its execution the LOG FILE
window is open. If the PRE_TOPKAPI-X software ends correctly then the case creation can be
continued after closing the log file window. If some errors occur, then come back to check the
errors reported in the log file and run again the pre processor clicking on the Next button in the
Lake step.
 3.13. CHANNELS

After running the pre processing the channel network has been created and the channel reaches
have been classified on the basis of their Strahler Order. The channel map can be visualized
through the Maps Visualizer tool.
For each Strahler Order the following parameters must be provided:

CHANNELS
Strahler Orders: The Strahler Order automatically generated by the PRE-PROCESSOR. This
value can be modified only at the end of the WIZARD procedure changing the
Drainage Network parameters and generating again the channel network. Moreover,
at the end of the WIZARD procedure, in the main form, the user can add reaches with
specific parameters (see Section 4.7)
Manning Coefficient: The Manning coefficient of the channel riverbed
Angle: Tangent of the angle of the riverbed sides (only for Triangular sections)
Max Discharge: Maximum Discharge that can flow through the section, usually a high value
is used.
Section Type: Type of riverbed section
 3.14. INFLOWS/OUTFLOWS AND DISTRIBUTED CONTRIBUTES
INFLOWS/OUTFLOWS and DISTRIBUTED CONTRIBUTES components are available only in the PROFESSIONAL VERSION

Inflow/Outflow Data are observed discharge or additional inflow or outflow, which can be
provided to the model in order to take them into account. If the Inflow/Outflow type is Observed
Discharge then the discharge computed by the model is replaced by the value read in the Data
File. Otherwise, if the Inflow/Outflow type is Observed Withdrawal the value read in the Data File
is added to the discharge computed by the model (positive values represent inflows and negative
values represent outflows).
The Inflow/Outflow component can be activated checking the INFLOW COMPONENT is active
option.
The Inflow/Outflow Points can be added only using the Maps Visualizer tool, clicking on the ADD
INFLOW/DISTRIBUTED CONTRIBUTE POINTS FROM MAP button. These points can be added
selecting the Strahler Orders Map and right clicking on the cell where the point should be added.

For each Inflow/Outflow point the following information must be provided:

INFLOW
Inflow ID: Inflow/Outflow point ID used in the Data File to identify the column with the
corresponding data
Inflow Name: Inflow/Outflow Name
X Coordinate: X coordinate of the point location (Maps Visualizer)
Y Coordinate: Y coordinate of the point location (Maps Visualizer)
 Raster: Raster number of the cell where the Inflow/Outflow is located (Maps Visualizer)
Inflow Type: Observed Discharge or Observed Withdrawal as previously described

The Inflow/Outflow data must be provided to the model through a CSV file, which path is specified
in the Data File field. The NoData value must be specified in the Null Value field. The first column
of this file contains the dates (with format ‘dd/MM/yyyy hh.mm’) and the other columns the
corresponding inflow/outflow data for each point added to the configuration. The CSV file must
have a header which contains the point ID for each column, as shown in the following figure.

A Distributed Contribute is the water discharge that laterally flows into a reach channel. This value
is used to connect the Hydrological Model to a Hydraulic Model providing this quantity as
distribute flow. This component can be activated checking the DISTRIBUTED CONTRIBUTES
COMPONENT is active option.
A distributed contribute requires two points, which identify the channel reach whose laterally flow
is computed. These reaches can be selected using the Maps Visualizer tool adding and selecting
the Strahler Order Map. Right clicking on a point of the map a context menu appears and the
channel reach can be selected by clicking on the items Add Distributed Contribute –
Upstream/Downstream.
If this component is activated an output file is printed in the Output Folder, this file is named
‘Distributed_Contributes.out’. This file is in CSV format, the first column contains the date
and the other columns the distributed contribute for the reach identified by the ID in the file
header. Each value represents the sum of the lateral flows to each cell that belongs to the channel
reach.

DISTRIBUTED CONTRIBUTES
Reach ID: The reach ID used in the output file ‘Distributed_Contributes.out’ to identify
the channel reach
Reach Name: The name of the channel reach
Upstream Raster: Raster Number of the upstream cell of the reach (Maps Visualizer)
Downstream Raster: Raster Number of the downstream cell of the reach (Maps Visualizer)
 3.15. CONTROL POINTS

The Control Points are points that belong to the channel network where information about the
simulation can be printed. If the Print Output box is checked a file named 'Section name'.out
will be printed in the Output Folder. This file contains, for each time step of the simulation, the
observed and simulated discharge, the mean values of Precipitation, Temperature, Soil Moisture,
ETA, ETP, Snow Water Equivalent, and others, computed on the sub-basin generated by the
control point.
Remember that the Basin Outlets are Control Points with the Print Output option checked and this
setting cannot be changed.
The Control Points must be added clicking on the Add Control Point From Map button and using
the Maps Visualizer tool, adding and selecting the Strahler Orders Map. Right clicking on a point in
the map a context menu appears and the Control Point can be added clicking on the Add Control
Point item.
For each Control Point the Section ID and the Section Name must be added and the Print Output
option must be checked if the user wants to be able to view the output using the Simulation
Visualizer (see Section 5.2). Moreover, using this tool the user can extract the simulation output in
CSV format.

CONTROL POINTS
Section ID: ID of the Control Point
Section Name: Name of the Control Point that is used as the output file name
X Coordinate: X coordinate of the control point location (Maps Visualizer)
Y Coordinate: Y coordinate of the control point location (Maps Visualizer)
 Raster: Raster Number of the cell where the Control Point is located (Maps Visualizer)
Print Output: Check this option if the output file must be printed

This is the last step of the case creation, clicking on the End button the main form will open (see
Section 4).
4. OPEN AN EXISTING CASE

In this section the main form of TOPKAPI-X will be described. This form contains all the
information about the case and allows it to be simulated. This form appears opening an existing
case or at the end of a case creation.

4.1. GLOBAL CONTROLS

File menu items

New: Come back to the Startup Form to create a new case; if the current configuration has
not been saved, the changes will be lost
Open: Open an existing case; if the current configuration has not been saved, the changes
will be lost.
Save: Save the current case
Delete Current Case: Delete the current case, any subfolder and any file inside the working
directory
Save Configuration: Create a copy of the current configuration (.tcop file) that can be
loaded at any time
Load Configuration: Load a configuration (.tcop file) previously saved; if the current
configuration has not been saved, the changes will be lost
Exit: Exit the program; if the current configuration has not been saved, the changes will be
lost

Tools menu items

Compute Evaluation Indexes: Open the Evaluation Indexes tool (see Section 5.1)
Simulation Visualizer: Open the Simulation Visualizer tool (see Section 5.2)
Maps Visualizer: Open the Maps Visualizer tool (see Section 5.3)
Compare Simulations: Open the Compare Simulations tool (see Section 5.4)

In order to run a simulation the user must provide a folder where the simulation states are saved.
The state folders can be created writing its name in the textbox below the STATE FOLDER field and
clicking on the Add button, the prefix ‘ST_’ will be automatically added in order to identify the
state folders when the case will be opened again. If an existing state folder is used when running a
simulation, the existing states will be overwritten if a new state is saved at the same date. The
states can be managed through the Simulation tab as described in Section 4.14.
Moreover, the user must choose an OUTPUT FOLDER, which can be created following the same
procedure described for the state folders. In this case, the prefix ‘OUT_’ will be automatically
added. When running a simulation the selected output folder will be deleted and a confirmation
message will be shown in order to avoid undesirable data losses. During the simulation the current
configuration is saved inside the selected output folder in a .tcop file, this configuration can be
loaded at any time selecting the desired output folder and clicking on the Load the configuration
of the selected output folder button. Remember that when a saved configuration is loaded, if the
current configuration has not been saved the changes will be lost.
 4.2. GENERAL

The first tab page contains the following GENERAL SETTINGS about the case:

GENERAL:
Working directory: is the directory where all the files needed by the software to simulate
the case are located
Delimiter: Is the list separator set in the international setting of the Operating System
Platform: This version of the TOPKAPI-X Visual Interface only runs on WINDOWS OS but the
model can be executed also on LINUX OS. This option allows to create the case using
the visual interface under WINDOWS and then to run the TOPKAPI-X model under
LINUX OS after copying the entire working directory, using a batch file automatically
generated (This option is not implemented in the Versions 1.0 and 1.1)

MAP WINDOW DATA: This group contains information about the window of the case maps. The
Rows Number, Columns Number, Cell Size, Xll Corner, Yll Corner and Number of Cells
values are read from the input maps and they cannot be modified. In this group the
user must only provide approximated values of the Latitude and Longitude of the
basin. These values are used by the Snow Melting/Accumulation module to compute
the sun height and inclination with respect to the cell aspect.

INITIAL STATE: when running a simulation the user can choose an existing initial state previously
saved or can start the simulation with an average initial state. The average initial state
can be defined on the basis of the simulation start month using the mean values of Soil
Moisture, Channel Level and Groundwater Moisture (if the Groundwater component
is activated) provided in this table.
 4.3. MONTHLY TEMPERATURE

This tab page is enabled only if the mean monthly temperatures are provided using thermometers
values and not maps, according to Section 3.5. For each available thermometer, its elevation and
coordinates, the mean monthly temperatures and the name must be provided. The data are then
distributed in space according to the Thiessen Polygons.
The mean monthly temperatures are used by the model to compute the Potential
Evapotranspiration; in fact they are required during the PRE-PROCESSING to compute the 'alpha'
and 'beta' coefficients of the Doremboos formula.
A thermometer can be manually added providing its coordinates or can be added using the Maps
Visualizer (Section 5.3) clicking on the Add Thermometer From Map button. This can be done
opening and selecting the Filled DEM map and right clicking on the desired point.

In the table the following values must be provided for each available Thermometer (ID):

MEAN MONTHLY TEMPERATURE

ID: Identification Number of the thermometer
Name: Name of the gauge station
X Coordinate: X Coordinate of the thermometer location (Maps Visualizer)
Y Coordinate: Y Coordinate of the thermometer location (Maps Visualizer)
Elevation: Elevation of the thermometer (Maps Visualizer)
Jan-Dec: The mean monthly temperatures recorded by the thermometer
 4.4. SOIL TYPE

In this tab page the Soil Type Parameters must be provided. Firstly the user can choose the
Number of soil layers and to activate or not the Infiltration Module (Green-Ampt model is active).
If the infiltration module is activated, the values of Surface Soil Conductivity (Kv) and Suction Head
(Psi) must be provided for each ID. If 1 soil layer is chosen, only the first table must be filled with
the parameters of each soil ID present inside the catchment area. Otherwise, also the parameters
for the deep soil layer must be provided. Remember that the ID numbers are the values found in
the SOIL TYPE Map previously provided. The SOIL TYPE map can be changed at any time by clicking
on the Load Map button and it can be visualized clicking on the View Map button.
The choice of these parameters depends on the case features. The Infiltration Module is useful in
catchments whose behaviour follows the Hortonian mechanism during the dry season. The second
layer is usually very important to correctly reproduce the base flow and the recession curved at
the same time. The response of the deep layer is usually lower and it regulates the base flow
during the wetting up period. The deep layer should have a low hydraulic conductivity and a quite
high depth. When the deep layer gets saturated then the surface layer becomes the main sub-
surface flow generator and it regulates the flood events during the wet period. This layer should
have a faster response than the deep layer; its conductivity should be quite high and its depth not
greater than 50 cm.

In the tables the following parameters for the surface and deep soil layers must be provided for
each Soil Type Class (ID):

SURFACE LAYER SOIL TYPE:

ID: The soil classes found in the SOIL TYPE maps, this value can be modified only changing
the SOIL TYPE map clicking on the Load Map button
Ksh: Horizontal soil conductivity [ms-1]
Ksv: Vertical soil conductivity [ms-1] (needed only if 1 soil layer is used)
 Depth: Depth of the surface soil layer [m]
Theta S: Saturated soil moisture content [0-1]
Theta R: Residual soil moisture content [0-1]
Exp H: Exponent of the horizontal flow equation
Exp V: Exponent of the percolation law (needed only if 1 soil layer is used)
Name: Name of the soil type class

If the Green-Ampt model is active, also the following parameters must be provided:

Kv: Vertical conductivity at the surface [ms-1]

Psi: Head suction [m]

DEEP LAYER SOIL TYPE:

ID: The soil classes found in the SOIL TYPE map, this value can be modified only changing the
SOIL TYPE map.
Ksh: Horizontal soil conductivity [ms-1]
Ksv: Vertical soil conductivity [ms-1]
Depth: Depth of the surface soil layer [m]
Theta S: Saturated soil moisture content [0-1]
Theta R: Residual soil moisture content [0-1]
Exp H: Exponent of the horizontal flow equation
Exp V: Exponent of the percolation law
Name: Name of the soil type class

4.5. LAND USE

In this tab page the Land Use Parameters must be provided. The required parameters can be easily
obtained by the Corinne Land Use Map, which covers most of the world providing the relative land
use characteristics.
Remember that the ID numbers are the values found in the LAND USE Map previously provided.
This map can be changed clicking on the Load Map button and it can be visualized clicking on the
View Map button.

LAND USE:
ID: The soil classes found in the LAND USE map, this value can be modified only changing the
LAND USE map clicking on the Load Map button
Manning: Surface Manning coefficient [sm-1/3]
Jan-Dec: The Krop Factor values for each month
Name: The Land Use class name

The TOPKAPI-X is not really sensitive to these parameters. The Surface Manning coefficient can
accelerate or delay the surface flow and the Krop Factors can increase or decrease the Potential
Evapotranspiration. To calibrate these parameters a suggestion is to use the literature values and
to change them only if the soil (Section 3.6) and the Channel (Section 3.13) parameters calibration
is not enough to well reproduce the river behaviour.

4.6. LAKES/RESERVOIRS
LAKES/RESERVOIRS component is available only in the PROFESSIONAL VERSION

The TOPKAPI-X has an internal reservoir management module. If some lakes or reservoirs are
present inside the catchment area this module can be activated checking the LAKES/RESERVOIRS
COMPONENT is active box and the lake map must be provided clicking on the Load Map button.
This map contains the integer Lake ID value for each cell inside the corresponding lake and NoData
values outside the lakes.
The lake balance is computed with a time step different from the one of the simulation, this value
must be provided in the Lake Time Step field; usually a time step of 1 minute is used.

For each lake or reservoir in the Lake Map the following parameters are required:

LAKES/RESERVOIRS
Lake ID: The lake ID found in the LAKE map, this value can be modified only loading a new
LAKE map.
Name: Name of the lake
Initial Volume: Water volume in the lake when the simulation starts [m3]
Min Outflow: Minimum discharge that must flow out the lake [m3s-1]
Raster: Raster number of the outlet cell (Maps Visualizer)
Observed Data: Check this option if observed data are available for the lake
Activated: Check this option if the lake must be taken into account in the simulation

The lakes/reservoirs features must be described using the following files.

INPUT FILES:
The Discharge – Level - Volume Curves are CSV files with header, where the first column
contains the LAKE ID, while the second and the third columns contain the required variables
as described below.

Discharge – Level - Volume Curves

Volume – Level File: The first column contains the Volume in [m3] and the second one
the Level in [m]
Level – Max Discharge File: The first column contains the Level in [m] and the second
one the Maximum Discharge that can flow out the reservoir in [m3s-1]
Level – Discharge File: The first column contains the Level in [m] and the second one
the Discharge [m3s-1] that flows out the reservoir functional on the management
rules

The Observed Data files are in CSV format with header. The first column contains the date
(with format ‘dd/MM/yyyy HH.mm’) and the other columns contain the observed Outflow
Discharge in [m3s-1] or Lake Level in [m] for each time step. Each column correspond the
lake identified by the ID in the header. The NoData value must be specified in the Null Value
field.
 4.7. CHANNELS

In this tab page the Drainage Network Parameters must be provided. The first parameter required
to generate the Channel Network is the Threshold Area, this is the minimum area [km2] that a cell
must drain to have the channel component. If this parameter is lower or equal than the cell size
then all the cells will have the channel component. In order to choose an adequate threshold area,
the user has to consider that the lower the threshold area is, the slower the catchment response
and the lower the base flow. On the other hand, the greater the threshold area is, the faster the
catchment response and the greater the base flow.
The channel width is computed according to a linear variation between the basin outlet and the
first cell of each channel reach. For this reason the Max Channel Width is the width of the channel
at the outlets and the Min Channel Width is the channel width at the first cell of each channel
reach (i.e. cells with number of accumulated cells correspondent to the threshold area).
In the TOPKAPI-X the channel component is solved using the kinematic wave or the Muskingum-
Cunge-Todini methods. The former is used when the cell slope is higher than the Slope threshold
for MKT parameter and the latter otherwise. A common value of this parameter is 10-3.

If the Drainage Network parameters are changed the drainage network will consequently change
and different Strahler Orders can be obtained. For this reason, to make effective the changes
regarding the channel network parameters it is necessary to run the TOPKAPI-X pre processing
clicking on the Apply Changes button.

After running the pre processing the channel network is created and the channel reaches have
been classified on the basis of their Strahler Order. The channel map can be visualized through the
Maps Visualizer tool or clicking on the View Map button.
For each Strahler Order the following parameters must be provided:

CHANNELS
 Strahler Orders: The Strahler Order automatically generated by the PRE-PROCESSOR. This
value can be modified only at the end of the WIZARD procedure changing the
Drainage Network parameters and generating again the channel network. Moreover,
at the end of the WIZARD procedure, in the main form, the user can add reaches with
specific parameters (see Section 4.7)
Manning Coefficient: The Manning coefficient of the channel riverbed
Angle: Tangent of the angle of the riverbed sides (only for Triangular sections)
Max Discharge: Maximum Discharge that can flow through the section, usually a high value
is used.
Section Type: Type of riverbed section

Sometimes the channel classification on the basis of the Strahler orders may be not satisfactory,
due to specific characteristics of some channel reach. For this reason it is possible to add some
Custom Reaches if needed. The custom reaches are identified by the raster values of the first and
last cells of the channel reach and different parameters will be assigned to all the cells included
between them. These parameters must be provided in the CUSTOM REACHES table. This table is
equal to the CHANNELS one apart from two new fields that contain the raster number of the first
and last cells of the reach.

The custom reaches can be only added through the Maps Visualizer, adding and selecting the
Strahler Order map and right clicking on the cell where the point should be added. Clicking on the
Add Custom Reach from Map button, the Maps Visualizer will be opened and the Strahler Order
Map will be added and selected.

4.8. INFLOWS AND DISTRIBUTED CONTRIBUTES

INFLOWS/OUTFLOWS and DISTRIBUTED CONTRIBUTES components are available only in the PROFESSIONAL VERSION
Inflow/Outflow Data are observed discharge or additional inflow or outflow, which can be
provided to the model in order to take them into account. If the Inflow/Outflow type is Observed
Discharge then the discharge computed by the model is replaced by the value read in the Data
File. Otherwise, if the Inflow/Outflow type is Observed Withdrawal the value read in the Data File
is added to the discharge computed by the model (positive values represent inflows and negative
values represent outflows).
The Inflow/Outflow component can be activated checking the INFLOW COMPONENT is active
option.
The Inflow/Outflow Points can be added only using the Maps Visualizer tool, clicking on the ADD
INFLOW/DISTRIBUTED CONTRIBUTE POINTS FROM MAP button. These points can be added
selecting the Strahler Orders Map and right clicking on the cell where the point should be added.

For each Inflow/Outflow point the following information must be provided:

INFLOW
Inflow ID: Inflow/Outflow point ID used in the Data File to identify the column with the
corresponding data
Inflow Name: Inflow/Outflow Name
X Coordinate: X coordinate of the point location (Maps Visualizer)
Y Coordinate: Y coordinate of the point location (Maps Visualizer)
Raster: Raster number of the cell where the Inflow/Outflow is located (Maps Visualizer)
Inflow Type: Observed Discharge or Observed Withdrawal as previously described

The Inflow/Outflow data must be provided to the model through a CSV file, which path is specified
in the Data File field. The NoData value must be specified in the Null Value field. The first column
of this file contains the dates (with format ‘dd/MM/yyyy hh.mm’) and the other columns the
corresponding inflow/outflow data for each point added to the configuration. The CSV file must
have a header which contains the point ID for each column, as shown in the following figure.

A Distributed Contribute is the water discharge that laterally flows into a reach channel. This value
is used to connect the Hydrological Model to a Hydraulic Model providing this quantity as
distribute flow. This component can be activated checking the DISTRIBUTED CONTRIBUTES
COMPONENT is active box.
A distributed contribute requires two points, which identify the channel reach whose laterally flow
is computed. These reaches can be selected using the Maps Visualizer tool adding and selecting
the Strahler Order Map. Right clicking on a point of the map a context menu appears and the
channel reach can be selected by clicking on the items Add Distributed Contribute –
Upstream/Downstream.
If this component is activated an output file is printed in the Output Folder, this file is named
‘Distributed_Contributes.out’. This file is in CSV format, the first column contains the date
and the other columns the distributed contribute for the reach identified by the ID in the file
header. Each value represents the sum of the lateral flows to each cell that belongs to the channel
reach.

DISTRIBUTED CONTRIBUTES
Reach ID: The reach ID used in the output file ‘Distributed_Contributes.out’ to identify
the channel reach
Reach Name: The name of the channel reach
Upstream Raster: Raster Number of the upstream cell of the reach (Maps Visualizer)
Downstream Raster: Raster Number of the downstream cell of the reach (Maps Visualizer)

4.9. PERCOLATION AND GROUNDWATER

GROUNDWATER component is available only in the PROFESSIONAL VERSION

In the TOPKAPI-X the percolation from the soil component to the groundwater can be taken into
account checking the PERCOLATION IS ACTIVE box. If the percolation component is activated, the
water flowing towards the groundwater does not contribute to the flood simulation, but it can be
used to represent the groundwater balance selecting the Groundwater option. If the groundwater
component is activated also points of water withdrawal can be provided. Otherwise, if the Water
Loss option is checked the percolation is taken into account as a simple loss of water from the soil.
The groundwater is represented by a saturated and a non-saturated zone. The percolation from
the soil flows to the non-saturated zone which recharges the saturated zone using a percolation
law functional on the groundwater soil moisture, the groundwater soil conductivity and the
vertical exponent (Exp V).
The horizontal flow direction is identified at each time step according to the hydraulic gradient
and the flow quantity depends on the groundwater soil moisture, the groundwater soil
conductivity and the hydraulic gradient itself.
On the boundary the groundwater level is assumed to be constant.

In order to activate the groundwater component the map of the groundwater bottom must be
provided. This map contains the level of the groundwater bottom in [m]. When this map is loaded
also the Groundwater Soil Type Map must be provided. This map is similar to the SOIL TYPE map
used to represent the soil component and for each soil type class (ID) the following parameters
are required:

GROUNDWATER
ID: The soil classes found in the GROUNDWATER SOIL TYPE map, this value can be modified
only loading a new map.
Ks: groundwater soil conductivity [ms-1]
Depth: Depth of the groundwater [m]
Theta S: Saturated soil moisture content [0-1]
Theta R: Residual soil moisture content [0-1]
Exp H: Exponent of the vertical flow equation
Name: Name of the groundwater soil type class

If some withdrawal points are present inside the basin area, they can be added using the Maps
Visualizer (Section 5.3) after adding and selecting the Groundwater Bottom Map and right clicking
on the desired point. The withdrawals are taken into account in the groundwater balance as a
water loss from the cell where the withdrawal is placed. The withdrawals data must be provided
for each point added to the configuration using a CSV file, which path is the Data File. The NoData
value must be specified in the Null Value field. The first column of this file contains the dates (with
format ‘dd/MM/yyyy hh.mm’) and the other columns the corresponding withdrawal data for each
point added to the configuration. The CSV file must have a header which contains the point ID for
each column, as shown in the following figure.
The withdrawal table must be filled with the following values:
WITHDRAWALS:
ID: Withdrawal point ID used in the CSV file to identify the column with the corresponding
data
Name: Name of the withdrawal point
X Coordinate: X coordinate of the withdrawal point location (Maps Visualizer)
Y Coordinate: Y coordinate of the withdrawal point location (Maps Visualizer)
Raster: Raster number of the cell where the withdrawal is located (Maps Visualizer)

4.10. SNOW MELTING/ACUMULATION AND EVAPOTRANSPIRATION

In this tab page the parameters concerning the Evapotranspiration and the Snow
Melting/Accumulation modules are required.
The Evapotranspiration module can be activated checking the EVAPOTRANSPIRATION is active
box. If this module is activated and the Computed from Temperature option is checked the
TOPKAPI-X computes the actual evapotranspiration as a function of the air temperature and the
soil water content, or allows the potential evapotranspiration (ETP) to be provided as observed
value if the Observed option is checked. In the first case, the historical Monthly ETP values are
computed according to Thornthwaite and Mather (1955) using the mean monthly temperature
values previously provided. Then, through the Doorembos (1984) formula, the ETP is computed for
each simulation time step. The Actual Evapotranspiration (ETA) is then computed on the basis of
the soil water content and the Beta parameters. If the water content is lower than Beta Min, then
the ETA is null. If the water content is greater than Beta Max, then ETA is equal to ETP. In the
other cases, ETA is equal to ETP multiplied by the water content value.
If the ETP will be provided as observed value, the data type and the relative files will be asked at
the end of the WIZARD procedure in the main form (Sections 4.12 and 4.13).
The Snow Melting and Accumulation module can be activated checking the SNOW
MELTING/ACCUMULATION is active option. If this module is activated The TOPKAPI-X computes
the Snow Melting and Accumulation through an energy balance based on the percentage of solid
and liquid precipitation. The part of solid precipitation is computed on the basis of the
temperature value applying an exponential distribution equation with mean value equal to the
Melting Temperature. This means that if the air temperature is equal to the Melting Temperature
the precipitation will be half solid and half liquid. The available energy to melt the snow is
computed on the basis of the Potential Evapotranspiration value, multiplied by an albedo
coefficient and a radiation efficiency coefficient functional on the height of the sun with respect to
the cell slope and aspect. For this reason an approximate value of the basin Latitude and
Longitude must be provided. Moreover, if the data used to feed the model are not on local time
the shift between data time and local time must be provided in the Shift to Local Time field.

4.11. CONTROL POINTS

The Control Points are points that belong to the channel network where information about the
simulation can be printed. If the Print Output box is checked a file named 'Section name'.out
will be printed in the Output Folder. This file contains, for each time step of the simulation, the
observed and simulated discharge, the mean values of Precipitation, Temperature, Soil Moisture,
ETA, ETP, Snow Water Equivalent, and others, computed on the sub-basin generated by the
control point.
Remember that the Basin Outlets are Control Points with the Print Output option checked and this
setting cannot be changed.
The Control Points must be added clicking on the Add Control Point From Map button and using
the Maps Visualizer tool, adding and selecting the Strahler Orders Map. Right clicking on a point in
the map a context menu appears and the Control Point can be added clicking on the Add Control
Point item.
For each Control Point the Section ID and the Section Name must be added and the Print Output
option must be checked if the user wants to be able to view the output using the Simulation
Visualizer (see Section 5.2). Moreover, using this tool the user can extract the simulation output in
CSV format.

CONTROL POINTS
Section ID: ID of the Control Point
Section Name: Name of the Control Point that is used as the output file name
X Coordinate: X coordinate of the control point location (Maps Visualizer)
Y Coordinate: Y coordinate of the control point location (Maps Visualizer)
Raster: Raster Number of the cell where the Control Point is located (Maps Visualizer)
Print Output: Check this option if the output file must be printed

4.12. INPUT DATA

In this tab page all the input data for historical simulations must be provided. First of all the user
must select, for each kind of data (precipitation, temperature and evapotranspiration), the DATA
TYPE. The input data can be provided as Maps or Gauges.
In the first case, the corresponding panel on the left side will be enabled and it must be filled with
the Folder Path where the maps are located, the Extension of the map files and the Corrector
Factor, which is used by the model to multiply the values found inside the map files. The maps
must be provided with ASCII format, all the maps must have the same header (same number of
rows and columns, xllcorner, yllcorner, cell size and NoData) and the name of the files must be the
date with format ‘yyyyMMddHHmm.ext’, where ‘ext’ must correspond to the Extension.
Inside each MAPS panel a button allows the user to visualize the maps. After clicking on the
button the maps will be loaded in the Maps Visualizer after providing the visualization period and
the time step. Remember that a maximum of 72 maps can be loaded at the same time in the Maps
Visualizer. Moreover, remember that if the maps folder contains a big amount of files the Maps
Visualizer can take several minutes to open, especially the first time the maps are loaded.
If the data are provided as Gauges, the corresponding panel on the right side of the page will be
enabled and the Coordinates File, Data File and Null Value must be provided. The Coordinates
File is a CSV file with header containing for each gauge a row with the following columns:
CODE: the code used to identify the gauge in the Data File;
Name: the gauge name;
X: the X coordinate of the gauge;
Y: the Y coordinate of the gauge;
Z: the elevation of the gauge.
In the following figure an example of Coordinates File is depicted.

The Data File is a CSV file with header containing all the gauge data. The first column must contain
the dates (with format ‘dd/MM/yyyy hh.mm’) and the other columns the corresponding observed
data for each available gauge. The CSV file must have a header which contains the gauge CODE
(see the Coordinates File) for each column, as shown in the following figure.

In order to compare the simulated discharge values with the observed ones, in the lower right
panel (Discharge) the file containing the observed discharges can be provided. The discharge Data
File has the same features of the previous files, but the gauge CODE in the header must
correspond to the Section ID provided in the Control Points tab page.
Inside each GAUGES panel a button allows the user to visualize the data series. After clicking on
the button the data will be loaded in the Graph Visualizer. Remember that if the file contains a big
amount of data the Graph Visualizer can take some minutes to open, especially the first time the
data are loaded.

4.13. FORECAST

In this tab page all the input data for real time forecasting must be provided. If Real Time
Forecasting is chosen instead of Historical Simulation in the Simulation tab page, also the
forecasted input data must be provided. In this case only maps can be used and not gauges data.
To fill the fields of this tab page please refer to the section regarding the Input Data tab page.
 4.14. SIMULATION

In this tab page all the information regarding the simulation type must be provided before running
the model. Firstly, the user must choose between Historical Simulation and Real Time
Forecasting. If the first option is chosen the model will run using the historical observed input data
(provided in the Input Data tab page) between the Start Date and the End Date selected inside
the SIMULATION DATES panel. If the second option is chosen, the user must provide the forecast
Start Date and the Forecast Length, the model will search for an initial state upon one month
before the Start Date and from that date it will start the simulation using the historical input data
until the Start Date. When the Start Date is reached the model saves an initial state and continues
the simulation using the forecasted input data provided in the Forecast tab page during the
Forecast Length. When the forecasted input data are updated, the user can start a new forecast
updating the Start Date and the model automatically will use the initial state previously saved.
Inside the SIMULATION DATES panel the user must also provide the simulation Time step and the
Channel Time Step. This last parameter represents the time step used by the model to solve the
channel component (the routing in riverbed) when the kinematic wave routing model is used
instead of the Muskingum-Cunge-Todini routing model. Be carefully to check that the simulation
Time Step is a multiple of the Channel Time Step, otherwise the model will notify an error. If the
lake/reservoir component is activated also the Lake Time Step must be provided; this time step is
used by the model to solve the lakes balance, usually a value of 1 minute is used. Also the Lake
Time Step must be a divisor of the simulation Time Step. Remember that every time step value
must be provided in minutes, while the Forecast Length in hours.

Inside the INITIAL STATE panel, all the initial states inside the selected STATE FOLDER are listed.
The initial states can be managed using the buttons at the bottom of the panel. In order to use one
of the available initial states the Start Date must be equal to one time step after the initial state
date (i.e. if the Time Step is 60 minutes and an initial state is available at date 27/11/1994 00.00, it
will be used if the Start Date is equal to 27/11/1994 01.00).
In order to save the states during an historical simulation the parameters inside the PRINT STATE
DATES must be correctly set. The model will save a state in correspondence of the Print Start Date
(if it is included in the simulation period) and it will continue to save the states every Print Time
Step until the Print End Date is reached.

Moreover, during the simulation also the output maps are printed if the Print Output Maps option
is checked. In this case the user must select inside the PRINT OUTPUT MAPS panel the variables to
be printed and the model will print the maps between the selected Start Date and End Date, with
the provided Time Step. The output maps will be printed in the OUTPUT FOLDER inside a
subfolder named ‘OutMaps’. The default format is binary and it can be read only using the Maps
Visualizer; the user can choose to print the maps also with ASCII format checking the Print ASCII
Format option. The ASCII maps will be printed inside the same folder and can be manually
managed by the user.
Depending on the variables selected inside the PRINT OUTPUT MAPS panel, at the end of the
simulation the user can choose the maps to be displayed by selecting them inside the VIEW
OUTPUT MAPS panel and clicking on the View Simulation Output Maps button at the bottom of
the panel. Remember that the user must select the visualization period and the time step because
a maximum of 72 maps will be displayed by the Maps Visualizer.

Finally, the user can decide to simulate only a part of the basin. This can be done selecting the
upstream point between the Control Points listed in the box Simulation Starts In The Control
Point With ID and the downstream point between the ones listed in the box And Ends In The
Control Point With ID. Remember that if an upstream point is chosen the discharge in that point
will be set to 0 unless an Inflow Point is provided (for this reason this option cannot be used in the
DEMO and EDUCATIONAL versions).

When all the parameters are set, the simulation can be ran clicking on the button SIMULATION (or
FORECAST if the option Real Time Forecasting is checked). If some required fields are empty, on
the top right an ERRORS panel listing the tab pages to be checked before running the simulation
will be displayed.
5. TOOLS

5.1. COMPUTE EVALUATION INDEXES

The Compute Evaluation Indexes tool allows the simulation indexes to be computed for a selected
period. The simulation outputs will be searched in the Output Folder provided in the box on the
top of the window. For all the output files inside this folder (corresponding to the Control Points
whose Print Output option was checked before running the simulation) the software will evaluate
the BIAS, the Root Mean Square Error, the NASH EFFICIENCY and the CORRELATION COEFFICIENT
during the period included between the Start Date and the End Date.

5.2. SIMULATION VISUALIZER

Opening the Simulation Visualizer tool the software will ask for the Control Points, the graph
types and the period to be visualized. Note that if many control points are available for a long
period it is not recommended to display all of them or all the variables, because this could cause
an OutOfMemory error.
When the control points and the variables to be shown have been selected, the following window
will be displayed.
This window gives an overall view of the simulation and the output variables are divided for topic
between the five graphs.
To enlarge one graph the user must double click on it and the following window will be displayed.
The Back button allows the user to come back to the previous window.

The following actions are permitted to change the visualization options:

Left click on:

Series: to visualize the series value for the specific time instant

Right click on:

Chart Area:
 Extract Data in CSV Format: to save all the data included in the graph in CSV format
Save as Image: to save the graph as image in BMP format

Series: to change the series Colour, Width and Style.

Axis: to change the chart area Colour and the grid line Colour, Type and Width

Select a portion of the chart area:

from Left to Right: to zoom in to the selected area
from Right to Left: to zoom out to the maximum chart extension

Arrow Key:
Left, Right, Up and Down: to move the visualized portion of the chart area

Mouse Wheel: to zoom in or zoom out

Compute Indexes (only available for Discharge Chart): to compute the evaluation indexes for the
selected period through the Evaluation Indexes Tool (Section 5.1)

5.3. MAPS VISUALIZER

The Maps Visualizer tool is a simple GIS visualizer that allows the user to display the TOPKAPI-X
configuration maps and to add external objects, such as shape, raster, ASCII, etc...
Remember that the visualizer does not permit to change the coordinates system. The coordinate
system of the Data Layers always corresponds to the one used in the case creation.
Through the Add TOPKAPI-X Configuration Maps menu item the following configuration maps can
be opened if they have been created in the specific case:
Raster Values: map of the raster numbers of each cell inside the basin mask
Original DEM: map of the original DEM provided during the case creation [m]
Filled DEM: map of the filled DEM created by the model or provided by the user [m]
Filling DEM Differences: map of the differences between the original DEM and the filled
DEM automatically computed by the software during the case creation [m]
Basin Outlets: map of basin outlets (cell values: 1 = basin outlet)
Basin Mask: map of the basin mask (cell values: 1 = inside; NoData = outside)
Flow Direction: map of flow directions
Flow Accumulation: map of flow accumulation
Original Riverbed: map of the original riverbed if provided during the case creation (cell
values: 1 = channel cell; NoData = otherwise)
Channel Network: map of the channel network computed by the software (cell values: 1 =
channel cell; NoData = otherwise)
Channel Width: map of the channel widths [m]
Slopes: map of the cell slopes [m/m]
Strahler Orders: map of the Strahler orders (NoData if cell type is not channel)
Soil Type: map of soil type provided by the user
Land Use: map of land use provided by the user
Mean Monthly Temperatures: maps of mean monthly temperatures for each month
Lakes: map containing the lakes ID
Groundwater: map of the groundwater bed [m]
Groundwater Soil Type: map of the groundwater soil type provided by the user

The following actions are permitted to interact with the maps:

Moving mouse on the map: the coordinates and the raster number of the cell corresponding to
the mouse position, and the cell value of the first layer map are displayed in the fields below
the map

Left click on map: the values of all the active raster maps are displayed in a new widow

Right click on map when one of the following maps is active and selected:

Strahler Orders Map:

Add Control Point: allows the user to add a control point if a channel cell is selected
Add Inflow: allows the user to add an inflow point if a channel cell is selected
Add Distributed Contribute: allows the user to add the upstream or downstream point
of a distributed contribute if a channel cell is selected
Add Custom Reach: allows the user to add the upstream or downstream point of a
custom channel reach if a channel cell is selected

Filled DEM Map:

Add Thermometer: allows the user to add a thermometer for the mean monthly
temperature values if these are provided using thermometers values and not
maps
 Groundwater Map
Add Groundwater Withdrawal: allows the user to add a withdrawal point if the
groundwater component is activated

Right click on a map layer name: allows the following actions

Zoom to Layer: zoom to the map layer extent
Properties: open the properties window for the selected map layer (Sections 5.3.1, 5.3.2)
Export Layer: allows the user to export the selected map layer
Remove Layer: remove the selected map layer if permitted (some layers cannot be
removed)

Right click on a group layer name:

Add Group Layer: allows the user to add a group layer. This function is useful when the
observed precipitation, temperature or evapotranspiration maps or the TOPKAPI-X
output maps are visualized. In order to move a map layer to a higher level the user can
add a group layer, move it to the higher position and move inside it the maps.

5.4. PROPERTIES: SIMBOLOGY

Through this form the user can change some visualization properties of the selected layer. The
layer name can be changed unless it is blocked, for example when the Control Points or others
default layers are selected.
Different options can be changed depending on the layer type. If a shape layer is selected, the user
can choose to display all the values with the same colour or to assign a colour for each value of a
specific field, in this case also the Transparent option can be chosen for each unique value.
Anyway, all the values are displayed with the same Shape, Shape Size, Line Width and Line Colour.
In order to change the colours the user must right click on the colour field.
If a raster layer is selected the user can choose if display it with stretched colours or assigning a
colour to each value (this options is available only for raster of integer type and with less than
1000 different values). If Stretched colour is chosen, the user must provide the minimum and
maximum values and the corresponding colours (right clicking on the colour field). Moreover, the
Coloring Type can be chosen between Gradient, Hillshade or Random and the Gradient Model
can be set as Exponential, Linear or Logarithmic. If Unique Values are selected the user can assign
a colour to each value (right clicking on the colour field of each value) or generate random colours.
The NoData values can be displayed checking the option Display NoData as. If this option is
checked the user can set the colour of the NoData values right clicking on the corresponding
colour filed, if the option is unchecked the NoData will be displayed as transparent.

5.5. PROPERTIES: LABELS

For shape type layer it is possible to show the labels checking the option Show Labels in the Labels
tab. If this option is checked the user can choose the field to show and the font.

5.6. COMPARE SIMULATIONS

The Compare Simulations tool allows two simulations to be compared. In the window depicted in
the following figure the user must provide the output folders where the simulations are saved and
when the Next button is clicked the Simulation Visualizer (see Section 5.2) will be called. The
Control Points found in both the output folders will be displayed and the user will be able to
choose the points, the variables and the period to be displayed. The series related to the first
folder will be named with ‘_1’ suffix and the ones related to the second folder with ‘_2’ suffix. The
actions available on the graphs are the same explained in Section 5.2.
When the Simulation Visualizer is displayed during a simulation comparison, the Compute Indexes
button (which appears when the Discharge graph is enlarged) will open a window slightly different
form the one described in Section 5.1. In this case the user can choose two output folders and the
indexes will be computed for each output file found inside the folders and the suffixes ‘_1’ or ‘_2’
will be added to the stations name. The initial values of each field are automatically filled on the
basis of the folders and dates chosen in the previous steps. The software will automatically
compute the indexes for each output file inside the folder, if some file does not contain observed
values for the provided period an error message will be displayed, but anyway the computation
will be made on the others stations.