wknoben / marrmot Goto Github PK

View Code? Open in Web Editor NEW

108.0 108.0 53.0 32.75 MB

Modular Assessment of Rainfall-Runoff Models Toolbox - Matlab code for 47 conceptual hydrologic models

License: GNU General Public License v3.0

MATLAB 65.69% Jupyter Notebook 32.04% Python 2.20% Dockerfile 0.08%

hydrological-modelling hydrology matlab model-comparison rainfall-runoff-model

marrmot's Introduction

MARRMoT

Modular Assessment of Rainfall-Runoff Models Toolbox - Matlab code for 47 conceptual hydrologic models.

MARRMoT is a novel rainfall-runoff model comparison framework that allows objective comparison between different conceptual hydrological model structures. The framework provides Matlab code for 47 unique model structures, standardized parameter ranges across all model structures and robust numerical implementation of each model. The framework is provided with extensive documentation, a User Manual and several workflow scripts that give examples of how to use the framework. MARRMoT is based around individual flux functions and aggregated model functions, allowing a wide range of possible applications.

If you have any questions about using or running the code, or are willing to contribute, please contact l.trotter[-at-] unimelb.edu.au or wouter.knoben[-at-]usask.ca

MARRMoT v2

The MARRMoT master branch has been updated to version 2.1.1. Main changes in MARRMoT v2 compared to v1 include code refactoring to rely on object-oriented programming and speed-ups in the model solving routines. The paper describing these changes was peer reviewed and published in Geoscientific Model Development (Trotter et al., 2022)

The last release of MARRMoT v1 is version 1.4 and can be found as a release here: dx.doi.org/10.5281/zenodo.6460624

Changes since peer-review:

Since MARRMoT v2.1 was peer reviewed, the following minor changes to the code were implemented:

Changes included in the release of v2.1.1
- Edits to my_cmaes to fix typos and improve clarity of outputs to screen
- Typos fixed in models m_13 and m_28
- Edits to MARRMoT_model class to make model objects loadable
- Addition of new objective functions of_MARE and of_PCMARE
- Updates to this README file
Changes included in the release of v2.1.2
- Edits to my_cmaes to fix typos (including error running parallel evaluation)
- Typo fixed in flux evap_15 affecting m_41 and m_45
- Updates to this README file

Getting Started

These instructions will help you install a copy of MARRMoT and run a few example cases. This process should be straightforward and MARRMoT can (given some knowledge of Github and Matlab) be up and running in a matter of minutes.

Requirements

MARRMoT has been developed on MATLAB version 9.11.0.1873467 (R2021b) and tested with Octave 6.4.0. To run in MATLAB, the Optimization Toolbox is required, while Octave requires the optim package.

Note that the function circshift() that is used by routing routines has markedly different behaviour in Matlab 2016b and higher compared to previous versions. Routing results will be unreliable in Matlab 2016a and below but will not generate any warnings or error messages. User discretion is advised.

Install

To obtain the MARRMoT source code:

EITHER: Download a copy of the files from this repository and extract the files in an appropriate directory;
OR: (Optionally fork and) clone this repository onto your own machine.

Then:

Open Matlab;
Add the MARRMoT folder and its subfolders Functions, Models and User Manual to the Matlab path (see image below; open the context menu by right-clicking the main MARRMoT folder inside the Matlab explorer window);

Try an example application

With MARRMoT installed and Matlab open:

Navigate Matlab's current folder to ./MARRMoT/User Manual;
Open the script workflow_example_1.m;
Run the script by pressing F5 or clicking the Run button;
Repeat with workflow_example_2.m and workflow_example_3.m (workflow_example_4.m shows a calibration example and takes a bit longer).

The User Manual provides further details.

Documentation

MARRMoT's documentation includes:

New paper: object-oriented implementation, changes from MARRMoT v1 to v2 (Trotter et al., 2022)
Original paper: rationale behind MARRMoT development, best practices used during development, summary of included model structures and an example application of all structures to simulate streamflow in a single catchment (Knoben et al., 2019).
User manual: description on how to use MARRMoT v2.- and how to contribute to it.
User manual appendices: detailed model descriptions (A), flux equations (B) and unit hydrographs (C)

User manual and appendices are found in this repository in ./MARRMoT/User manual.

Model structure summary

MARRMoT model structures are based on a wide variety of different models. However, do to the standardised format of this framework, MARRMoT models resemble, but are not the same as the models they are based on. In addition to a range of unnamed models, the following models provided inspiration for MARRMoT:

FLEX-Topo
IHACRES
GR4J
TOPMODEL
SIMHYD
VIC
LASCAM
TCM
TANK
XINANJIANG
HYMOD
SACRAMENTO
MODHYDROLOG
HBV-96
MCRM
SMAR
NAM
HYCYMODEL
GSM-SOCONT
ECHO
PRMS
CLASSIC
IHM19

License

MARRMoT is licensed under the GNU GPL v3 license - see the LICENSE file for details.

DOIs of previous releases

v2.1:
v2.0:
v1.4:
v1.3:
v1.2:
v1.1:
v1.0:

Acknowledgements

MARRMoT could not have been made without the effort that many hydrologists have put into development of their models. Their effors are gratefully acknowledged. Special thanks are extended to:

Philip Kraft for finding a bug in the flux smoothing code during peer review;
Sebastian Gnann for suggesting various quality of life fixes;
Clara Brandes for finding and suggesting a fix for a bug in the water balance calculations and implementing m47;
Koen Jansen for suggesting various improvements and correcting parameter descriptions;
Mustafa Kemal Türkeri for making workflow_example_4 operational in Octave; and for performing extensive testing of MARRMoT in Matlab and Octave;
Thomas Wöhling for suggesting various additional efficiency metrics and a possible implementation for warmup periods;
Hidde Drost for suggesting a way to clarify MARRMoT install instructions in this readme;
Dongdong Kong for finding a few typos in the code foe m13 and m28.

marrmot's People

Contributors

Stargazers

Watchers

marrmot's Issues

parfor in my_cmaes.m throws an error!

When I run a model in parallel mode, I get the following error "The range of the parfor-loop variable 'k' must evaluate to a row vector of consecutive increasing integers"
Please help!

add BMI description to main readme file

please add BMI description to the main readme file.

Config file using ERA5

In order to test the BMI it will be good to have a config file using ERA5 data.

Low computing efficiency

In R, Xinanjiang model calibration only cost about 40s.
But in MARRMoT, the calibration is quite low efficiency. With the same forings, half hour passed, still no output.

Just wondering which part delays the computing efficiency? ODE or optimization function? Any idea?

GR4J leads to odd threshold behaviour for certain parameter sets

Diagnosis:

x2 (water exchange parameter) is determined by relative fullness of store S2 (R in original GR4J paper), which is controlled by x3(maximum routing store depth)
Empty S2, no flow from x2; full S2, flow from x2 as x2's value
Perrin (2001) says: ". In absolute value, F cannot be greater than x2: x2 represents the maximum quantity of water that can be added (or released) to (from) each model flow component when the routing store level equals x3."
Theoretically, this works; if S2 never goes above x3, import based on x2 never goes above x2
In practice, if S2 goes over x3, we can end up in situation where water import via x2 goes up (because S2 > x3), which makes S2 go up further, etc.
At some point, an equilibrium will be reached where outflow from S2 through flux Qr is equal to import via x2

Why would S2 go over x3?

Numerical inaccuracies, rounding, etc
if x2 > x3

Possible solutions:

Extra constraint in recharge_2 to ensure that returned flow is at most equal to "flux"
Enforce a check that x2 cannot be greater than x3

JacobPattern error in `m_28_xinanjiang_12p_4s`

In m_28_xinanjiang_12p_4s:

flux_e  = evap_21(lm,c,S1,Ep,delta_t);
flux_r  = saturation_14(a,b,S1,wmax,flux_pi);
flux_rs = saturation_2(S2,smax,ex,flux_r);
flux_ri = saturation_2(S2,smax,ex,S2*ki);
flux_rg = saturation_2(S2,smax,ex,S2*kg);
flux_qs = flux_rb + flux_rs;
flux_qi = interflow_5(ci,S3);
flux_qg = baseflow_1(cg,S4);

% stores ODEs
dS1 = flux_pi - flux_e  - flux_r;
dS2 = flux_r  - flux_rs - flux_ri - flux_rg;
dS3 = flux_ri - flux_qi;
dS4 = flux_rg - flux_qg;

Hence, I think JacobPattern should be

obj.JacobPattern  = [1,0,0,0;
                     1,1,0,0;
                     0,1,1,0;
                     0,1,0,1];

Other than

obj.JacobPattern  = [1,0,0,0;
                     1,1,0,0;
                     0,1,1,0;
                     0,0,1,1];
% the last row error

https://github.com/wknoben/MARRMoT/blob/master/MARRMoT/Models/Model%20files/m_28_xinanjiang_12p_4s.m#L34

Low computing efficiency of `saturation_7`

https://github.com/wknoben/MARRMoT/blob/master/MARRMoT/Models/Flux%20files/saturation_7.m#L24

The integral operation leads to m_14_topmodel_7p_2s about 20 times slower than other models?
Any idea how to improve this?

The attachment is the consumed time for each model in my case.

Thanks and Regards,
Dongdong

BMI implementation of get_value_at_indices still not working in python

work in progress

Implement a hot-start functionality

Implement the ability to continue running the model using saved model outputs from the last run

BMI interface returns wrong data types

Calling bmi methods via grcp4bmi and Docker is giving errors.

model.get_output_var_names() returns error with

Cell(['Fluxes leaving the model > flux_out', 'Internal fluxes > flux_in',
       'Storages (time = t) > S(t)', 'Water balance check > wb'],
      dtype=object) has type <class 'oct2py.io.Cell'>, but expected one of: (<class 'bytes'>, <class 'str'>)

model.get_value('flux_out') returns error with

Arrays with type {} cannot be transmitted through this GRPC channel

Remove constraints from individual flux functions
Build in constraints as part of the solver, where we (1) check if a new solution dumps a store into the negative; (2) if so, reduce all relevant fluxes by a scaled amount.

Big change, so probably should be saved for a large development push.

implementing time by bmi standards

start and end-time are date-vecs, but current time is scalar.

grids not implemented yet

on the python side, grids are not implemented

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.