Cryosphere and Mountain Hydrosphere at ISTA
Published April 29, 2025 | Version V1.0
Model Open

TOPKAPI-ETH Rio Santa model set-up for publication: 'Thin and ephemeral snow shapes melt and runoff dynamics in the Peruvian Andes'

Creators

  • 1. ROR icon Institute of Science and Technology Austria
  • 2. ROR icon University of Sheffield
  • 3. ROR icon Swiss Federal Institute for Forest, Snow and Landscape Research
  • 4. ROR icon British Antarctic Survey
  • 5. ROR icon Universidad Nacional Santiago Antúnez de Mayolo
  • 6. ROR icon National University of Singapore
  • 7. ROR icon Bridgewater State University
  • 8. ROR icon CentrEau - Quebec Water Management Research Centre
  • 9. Geotop
  • 10. ROR icon École de Technologie Supérieure
  • 11. Pacific Institute
  • 12. Autoridad Nacional del Agua
  • 13. Northumbria University

Description

Introduction

This data deposit contains the model files required to run TOPKAPI-ETH for the Rio Santa catchment. The set-up as saved here is suitable for running the model to produce the majority of the outputs associated with the paper 'Thin and ephemeral snow shapes melt and runoff dynamics in the Peruvian Andes'. This model set-up will produce the 'MB_26' outputs in the related dataset of the model outputs. With changes to the RS.TPK file to save only the daily snow grids it could also be used to produce the 'MB_27' model outputs saved in the same dataset. An overview of the model and the input and output data required is provided in the file TManual_Aug2013.pdf, and further details on the parameters and model outputs are provided in TOPKAPI-ETH Documentation.xlsx. Note these documents have not been fully updated, if you have questions please get in touch with Catriona Fyffe. 

How to run the model

  1. Download the files to your directory on your PC or HPC.
  2. Adjust filepaths as needed. Note that currently the filepaths are for Linux, so if you are running on Windows then you'll need to adjust the slashes too. File paths need to be updated in the RS.TPK file and in the run files (see step 5). 
  3. Create outputs and log folders. The output folder should be in the form Outputs/MB_XX, and the filepath is set in RS.TPK under [SimOutput]. If you are running on an HPC system you may also need to create a folder for log files, as set in the TPK_slurm_wine.sh file.
  4. Check the model set-up and parameters. These are all adjusted in the RS.TPK file. See TOPKAPI-ETH Documentation.xlsx, TPK tab for help.
  5. Run the model. This can be done either from MATLAB using the file TPK_run.m (please adjust filepaths, then run the file) or using an HPC system in Linux, in this case TOPKAPI-ETH can be run in the Windows emulator Wine. An example Slurm script is available called TPK_slurm_wine.sh. Please adjust the filepaths and requirements as necessary for your system. You will then need to submit the job to your HPC system.

Running TOPKAPI-ETH for your own catchment

If you'd like to run TOPAKPI-ETH for your catchment then we highly recommend that you use the new version Topwatch. It is currently under development by the team at the Institute of Environmental Engineering, ETH Zurich. We would therefore ask you to get in touch with Prof. Peter Molnar for further information. 

Technical info (English)

File contents and description

FORCINGS > Note 'stations' here refer to the WRF cells used to force the model, for air temperauture and precipitation this is per sub-catchment, for cloud cover all WRF cells within the catchment are used, see SI section 1.2.

CCT_RS.csv > Timeseries of cloud cover transmissivity (fraction) for each forcing 'station', see SI section 1.2.
CCT_RS.xyz > Locations of the cloud cover transmissivity forcing 'stations'.
Pr_RS_main_st.xyz > Locations of the precipitation forcing 'stations'.
Pr_RS_UCnone.csv > Timeseries of precipitation for each forcing 'station', see SI section 1.2. (mm)
Ta_lapse_RS.csv > Air temperature lapse rates for each sub-catchment (note only used in sensitivity runs) (degrees C m^-^1)
Ta_lapse_Tmod_comb.csv > Air temperature lapse rates for each sub-catchment (degrees C m^-^1), see SI section 1.2
Ta_RS.csv > Air temperature time series for each forcing 'station' (note only used in sensitivity runs) (degrees C)
Ta_RS.xyz > Location of air temperature 'stations' used for forcing (note only used in sensitivity runs)
Ta_RS_Tmod_comb.xyz > Location of air temperature 'stations' used for forcing
Ta_RS_Tmod_comb_Hd.csv > Air temperature time series for each forcing 'station' (degrees C)

GRID >
PR_MAPS_MAIN_ST\_XX.asc > Precipitation lapse rates per month (01 to 12), they are multipliers for each cell, see SI section 1.2 for their derivation. 
RIO_SANTA\RS_MASK.asc > Mask of the catchment used in the model. 

FIUME > Defines the working directory root, in this case RS.
hQ_table.txt > Reservoirs water level - outflow relation table, see SI section 1.3.9. Column h is water level in m a.s.l. and Q is outflow in m^3 s^-^1, for each reservoir.
hV_table.txt > Reservoirs water level - volume relation table, see SI section 1.3.9. Column h is water level in m a.s.l. and V is water volume in m^3, for each reservoir. 
RS.cel > Descries the spatial location of each grid cell. 
RS.dem > Digital elevation model for the catchment (m a.s.l.)
RS.gsec > Grid of glacier IDs.
RS.TES > Contains the properties of each of the grid cells in a table format.
RS.TPK > Model configuration file, this contains all the model set-up switches and parameter values. 
RS_DTH2_14.asc > Glacier debris thickness map (m), see SI section 1.2.4 for derivation. 
rs_insno1ogrf.asc > Initial snow depths (mm w.e.), see SI section 1.2.4 for derivation. 
RS_MASK.asc > Mask of the catchment used in the model. 
RS_Reservoir_Level_static.csv > Timeseries of reservoir water levels (m a.s.l.)
rs_soil_d_high.asc > Distributed grid of upper soil depths in m, see SI section 1.2.4 for derivation. 
rs_soil_d_low.asc > Distributed grid of lower soil depths in m, see SI section 1.2.4 for derivation. 
TOPKAPI64
TOPKAPI64.exe > TOPAKPI-ETH model executable. This is a Windows executable, to run in Linux use Wine. 
TOPKAPI-ETH.log > Log file for the last run.
TPK_run.m > Matlab file which can be used to run TOPKAPI-ETH. Please edit file paths and directory as required.
TPK_slurm_wine.sh > Slurm script which can be used to run TOPKAPI-ETH on an HPC system. Please edit file paths and directories as required.

TManual_Aug2013.pdf > Manual describing the model and input and output data required

TOPKAPI-ETH Documentation.xlsx > Excel sheet with documentation on the parameters and model choices (TPK tab) and the contents of the main model outputs. 

Files

MODEL_Cat_forZenodo.zip

Files (181.8 MB)

Name Size Download all
md5:18b88155917e8ef06a0acd0d3953088a
181.8 MB Preview Download

Additional details

Related works

Continues
Dataset: https://catalogue.ceh.ac.uk/documents/c1dc6b28-8dc9-458d-b98d-76a844d1a8cc (URL)
Is continued by
Software: 10.5281/zenodo.15341457 (DOI)
Is source of
Dataset: 10.5281/zenodo.15297284 (DOI)

Funding

Natural Environment Research Council
Peru GROWS: Peruvian Glacier Retreat and its Impact on Water Security NE/S013296/1
UK Research and Innovation
PEGASUS: Producing EnerGy and preventing hAzards from SUrface water Storage in Peru NE/S013318/1
Consejo Nacional de Ciencia, Tecnología e Innovación Tecnológica
Peru GROWS: Peruvian Glacier Retreat and its Impact on Water Security N°08-2019-FONDECYT
European Union
EPIC: ExPloring the ecohydrological Impacts of a changing Cryosphere in the Peruvian Andes 101105480
Swiss National Science Foundation
PASTURE: Glacier retreat and their impact on mountain ecosystems and agriculture in Peru 202604

Dates

Created
2025-04-29
Created dataset

Software

Programming language
MATLAB, Fortran