The UFZ services GitLab and Mattermost will be unavailable on Monday, July 4 from 06:00 AM to 08:00 AM due to maintenance work.

Commit c836ce8c authored by Sebastian Müller's avatar Sebastian Müller 🐈
Browse files

Merge branch 'doc_update' into 'develop'

Online Documentation with GitLab pages

See merge request mhm/mhm!44
parents 4bbabcbe 7ea64612
Pipeline #7900 canceled with stages
......@@ -6,10 +6,15 @@
stages:
- info
- cmake
- build
- valgrind
- test
cache:
# Required to keep artifacts from old builds, e.g. from master/develop
paths:
- public
show-env-vars:
stage: info
variables:
......@@ -26,8 +31,42 @@ show-env-vars:
script:
- echo -e "${SEP}\n${S00}$(date)\n${SEP}\n${S01}\n${S02}\n${S03}\n${S04}\n${SEP}\n${S05}${GIT_CLONE_PATH}\n${S06}\n${SEP}"
pages:
stage: build
script:
- module load foss/2019b
- module load texlive/2019
- module load Graphviz/2.42.2
- module load Anaconda3
- source activate /global/apps/mhm_checks/mhm_env
# use doxygen from the mhm_env conda environment
- doxygen doc/doxygen.config > doxygen_log.txt
# create public dir if not already present
- mkdir -p public
# remove the branch specific subdir if present
- rm -rf public/$CI_COMMIT_REF_NAME/
# recreate the subdir
- mkdir -p public/$CI_COMMIT_REF_NAME/
# copy the doxygen generated html page to the public site
- cp html/* public/$CI_COMMIT_REF_NAME/ -R
# create an index.html that redirects to the master documentation (in master folder)
- cp doc/html_files/index.html public/ -R
# create pdf documentation
- cd latex/ && make > ../doxygen_latex.txt
- cp refman.pdf ../mhm_doc.pdf
- cp refman.pdf ../public/$CI_COMMIT_REF_NAME/mhm_doc.pdf
artifacts:
name: "$CI_COMMIT_REF_NAME"
paths:
- public
- mhm_doc.pdf
- doxygen_log.txt
- doxygen_latex.txt
- doxygen_warn.txt
when: always
cmake-nag62:
stage: cmake
stage: build
variables:
GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_RUNNER_SHORT_TOKEN/$CI_PROJECT_PATH/$CI_COMMIT_REF_NAME/$CI_JOB_NAME
script:
......@@ -40,7 +79,7 @@ cmake-nag62:
- mhm_debug
cmake-gcc73:
stage: cmake
stage: build
variables:
GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_RUNNER_SHORT_TOKEN/$CI_PROJECT_PATH/$CI_COMMIT_REF_NAME/$CI_JOB_NAME
script:
......@@ -57,7 +96,7 @@ cmake-gcc73:
- mhm_openmp_debug
cmake-gcc73MPI:
stage: cmake
stage: build
variables:
GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_RUNNER_SHORT_TOKEN/$CI_PROJECT_PATH/$CI_COMMIT_REF_NAME/$CI_JOB_NAME
script:
......@@ -70,7 +109,7 @@ cmake-gcc73MPI:
- mhm_mpi_debug
cmake-gcc83:
stage: cmake
stage: build
variables:
GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_RUNNER_SHORT_TOKEN/$CI_PROJECT_PATH/$CI_COMMIT_REF_NAME/$CI_JOB_NAME
script:
......@@ -87,7 +126,7 @@ cmake-gcc83:
- mhm_openmp_debug
cmake-gcc83MPI:
stage: cmake
stage: build
variables:
GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_RUNNER_SHORT_TOKEN/$CI_PROJECT_PATH/$CI_COMMIT_REF_NAME/$CI_JOB_NAME
script:
......@@ -100,7 +139,7 @@ cmake-gcc83MPI:
- mhm_mpi_debug
cmake-intel18:
stage: cmake
stage: build
variables:
GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_RUNNER_SHORT_TOKEN/$CI_PROJECT_PATH/$CI_COMMIT_REF_NAME/$CI_JOB_NAME
script:
......@@ -117,7 +156,7 @@ cmake-intel18:
- mhm_openmp_debug
cmake-intel18MPI:
stage: cmake
stage: build
variables:
GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_RUNNER_SHORT_TOKEN/$CI_PROJECT_PATH/$CI_COMMIT_REF_NAME/$CI_JOB_NAME
script:
......
......@@ -54,7 +54,7 @@ While installing cygwin you will have to choose a mirror. A mirror is a server
on the internet where the files for the installation come from. Choose any server
located near your city and when in doubt, choose the first one in the list.
In the next step you can find all available packages provided by cygwin, set
the view to "full". In the search panel you can filter the packages
the view to "full". In the search panel you can filter the packages
by the dependencies listed above (e.g. make). When you choose a
version, the newest one is usually a good choice if not marked as experimental.
......@@ -65,8 +65,8 @@ Some cygwin versions create a new home directory for you. You may check e.g. her
C:\cygwin64\home\$username
As from December 2019, step-by-step guidelines, how to install all netCDF dependencies
can be viewed in [this youtube video](https://www.youtube.com/watch?v=G0i7eDEIfPA&list=PLaT_WNTBfPhK2UT0wkmJR5luEoc9qhbFf)
As from December 2019, step-by-step guidelines, how to install all netCDF dependencies
can be viewed in [this youtube video](https://www.youtube.com/watch?v=G0i7eDEIfPA&list=PLaT_WNTBfPhK2UT0wkmJR5luEoc9qhbFf)
created by Cüneyd Demirel (Istanbul Technical University).
### Ubuntu, Mint and other apt-get based systems with matching repositories:
......@@ -82,7 +82,7 @@ created by Cüneyd Demirel (Istanbul Technical University).
### Module systems:
If you are on a module system, load the modules gcc or intel depending on your
favorite compiler. Then, load the modules netcdf-fortran and cmake.
favorite compiler. Then, load the modules netcdf-fortran and cmake.
These modules will have system specific names, environments, etc.
You may use `module spider` to find the right packages and the
......@@ -90,35 +90,64 @@ right dependencies, potentially use corresponding wiki pages.
#### On eve (the cluster at the UFZ):
If you not already have, opt in for the easy-build setup:
A set of load-scripts is provided in `moduleLoadScripts`, to load all need modules for specifc compilers:
- GNU 7.3 compiler (`foss/2018b` Toolchain):
```bash
source moduleLoadScripts/eve.gcc73
```
or (MPI support)
```bash
source moduleLoadScripts/eve.gcc73MPI
```
- GNU 8.3 compiler (`foss/2019b` Toolchain):
```bash
source moduleLoadScripts/eve.gcc83
```
or (MPI support)
```bash
source moduleLoadScripts/eve.gcc83MPI
```
- Intel 18 compiler (`iomkl/2018b` Toolchain):
```bash
source moduleLoadScripts/eve.intel18
```
or (MPI support)
```bash
source moduleLoadScripts/eve.intel18MPI
```
- NAG 6.2 compiler:
```bash
source moduleLoadScripts/eve.nag62
```
Then you can compile mHM with cmake. We prepared a set of scripts, to automatize the build and compilation process to generate an executable in the root directory with the following naming scheme:
- Release version `mhm`:
```bash
source CI-scripts/compile
```
- Debug version `mhm_debug`:
```bash
source CI-scripts/compile_debug
```
- Release version with MPI support `mhm_mpi`:
```bash
source CI-scripts/compile_MPI
```
- Debug version with MPI support `mhm_mpi_debug`:
```bash
source CI-scripts/compile_MPI_debug
```
- Release version with OpenMP support `mhm_openmp`:
```bash
source CI-scripts/compile_OpenMP
```
- Debug version with OpenMP support `mhm_openmp_debug`:
```bash
source CI-scripts/compile_OpenMP_debug
```
touch ~/.easybuild-yes
Then disconnect from the cluster and connect anew.
(see https://wiki.ufz.de/eve/index.php/EasyBuild for details)
From the source directory use a script provided in `moduleLoadScripts`,
for example for the GNU 7.3 compiler:
source moduleLoadScripts/eve.gfortran73
Starting from Jan 2020, if you want to compile mHM code with intel on EVE (under EasyBuild),
you need to load following modules:
module purge
ml uge/8.5.5-2 Java/1.8.0_202 grid-engine-tools/0.8.3-3-g93f1efa icc/2018.3.222-GCC-7.3.0-2.30 ifort/2018.3.222-GCC-7.3.0-2.30 iccifort/2018.3.222-GCC-7.3.0-2.30
If you use cmake to compile mHM with easy-build, the netcdf-Fortran library and cmake can be loaded as
module load foss/2018b
module load netCDF-Fortran
module load CMake
Then follow the installation instructions.
### MacOS:
*(to be added)*
......@@ -210,7 +239,7 @@ Installation
If everything worked well a Makefile was created with the corresponding paths.
*Note: have a look at "Specific setups" above in case you are using module systems,
or when the netcdf libraries are not located where the package manager usually installs libraries,
or when the netcdf libraries are not located where the package manager usually installs libraries,
or when they are not saved in environment variables (i.e., classical MacOS setups at CHS).*
5. Make the build:
......@@ -227,7 +256,7 @@ Installation
cp build/mhm .
On Windows the executable is called `mhm.exe` instead of `mhm`. In that case
instead of `cp build/mhm .` execute
instead of `cp build/mhm .` execute
cp build/mhm.exe .
......@@ -247,7 +276,7 @@ Installation
Building Realease or Debug versions:
====================================
If you want to set up specific versions of the build, you can
create different folders for that. In case a release and a debug version need to be set up, it makes sense to create two folders named `debug` and `release`.
create different folders for that. In case a release and a debug version need to be set up, it makes sense to create two folders named `debug` and `release`.
mkdir release
......
......@@ -3,43 +3,48 @@
- The current release is **[mHM v5.10][1]**.
- The latest mHM release notes can be found in the file [RELEASES][3] or [online][4].
- General information can be found on the [mHM website](http://www.ufz.de/mhm/).
- All the details of the code can be found in the [user manual][5].
- The mHM comes with a [LICENSE][6] agreement, this includes also the GNU Lesser General Public License.
- There is a list of [publications using mHM][7].
**Please note:** The [GitLab repository](https://git.ufz.de/mhm/mhm) grants read access to the code.
If you like to contribute to the code, please contact [mhm-admin@ufz.de](mailto:mhm-admin@ufz.de).
## Documentation
The online documentation for mHM can be found here (pdf versions are provided there as well):
- stable: https://mhm.pages.ufz.de/mhm
- latest: https://mhm.pages.ufz.de/mhm/develop
## Cite as
Please refer to the main model by citing Samaniego et al. (2010) and Kumar et al. (2013):
- Samaniego L., R. Kumar, S. Attinger (2010): Multiscale parameter regionalization of a grid-based hydrologic model at the mesoscale. Water Resour. Res., 46,W05523, doi:10.1029/2008WR007327, http://onlinelibrary.wiley.com/doi/10.1029/2008WR007327/abstract
- Kumar, R., L. Samaniego, and S. Attinger (2013): Implications of distributed hydrologic model parameterization on water fluxes at multiple scales and locations, Water Resour. Res., 49, doi:10.1029/2012WR012195, http://onlinelibrary.wiley.com/doi/10.1029/2012WR012195/abstract
> Samaniego L., R. Kumar, S. Attinger (2010): Multiscale parameter regionalization of a grid-based hydrologic model at the mesoscale. Water Resour. Res., 46,W05523, doi:10.1029/2008WR007327, http://onlinelibrary.wiley.com/doi/10.1029/2008WR007327/abstract
> Kumar, R., L. Samaniego, and S. Attinger (2013): Implications of distributed hydrologic model parameterization on water fluxes at multiple scales and locations, Water Resour. Res., 49, doi:10.1029/2012WR012195, http://onlinelibrary.wiley.com/doi/10.1029/2012WR012195/abstract
The model code can be cited as:
- **mHM:** Luis Samaniego et al. (2019), mesoscale Hydrologic Model, doi:10.5281/zenodo.1069202, https://doi.org/10.5281/zenodo.1069202
> **mHM:** Luis Samaniego et al. (2019), mesoscale Hydrologic Model, doi:10.5281/zenodo.1069202, https://doi.org/10.5281/zenodo.1069202
## Install
Please see the file [DEPENDENCIES][8] for external software required to run mHM.
See also the [users manual][5] for detailed instructions to setup mHM.
As from June 2019, new option to compile mHM with cmake is provided, see more details under [cmake manual][9].
Please see the file [DEPENDENCIES][8] for external software required to run mHM.
See also the [documentation][5] for detailed instructions to setup mHM.
## Quick start
1. Compile mHM with the `make` command, which uses settings from [Makefile](Makefile).
2. Run mHM on a test basin with the command `./mhm`, which uses settings from [mhm.nml](mhm.nml).
3. Explore the results in the [output directory](test_basin/), e.g. by using the NetCDF viewer `ncview`.
1. Compile mHM
2. Run mHM on the test domains with the command `./mhm`, which uses settings from [mhm.nml](mhm.nml).
3. Explore the results in the [output directory](test_domain/), e.g. by using the NetCDF viewer `ncview`.
[1]: https://git.ufz.de/mhm/mhm/tree/5.10
[2]: https://git.ufz.de/mhm/mhm/repository/5.10/archive.zip
[3]: doc/RELEASES.md
[4]: https://git.ufz.de/mhm/mhm/tags/
[5]: doc/mhm_manual_v5.10.pdf
[5]: https://mhm.pages.ufz.de/mhm
[6]: LICENSE
[7]: doc/mhm_papers.md
[8]: doc/DEPENDENCIES.md
......
/**
\mainpage Introduction to mHM
Welcome to the documentation of mHM version 5.11.
\image html mHM_textlogo.png
This chapter is divided in the following sections:\n
- \ref description
- \ref mHM
- \ref model
- \ref mpr
- \ref param_est
- \ref cal
- \ref mHM
- \ref model
- \ref mpr
- \ref param_est
- \ref cal
- \ref basininfo
- \ref protocols
- \ref protocols
\section description Short Description
......@@ -44,8 +48,8 @@ and flood routing (\ref fig_mhm "mHM"). More information about the model
can be found in
\cite SKA2010 .
\image html mhm5-logo.png "Typical mHM cell"
\anchor fig_mhm \image latex mhm5-logo.pdf "Typical mHM cell" width=10cm
\image html mhm5-logo.png "Typical mHM cell"
\anchor fig_mhm \image latex mhm5-logo.pdf "Typical mHM cell" width=10cm
Dominant processes of the hydrological cycle at mesoscale span over
......@@ -70,7 +74,7 @@ represent the spatial variability of state and inputs variables:
precipitation. The cell size at this level is denoted by
\f$ \ell_2 \f$.
\image html levels.png "Hierarchy of data and modeling levels in mHM"
\image html levels.png "Hierarchy of data and modeling levels in mHM"
\anchor fig_levels \image latex levels.pdf "Hierarchy of data and modeling levels in mHM" width=10cm
......@@ -94,54 +98,54 @@ describe the evolution of the state variables at a given location
\dot{x}_{5i} & = & I_i^L(t) - q_{2i}(t)- q_{3i}(t)- C_i(t) \\
\dot{x}_{6i} & = & C_i(t) - q_{4i}(t) \\
\dot{x}_{7i} & = & \hat{Q}_{i}^{0}(t)-\hat{Q}_{i}^{1}(t)
\f}
\f}
\f$ \quad \forall i \in \Omega \f$.
where
where
<b>Inputs | Description </b>
<b>Inputs | Description </b>
--------- | ---------------------------------------------------------
\f$P\f$ | Daily precipitation depth, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$P\f$ | Daily precipitation depth, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$E_p\f$ | Daily potential evapotranspiration (PET), \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$T\f$ | Daily mean air temperature, \f$^{\circ}C\f$
<b>Fluxes | Description </b>
<b>Fluxes | Description </b>
------------ | ---------------------------------------------------------
\f$S\f$ | Snow precipitation depth, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$R\f$ | Rain precipitation depth, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$M\f$ | Melting snow depth, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$E_p\f$ | Potential evapotranspiration, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$F\f$ | Throughfall, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$E_1\f$ | Actual evaporation intensity from the canopy, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$E_2\f$ | Actual evapotranspiration intensity, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$E_3\f$ | Actual evaporation from free-water bodies, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$S\f$ | Snow precipitation depth, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$R\f$ | Rain precipitation depth, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$M\f$ | Melting snow depth, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$E_p\f$ | Potential evapotranspiration, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$F\f$ | Throughfall, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$E_1\f$ | Actual evaporation intensity from the canopy, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$E_2\f$ | Actual evapotranspiration intensity, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$E_3\f$ | Actual evaporation from free-water bodies, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$I\f$ | Recharge, infiltration intensity or effective precipitation, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$C\f$ | Percolation, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$C\f$ | Percolation, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$q_{1}\f$ | Surface runoff from impervious areas, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$q_{2}\f$ | Fast interflow, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$q_{3}\f$ | Slow interflow, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$q_{4}\f$ | Baseflow, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$q_{2}\f$ | Fast interflow, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$q_{3}\f$ | Slow interflow, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
\f$q_{4}\f$ | Baseflow, \f$\mathrm{mm}\; \mathrm{d}^{-1}\f$
<b> Outputs | Description </b>
<b> Outputs | Description </b>
---------------- | ---------------------------------------------------------
\f$Q_{i}^{0}\f$ | Simulated discharge entering the river stretch at cell \f$i\f$, \f$\mathrm{m}^3\;\mathrm{s}^{-1}\f$
\f$Q_{i}^{1}\f$ | Simulated discharge leaving the river stretch at cell \f$i\f$, \f$\mathrm{m}^3\;\mathrm{s}^{-1}\f$
\f$Q_{i}^{0}\f$ | Simulated discharge entering the river stretch at cell \f$i\f$, \f$\mathrm{m}^3\;\mathrm{s}^{-1}\f$
\f$Q_{i}^{1}\f$ | Simulated discharge leaving the river stretch at cell \f$i\f$, \f$\mathrm{m}^3\;\mathrm{s}^{-1}\f$
<b> States | Description </b>
<b> States | Description </b>
---------- | ---------------------------------------------------------
\f$x_1\f$ | Depth of the canopy storage, \f$\mathrm{mm}\f$
\f$x_2\f$ | Depth of the snowpack, \f$\mathrm{mm}\f$
\f$x_3\f$ | Depth of soil moisture content in the root zone, \f$\mathrm{mm}\f$
\f$x_4\f$ | Depth of impounded water in reservoirs, water bodies, or sealed areas, \f$\mathrm{mm}\f$
\f$x_2\f$ | Depth of the snowpack, \f$\mathrm{mm}\f$
\f$x_3\f$ | Depth of soil moisture content in the root zone, \f$\mathrm{mm}\f$
\f$x_4\f$ | Depth of impounded water in reservoirs, water bodies, or sealed areas, \f$\mathrm{mm}\f$
\f$x_5\f$ | Depth of the water storage in the subsurface reservoir, \f$\mathrm{mm}\f$
\f$x_6\f$ | Depth of the water storage in the groundwater reservoir, \f$\mathrm{mm}\f$
\f$x_7\f$ | Depth of the water storage in the channel reservoir, \f$\mathrm{mm}\f$
\f$x_6\f$ | Depth of the water storage in the groundwater reservoir, \f$\mathrm{mm}\f$
\f$x_7\f$ | Depth of the water storage in the channel reservoir, \f$\mathrm{mm}\f$
<b> Indices | Description </b>
<b> Indices | Description </b>
------------ | ---------------------------------------------------------
\f$l\f$ | Index denoting a root zone horizon, \f$l=1,\ldots,L\f$ (say \f$L=3\f$), in the first layer, \f$0 \leq z \leq z_1\f$
\f$t\f$ | Time index for each \f$\Delta t\f$ interval
\f$\rho^l\f$ | Overall influx fraction accounting for the impervious cover within a cell
\f$l\f$ | Index denoting a root zone horizon, \f$l=1,\ldots,L\f$ (say \f$L=3\f$), in the first layer, \f$0 \leq z \leq z_1\f$
\f$t\f$ | Time index for each \f$\Delta t\f$ interval
\f$\rho^l\f$ | Overall influx fraction accounting for the impervious cover within a cell
\section mpr The Multiscale Parameter Regionalization Technique
......@@ -160,7 +164,7 @@ optimization algorithms \cite PG2009 . To overcome this problem a
multiscale parameter regionalization (MPR) was employed in the mHM
model \cite SKA2010 .
\image html upscaling.pdf "MPR"
\image html upscaling.png "MPR"
\anchor fig_mpr \image latex upscaling.pdf "MPR" width=10cm
Based on this regionalization method, model parameters at a coarser
......@@ -203,7 +207,7 @@ algorithm finds good solutions for the transfer functions parameters
(\f$s=\f$ 45) instead of the model parameters for every grid cell. This,
in turn, implies a great reduction of complexity since \f$ K \times n
\gg s\f$, where \f$n\f$ denotes the total number of cells of a given basin
at level-1.
at level-1.
\section param_est The Parameter Estimation Problem
......@@ -236,7 +240,7 @@ where
\li \f${\beta}\f$ denotes the fields of effective mHM parameters at
level-1 estimated as described in section (\ref mpr "MPR").
\li \f$ \gamma\f$ is a vector of global parameters characterized by a
probability density function \f$\Phi_{\gamma_s}\f$.
probability density function \f$\Phi_{\gamma_s}\f$.
\li \f$i\f$, \f$t\f$ represent a point in space and time
respectively.
......@@ -248,7 +252,7 @@ In general, \f$\gamma\f$ can be estimated, for example, by
where \f$\|\cdot\|\f$ denotes a robust estimator. Many procedures to
estimate global parameters are provided in mHM (e.g. simulated
annealing \cite AK90, dynamically dimensioned search \cite TS2007 .
Other techniques can be found in the CHS Fortran Library.
Other techniques can be found in the CHS Fortran Library.
\section cal Model Calibration
......
......@@ -26,14 +26,14 @@ If not jet available you need to <b>install curl</b> on ypur computer. Download
go to the related folders and use the following commands:
\code
cd /Downloads/curl-7.57
CDIR=/usr/local
CDIR=/usr/local
./configure --prefix=${CDIR}
sudo make check
sudo make install
\endcode
Download the five dependencies zlib, hdf5, szip, netcdf and netcdf fortran and unzip them to
some folder (not the place where you will install them, e.g., /Downloads/).
some folder (not the place where you will install them, e.g., /Downloads/).
<b>Download and unpack zlib</b>, go to the related folder and use the following commands:
\code
......@@ -149,25 +149,25 @@ A NETCDF installation under Windows7 and Windows10 has only been tested using CY
First, the following netcdf packages have to be installed (\ref fig_cygwin_netcdf):
\image html cygwin_netcdf.pdf "netcdf packages for CYGWIN"
\image html cygwin_netcdf.png "netcdf packages for CYGWIN"
\anchor fig_cygwin_netcdf \image latex cygwin_netcdf.pdf "netcdf packages for CYGWIN" width=14.5cm
Second, the following hdf5 version has to be installed for netcdf-4 support.
Second, the following hdf5 version has to be installed for netcdf-4 support.
\image html cygwin_hdf5.pdf "hdf5 packages for CYGWIN"
\image html cygwin_hdf5.png "hdf5 packages for CYGWIN"
\image latex cygwin_hdf5.pdf "hdf5 packages for CYGWIN" width=14cm
Third, the gfortran compiler (\ref fig_cygwin_gfortran) and (\ref fig_cygwin_libgfortran) have to be installed:
\image html cygwin_gfortran.pdf "gfortran packages for CYGWIN"
\image html cygwin_gfortran.png "gfortran packages for CYGWIN"
\anchor fig_cygwin_gfortran \image latex cygwin_gfortran.pdf "gfortran packages for CYGWIN" width=14cm
\image html cygwin_libgfortran.pdf "libgfortran packages for CYGWIN"
\image html cygwin_libgfortran.png "libgfortran packages for CYGWIN"
\anchor fig_cygwin_libgfortran \image latex cygwin_libgfortran.pdf "libgfortran packages for CYGWIN" width=14cm
Fourth, GNU <code>make</code> has to be made available by selecting the following:
\image html cygwin_make.pdf "make packages for CYGWIN"
\image html cygwin_make.png "make packages for CYGWIN"
\image latex cygwin_make.pdf "make packages for CYGWIN" width=15cm
Note that Cygwin users are advised to define following flag in the Makefile, otherwise compilation won't be successful.
......@@ -178,11 +178,11 @@ EXTRA_CFLAGS += -Wl,--stack,12485760
Additionally, make sure to have <code>\cygwin64\bin</code> folder in your environmental path (\ref fig_cygwin_path).
\image html cygwin_path.pdf "setup environmental path CYGWIN"
\image html cygwin_path.png "setup environmental path CYGWIN"
\anchor fig_cygwin_path \image latex cygwin_path.pdf "setup environmental path CYGWIN" width=17cm
Finally, once the installation of CYGWIN including the packages outlined above is completed, you have to change the system in the Makefile to 'cygwin'.
Then, the mhm has proven to compile (simply type <code>make\bin</code> on the command line) under Windows.
Then, the mhm has proven to compile (simply type <code>make\bin</code> on the command line) under Windows.
This will produce an executable <code>mhm\bin</code> which can be launched by <code>./mhm\bin</code> and results for the test basins can be found
under <code>./test_basin/output_b1/</code> and <code>./test_basin_2/output_b1/</code>.
......@@ -191,7 +191,7 @@ under <code>./test_basin/output_b1/</code> and <code>./test_basin_2/output_b1/</
As from June 2019, we encourage users to make use of cmake guide:\n
<a href="https://git.ufz.de/mhm/mhm/blob/develop/INSTALL.md">https://git.ufz.de/mhm/mhm/blob/develop/INSTALL.md</a>
Alternatively to cmake, the Makefile can be used. Compilations of the code need to know paths and locations of its dependencies that are specific to the individual operating system. This requires a file in the make.config folder containing a valid configuration for the system mHM is compiled on. Configuration files for Cygwin and Ubuntu are provided. Creating a new configuration file is only recommended for experienced Linux users.
Alternatively to cmake, the Makefile can be used. Compilations of the code need to know paths and locations of its dependencies that are specific to the individual operating system. This requires a file in the make.config folder containing a valid configuration for the system mHM is compiled on. Configuration files for Cygwin and Ubuntu are provided. Creating a new configuration file is only recommended for experienced Linux users.
Before compiling, make sure that you individual requirements hold.
Open <code>Makefile</code> and adjust at least the following settings:
......@@ -217,7 +217,7 @@ In between two compilations, it might be useful to apply the command <code>make
\section test Test mHM on Example Basin
The mHM distribution usually comes with an example test basin located in
The mHM distribution usually comes with an example test basin located in
\code
test_basin/
\endcode
......@@ -239,12 +239,12 @@ When editing these files, we recommend to use syntax highlighting for Fortran, w
\subsection mhmnml Main Configuration: Paths, Periods, Switches
The file <code>mhm.nml</code> contains the main configuration for running mHM in your catchments. Since the comments should explain
The file <code>mhm.nml</code> contains the main configuration for running mHM in your catchments. Since the comments should explain
each single setting, this section will only roughly describe the structure of the file. By the way, paths can be relative, absolute and even symbolic links.
\li <b>Common Settings:</b> Defines output path, input look-up tables and input data format (all "nc" or all "bin") for all basins in your simulation.
\li <b>Basin wise paths:</b> Set paths for input and output. Create a block for each basin. Remove needless blocks.
\li <b>Resolution:</b> Hourly or Daily time step. Hydrologic resolution should be factorisable with the input resolutions (e.g. meteo: 4000, hydro: 2000, morph: 100).
\li <b>Resolution:</b> Hourly or Daily time step. Hydrologic resolution should be factorisable with the input resolutions (e.g. meteo: 4000, hydro: 2000, morph: 100).
The routing resolutions determines the velocity of water from cell to cell (keep it greater than the hydro resolution). If you change the routing, remember to recalibrate the model (see \ref calibration).
\li <b>Restart:</b> mHM does provide you the option to save the whole model configuration (incl. states, fluxes, routing network, and model parameters) at the end of the simulation period. mHM is then able to restart a new simulation with this model configuration. This reduces the amount of computational time in the newly started simulation because mHM does not have to re-setup the model configuration (e.g., parameter fields and routing network).
\li <b>Periods:</b> Your actual period of interest should be subsequent of a warming period, where model dynamics can set in properly. Remember to expand your input data by that period, too.
......@@ -254,19 +254,19 @@ each single setting, this section will only roughly describe the structure of th
LAI values defined for 10 land classes or choose to run mHM using gridded LAI input data (e.g., MODIS).
Gridded LAI data must be provided on a daily time-step at the Level-0 resolution.
/*!
\li <b>Process Switches:</b>
\li <b>Process Switches:</b>
* - Proccess case 5 - potential evapotranspiration (PET):
* -# PET is input (processCase(5)=0)
* -# PET after Hargreaves-Samani (processCase(5)=1)
* -# PET after Priestley-Taylor (processCase(5)=2)
* -# PET after Penman-Monteith (processCase(5)=3)
* - Proccess case 8 - routing can be activated (=1) or deactivated (=0).
* - Proccess case 8 - routing can be activated (=1) or deactivated (=0).
\li <b>Annual Cycles:</b> Values for pan evaporation hold in impervious regions only. The meteorological forcing table disaggregates daily input data to hourly values.
\subsection mhmoutputnml Output Configuration: Time Steps, States, Fluxes
The file <code>mhm_output.nml</code> regulates how often (e.g. <code>timeStep_model_outputs = 24</code>) and which variables (fluxes and states) should be
written to the final netcdf file <code>[OUTPUT_DIRECTORY]/mHM_Fluxes_States.nc</code>. We recommend to only switch on variables that are of actual interest,
written to the final netcdf file <code>[OUTPUT_DIRECTORY]/mHM_Fluxes_States.nc</code>. We recommend to only switch on variables that are of actual interest,
because the file size will greatly increase with the number of containing variables. During calibration (see \ref calibration) no output file will be written.
\subsection mhmparameters Regionalised Parameters: Initial Values and Ranges
......@@ -278,8 +278,8 @@ and seem to be transferabel to other catchments. If you come up with a very diff
\section calibration Calibration and Optimization
By default, mHM runs without caring about observed discharge data. It will use default values of the global regionalised parameters \gamma, defined in
<code>mhm_parameters.nml</code> . In order to fit discharge to observed data, mHM has to be recalibrated. This will optimise the \gamma parameters
By default, mHM runs without caring about observed discharge data. It will use default values of the global regionalised parameters \gamma, defined in
<code>mhm_parameters.nml</code> . In order to fit discharge to observed data, mHM has to be recalibrated. This will optimise the \gamma parameters
such that mHM arrives at a best fit for discharge. The optimization procedure runs mHM many many times, sampling parameters in their given ranges for each iteration,
until the objective function converges to a confident best fit.
......@@ -297,7 +297,7 @@ Objective functions currently implemented in mHM are:
\li <b>0.5*(NSE+lnNSE):</b> weights both NSE and lnNSE by 50%, roughly fits high and low flows.
\li <b>Likelihood:</b> The confidence bands are probability density functions that capture variable errors, recommended for hydrological discharge.
\li <b>KGE:</b> Kling Gupta model efficiency: combined measure for variability, bias and correlation
\li <b>PD:</b> Pattern dissimilarity (PD) of spatially distributed soil moisture