Topkapi x user manual

TOPKAPITOPKAPI-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 MuskingumCunge-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 subsurface 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 MuskingumCunge-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.