search

geotopmodel / geotop

GEOtop is a distributed model of the mass and energy balance of the hydrological cycle, which is applicable to simulations in continuum in small catchments. GEOtop deals with the effects of topography on the interaction between energy balance and hydrological cycle with peculiar solutions.
GNU General Public License v3.0
38 stars 29 forks source link

readme

GEOtop 3.0

|Build Status| |License (GPL version 3)|

:date: last revision August 2024

Introduction

GEOtop is a distributed model of the mass and energy balance of the hydrological cycle, which is applicable to simulations in continuum in small catchments. GEOtop deals with the effects of topography on the interaction between energy balance and hydrological cycle with peculiar solutions.

GEOtop is distributed under the GNU General Public License version 3. A copy of the license text can be found in the COPYING file.

GEOtop 3.0 version (www.geotop.org) starts from 2.0 version (branch se27xx) already validated and published in the Endrizzi et al. 2014 paper. It performs exactly as the previous version but it has some improvements in terms of:

However, the 3.0 version still lacks of the integration with the MeteoIO library and other features implemented in the current 2.1.1 version (former branch master). In the next months we plan to move toward a stable 3.0 version, together with a publication.

A more detailed description of this new version can be found in the MHPC thesis (https://www.mhpc.it/) of Elisa Bortoli at the following link: https://iris.sissa.it/handle/20.500.11767/86154#.XEXzOsZ7l8w

You can compile and run GEOtop 3.0 following the listed instructions, tested on a Linux system.

Getting the source code

Compiling

Now you can compile using a build system tool. Build tools are programs that automate the creation of executable applications from source code. Building incorporates compiling, linking and packaging the code into a usable or executable form. You can choose between CMake (Please note that you need cmake version 3 at least) and Meson.

Option 1: using CMake

Note that you need to have installed in your system CMake version > 3.0 as it's written in the CMakeLists.txt (https://github.com/geotopmodel/geotop/blob/v3.0/CMakeLists.txt).

Option 2: using Meson

Notes for Mac users

The following information is related to compiling geotop v3.0 using Meson only. On Mac, you might have issues with libomp, The error is something like below:

geotop.p/src_geotop_input.cc.o -c ../src/geotop/input.cc ../src/geotop/input.cc:47:10: fatal error: 'omp.h' file not found

To resolve this, enable the WITH_OMP option in the meson_options.txt file. This option is set to false by default as seen below:

option('WITH_OMP', type: 'boolean', value: false, description: 'Enable openMP framework')

You can either enable it using the command line:

meson configure -DWITH_OMP=true

Alternatively, you can edit the meson_options.txt file directly and set value: true.

Another issue was related to the version of GoogleTest (googletest: stable 1.15.2) being incompatible with C++11. To address this, you can update your meson.build file as follows:

Default header of meson.build file:

project('geotop','cpp',
        default_options : ['cpp_std=c++11',
  'buildtype=release',
  'warning_level=3' ],
        version: '3.0')

Change to:

project('geotop','cpp',
        default_options : ['cpp_std=c++14', # default c++11
  'buildtype=release',
  'warning_level=3' ],
        version: '3.0')

By doing these, you should able to compile geotop version 3.0.0 on Mac using Meson.

Running GEOtop

If you have compiled the code with CMake you will have your executable called geotop in the folder cmake-build, with meson in the folder meson-build.

To run the code just type:

./geotop simulation_path

where simulation_path if the path to a folder where all the input of a simulation are. For example:

./geotop ../tests/1D/Matsch_B2_Ref_007/

Then you can copy the executable binary whethever you want or create a link to the executable file in your binary folder in your home. For example:

cd
mkdir -p bin/
cd bin
ln -s ../your_path_to_geotop_source_folder/meson-build/geotop GEOtop_V30

Then you can modify your .batch_profile file to add the bin folder to your system $PATH variable, so simply typing Geotop_V30 from anywhere you can run GEOtop.

Running the test cases

Now you can run the proposed test cases.

Note that you need to have numdiff installed on your mashine 

apt-get install -y numdiff

Option 1: using CMake

Option 2: using Meson

Getting help

Output error message

If for some reasons at a certain point after typing ninja you get a message like:

Something went terribly wrong. Please file a bug.
FAILED: build.ninja

remove the build folder and create it again.

Looking into the documentation

An interactive documentation can be built with Doxygen by typing in the root directory:

doxygen Doxyfile

A new folder doxygen_generated_doc will be created, containing two subfolders: html and latex, with graphs of the single functions.

If you want to navigate files and functions, go inside html folder and type:

firefox index.html

Reporting an issue

To report a problem you can open an issue on GitHub (https://github.com/geotopmodel/geotop/issues) listing all the following infos:

GEOtop users community

If you want to get in contact with the users and developers community or discuss about your GEOtop application we have the following mailing lists:

GEOtopDev for developers and advanced users: https://groups.google.com/forum/#!forum/geotopdev

GEOtopUsers for regular users: https://groups.google.com/forum/#!forum/geotopusers

DOCUMENTATION

A manual of the model (for the version 1.2, mainly valid also for the current version) can be found here:

http://geotopmodel.github.io/geotop/materials/geotop_manuale.pdf (updated July 2011)

in the doc directory there is further documentation.

Documentation on former versions of the code can be found here:

http://eprints.biblio.unitn.it/551/

http://www.ing.unitn.it/dica/tools/download/Quaderni/tutorial_input_geotop.pdf

Useful material on GEOtop and his hystorical development can be found also on the R.Rigon blog:

http://abouthydrology.blogspot.com/

GEOTOP MODEL I/0 SCRIPTING TOOLS and PLUGINS

The GEOtop model used as I/0 ascii text files. To better analyze and exploit GEOtop outputs several tools have been prepared.

R inteface with the geotopbricks R package

The geotopbricks (R Package) develope by E. Cordano allow a full set of functions to integrate GEOtop outptus as data strctures in the R environment. The development version is in the following git repository https://github.com/ecor/geotopbricks

Python wrapper with the GEOtoPy Python package

GEOtoPy is a small Python package developed by S. Campanella. It works as a GEOtop Python wrapper, exporting a single base class GEOtoPy.GEOtop.

Matlab scripts with the GEOmatlab collection

GEOmatlab is a collection of Matlab scripts to import, analyze and plot GEOtop model output files developed by G. Bertoldi.

EXTERNAL MODEL EXTENSIONS

Thsere are several GEOtop model extensions, to deal with additional physical processes.

High-Performance Optimization for the Calibration of the GEOtop Model

The repository Stefanocampanella/MHPC-project contains notebooks, code and documentation for a high-performance derivative-free optimization to exploit HPC for the calibration of parameters of the GEOtop model. It has been developed by Stefano Campanella in the course of his MHPC Thesis Calibration of the GEOtop model using evolutionary algorithms on supercomputers

GEOtop model particle swarm optimization with R

The plugin geotopOtim2 (R Package), based on geotopbricks (R Package) allows the automatic calibration and sensitivity analysis of the GEOtop 2.x hydrological model, based on the "Particle Swarm Optimisation" approach and the LHOAT "Latin-Hypercube One-factor-At-a-Time" approach. It has been mainly developed by Emanuele Cordano, Samuel Senoner, Giacomo Bertoldi.

GEOtop model optimization with PEST

It has been developed an interface for PEST software package for parameter estimation and uncertainty analysis. An example of the GEOtop-PEST interface for inverse modelling in the Rott catchment can be found at: https://doi.pangaea.de/10.1594/PANGAEA.892921. Full details can be found in the paper Soltani et al. (2019)

In general, PEST requires the following input files for automatic parameter estimation and inverse modelling: (i) Template files, to identify the model parameters; (ii) Instruction files, to identify the model outputs; and (iii) Control file, which supplies PEST with the names of all template and instruction files, the names of model input and output files, initial parameter values, measurement values and weights, etc. (Doherty, 2010).

The PEST software (Doherty, 2002) together with over 100-utility-programs such as SENSAN and GENLINPRED used herein are freely available at http://www.pesthomepage.org/Downloads.php. For detailed and comprehensive information for combining a model of interest with PEST, it is referred to Sect. “3. The Model-PEST Interface” of the PEST manual, as described in Doherty (2002).

GEOtop model for shallow landslides triggering prediction.

GEOtop-SF has been one of the first fully distributed hydrolgical models applied for hallow landslides triggering prediction. A fundamental paper is Simoni et al. (2008), which is referred to the old 0.875 version of the model.

A more recent implementation of GEOtop for shallow landslides prectition can be found in Formetta et al. (2016b), where GEOtop is embedded in the GEOframe modelling system.

GEOtop model for soil erosion prediction.

GEOtop_SED is an extension of GEOtop for modelling sediment dynamics simulating the spatio-temporal dynamics of soil erosion , deposition. Documentation can be found in Zi et al. (2016)

The code of the GEOtop_sed model extension can be dowloaded from the repository: https://github.com/TanZiTT/GEOtopSed

GEOtop model for vegetation dynamic simulation.

GEOtop_DV is a Matlab extension of GEOtop for modelling grassland vegetation dynamics for 1D simulations. Documentation can be found in Della Chiesa et al. (2014)

Operational GEOtop model applications

The GEOtop model has been also used for operational application:

Snow depth mapping

The GEOtop model (v 2.1) is the scientific basis of the MySnowMaps service, which presents real time snow depth maps and prediction for the Alps, implemented by M. Dall´Amico the MobyGis company.

The GEOtop model (v 2.1) has been also used by P. Pogliotti for the ARPA Valle d´Aosta (Italy) to monitor in real-time meltwater avaliabilty for hydropower.

Water budget mapping

A preliminary application of the GEOtop model (v 3.0) for mapping the water budget of the Venosta (Italy) catchment in near real time on a weekly basis has implemented in the following web-gis: https://maps.civis.bz.it/ in the framework of the European Regional Development Fund (ERDF) project DPS4ESLAB.

ACKNOWLEDGEMENTS

Mandatory references

When using the model, please cite the following fundamental papers describing the GEOtop model:

GEOtop developers

The GEOtop model has been developed since year 2000 by a number of people, starting from the research group of Prof. R. Rigon of the University of Trento, Italy, and then by different reseach groups worldwide, in particular the University of Zurich, CH, Eurac research, Italy, the Mountaneering, MobyGIS , WaterJade, Rendena100 )companies. A non exaustive list of contributors include: Marco Pegoretti, Giacomo Bertoldi, Fabrizio Zanotti, Silvia Simoni, Stefano Endrizzi, Matteo dell´Amico, Emanuele Cordano , Stefan Gruber, Andrea Cozzini, Alberto Sartori, Samuel Senoner, Elisa Bortoli.

Financial support

Part of the GEOtop v3.0 refactoring work was developed by E. Bortoli in the framework of her MHCP thesis. This last work was partly supported by:

REFERENCES

Here is the full list of peer-reviewed publications that we know that are using the GEOtop model. Please let as know if some are missed! (updated August 2024):