MARRMOT_47
Implementation
MARRMoT v2.1.1 rev eeb7e15 m_47_IHM19_16p_4s; standardized continuous structure, not original model
Time step: daily
Backend: octave-cli + Octave optim
Calibrated parameters: 16
Temperature required: no
Parameters and initial configuration
Parameter |
Supported calibration range |
Default |
|---|---|---|
|
2 to 5 |
3.5 |
|
0.9 to 1 |
0.95 |
|
0.4 to 0.95 |
0.675 |
|
0.05 to 5 |
2.525 |
|
0 to 1 |
0.5 |
|
1 to 5 |
3.0 |
|
400 to 600 |
500.0 |
|
0.3 to 0.7 |
0.5 |
|
0 to 1000 |
500.0 |
|
0 to 15 |
7.5 |
|
0 to 1 |
0.5 |
|
1 to 5 |
3.0 |
|
300 to 500 |
400.0 |
|
0 to 1 |
0.5 |
|
1 to 5 |
3.0 |
|
0.01 to 5 |
2.505 |
|
Fixed initial/configuration value |
0.0 |
|
Fixed initial/configuration value |
0.0 |
|
Fixed initial/configuration value |
0.0 |
|
Fixed initial/configuration value |
0.0 |
Ranges/defaults are implementation contracts, not universal priors or a recommended basin calibration. Consult source comments for parameter units and coupling.
Governing equations
The following source is the exact model kernel used by this adapter. For MARRMoT it includes the state derivative and each referenced flux function; the solver and routing are described above. Original notices and source citations are retained in the files.
function [dS, fluxes] = model_fun(obj, S)
% parameters
theta = obj.theta;
SIMAX = theta(1); % maximum interception storage [mm]
A = theta(2); % splitting coeffcient for excess precipitation [-]
FF = theta(3); % forest fraction [-]
SMPMAX = theta(4); % maximum storage macropores [mm]
CQMP = theta(5); % runoff time parameter (fast/slow runnoff) first soil layer [1/d]
XQMP = theta(6); % runoff scale parameter first soil layer [-]
SS1MAX = theta(7); % maximum soil moisture storage first soil layer [mm]
FCCS1 = theta(8); % field capacity coefficient fist soil layer [-]
CFS1 = theta(9); % maximum infiltration rate first soil layer [-]
XFS1 = theta(10); % infiltration loss exponent first soil layer [-]
CQS1 = theta(11); % runoff time parameter for (fast/slow runnoff) first soil layer [1/d]
XQS1 = theta(12); % runoff scale parameter first soil layer [-]
SS2MAX = theta(13); % maximum soil moisture storage second soil layer [mm]
CQS2 = theta(14); % runoff time parameter for (fast/slow runnoff) second soil layer [1/d]
XQS2 = theta(15); % runoff scale parameter second soil layer [-]
% delta_t
delta_t = obj.delta_t;
% unit hydrographs and still-to-flow vectors
uhs = obj.uhs;
uh_q0r = uhs{1};
% stores
S1 = S(1);
S2 = S(2);
S3 = S(3);
S4 = S(4);
% climate input
t = obj.t; % this time step
climate_in = obj.input_climate(t,:); % climate at this step
P = climate_in(1);
Ep = climate_in(2);
T = climate_in(3);
% fluxes functions
flux_ei = evap_1(S1,Ep,delta_t);
flux_pex = interception_1(P,S1,SIMAX);
flux_pexmp = split_1(A,flux_pex);
flux_pexs1 = split_2(A,flux_pex);
flux_fmp = infiltration_3(flux_pexmp,S2,SMPMAX);
flux_qexmp = flux_pexmp - flux_fmp;
flux_qmp = interflow_3(CQMP,XQMP,S2,delta_t);
flux_pqexs1 = flux_pexs1 + flux_qexmp;
flux_fs1 = infiltration_7(CFS1,XFS1,S3,SS1MAX,flux_pqexs1);
flux_etas1 = evap_23(FF,FCCS1,S3,SS1MAX,Ep,delta_t);
flux_qs1 = interflow_9(S3,CQS1,FCCS1*SS1MAX,XQS1,delta_t);
flux_q0 = flux_pqexs1 - flux_fs1;
flux_q0r = route(flux_q0, uh_q0r);
flux_qmps1 = flux_qmp + flux_qs1;
flux_pc = infiltration_3(flux_qmps1,S4,SS2MAX);
flux_qh = flux_qmps1 - flux_pc;
flux_qs2 = interflow_3(CQS2,XQS2,S4,delta_t);
flux_qgw = 0.0195;
% stores ODEs
dS1 = P - flux_ei - flux_pex;
dS2 = flux_fmp - flux_qmp;
dS3 = flux_fs1 - flux_etas1 - flux_qs1;
dS4 = flux_pc - flux_qs2;
% outputs
dS = [dS1 dS2 dS3 dS4];
fluxes = [flux_ei, flux_pex, flux_pexmp, flux_pexs1,...
flux_fmp, flux_qexmp, flux_qmp, flux_pqexs1,...
flux_fs1, flux_etas1, flux_qs1, flux_q0,...
flux_q0r, flux_qmps1, flux_pc , flux_qh,...
flux_qs2, flux_qgw];
end
% STEP runs at the end of every timestep.
function [out] = evap_1(S,Ep,dt)
%evap_1
% Copyright (C) 2019, 2021 Wouter J.M. Knoben, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Evaporation at the potential rate
% Constraints: f <= S/dt
% @(Inputs): S - current storage [mm]
% Ep - potential evaporation rate [mm/d]
% dt - time step size
out = min(S/dt,Ep);
end
function [out] = interception_1(In,S,Smax,varargin)
%interception_1
% Copyright (C) 2019, 2021 Wouter J.M. Knoben, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Interception excess when maximum capacity is reached
% Constraints: -
% @(Inputs): In - incoming flux [mm/d]
% S - current storage [mm]
% Smax - maximum storage [mm]
% varargin(1) - smoothing variable r (default 0.01)
% varargin(2) - smoothing variable e (default 5.00)
if size(varargin,2) == 0
out = In.*(1-smoothThreshold_storage_logistic(S,Smax));
elseif size(varargin,2) == 1
out = In.*(1-smoothThreshold_storage_logistic(S,Smax,varargin(1)));
elseif size(varargin,2) == 2
out = In.*(1-smoothThreshold_storage_logistic(S,Smax,varargin(1),varargin(2)));
end
end
function [out] = split_1(p1,In)
%split_1 flow splitting
% Copyright (C) 2019, 2021 Wouter J.M. Knoben, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Split flow (returns flux [mm/d])
% Constraints: -
% @(Inputs): p1 - fraction of flux to be diverted [-]
% In - incoming flux [mm/d]
out = p1.*In;
end
function [out] = split_2(p1,In)
%split_2
% Copyright (C) 2021 Clara Brandes, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Split flow (returns flux [mm/d]), counterpart to split_1
% Constraints: -
% @(Inputs): p1 - fraction of flux to be diverted [-]
% In - incoming flux [mm/d]
out = (1-p1).*In;
end
function [out] = infiltration_3(In,S,Smax,varargin)
%infiltration_3
% Copyright (C) 2019, 2021 Wouter J.M. Knoben, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Infiltration to soil moisture of liquid water stored in snow pack
% Constraints: -
% @(Inputs): In - incoming flux [mm/d]
% S - current storage [mm]
% Smax - maximum storage [mm]
% varargin(1) - smoothing variable r (default 0.01)
% varargin(2) - smoothing variable e (default 5.00)
if size(varargin,2) == 0
out = In.*(1-smoothThreshold_storage_logistic(S,Smax));
elseif size(varargin,2) == 1
out = In.*(1-smoothThreshold_storage_logistic(S,Smax,varargin(1)));
elseif size(varargin,2) == 2
out = In.*(1-smoothThreshold_storage_logistic(S,Smax,varargin(1),varargin(2)));
end
end
function [out] = interflow_3(p1,p2,S,dt)
%interflow_3
% Copyright (C) 2019, 2021 Wouter J.M. Knoben, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Non-linear interflow (variant)
% Constraints: f <= S
% S >= 0 - this avoids numerical issues with complex numbers
% @(Inputs): p1 - time delay [d-1]
% p2 - exponential scaling parameter [-]
% S - current storage [mm]
% dt - time step size [d]
out = min(p1*max(S,0)^(p2),max(S/dt,0));
end
function [out] = infiltration_7(p1,p2,S,Smax,In,varargin)
%infiltration_7: infiltration_1 with customization
% Copyright (C) 2021 Clara Brandes, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Infiltration as exponentially declining based on relative storage
% Constraints: f <= fin
% @(Inputs): p1 - maximum infiltration rate [mm,/d]
% p2 - exponential scaling parameter [-]
% S - current storage [mm]
% Smax - maximum storage [mm]
% fin - size of incoming flux [mm/d]
pre_smoother = (min(p1.*exp((-1*p2*S)./Smax),In));
if size(varargin,2) == 0
out = pre_smoother.*(1-smoothThreshold_storage_logistic(S,Smax));
elseif size(varargin,2) == 1
out = pre_smoother.*(1-smoothThreshold_storage_logistic(S,Smax,varargin(1)));
elseif size(varargin,2) == 2
out = pre_smoother.*(1-smoothThreshold_storage_logistic(S,Smax,varargin(1),varargin(2)));
end
end
function [out] = evap_23(p1,p2,S,Smax,Ep,dt)
% evap_23 combines evap_5 (evaporation) and evap_6 (transpiration)
% Copyright (C) 2021 Clara Brandes, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Transpiration from vegetation at the potential rate if
% storage is above field capacity and scaled by relative
% storage if not (similar to evap_6), addition of
% Evaporation from bare soil scaled by relative storage
% (similar to evap_5)
% Constraints: Ea <= Ep
% Ea <= S/dt
% @(Inputs): p1 - fraction vegetated area [-] (0...1)
% p2 - field capacity coefficient[-]
% S - current storage [mm]
% Smax - maximum storage [mm]
% Ep - potential evapotranspiration rate [mm/d]
% dt - time step size [d]
out = min([p1.*Ep+(1-p1).*S./Smax.*Ep, p1*Ep*S./(p2*Smax)+(1-p1).*S./Smax.*Ep,S/dt]);
end
function [out] = interflow_9(S,p1,p2,p3,dt)
%interflow_9
% Copyright (C) 2019, 2021 Wouter J.M. Knoben, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Non-linear interflow if storage exceeds a threshold
% Constraints: f <= S-p2
% S-p2 >= 0 prevents numerical issues with complex numbers
% @(Inputs): p1 - time coefficient [d-1]
% p2 - storage threshold for flow generation [mm]
% p3 - exponential scaling parameter [-]
% S - current storage [mm]
% dt - time step size [d]
out = min(max((S-p2)/dt,0),(p1.*max(S-p2,0)).^p3);
end
function [ flux_out ] = route(flux_in, uh)
% ROUTE calculates the output of a unit hydrograph at the current timestep
% after routing a flux through it.
% Copyright (C) 2019, 2021 Wouter J.M. Knoben, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% In:
% flux_in - input flux [1x1]
% uh - unit hydrograph [nx2]
% uh's first row contains coeficients to splut flow at each
% of n timesteps forward, the second row contains
% still-to-flow values.
%
% Out:
% flux_out - flux routed through the uh at this step [1x1]
%
flux_out = uh(1,1) * flux_in + uh(2,1);
end
function [out] = smoothThreshold_storage_logistic(S,Smax,r,e)
%smoothThreshold_storage_logistic Logisitic smoother for storage threshold functions.
% Copyright (C) 2018 Wouter J.M. Knoben
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Smooths the transition of threshold functions of the form:
%
% Q = { P, if S = Smax
% { 0, if S < Smax
%
% By transforming the equation above to Q = f(P,S,Smax,e,r):
% Q = P * 1/ (1+exp((S-Smax+r*e*Smax)/(r*Smax)))
%
% Inputs:
% S : current storage
% Smax : maximum storage
% r : [optional] smoothing parameter rho, default = 0.01
% e : [optional] smoothing parameter e, default 5
%
% NOTE: this function only outputs the multiplier. This needs to be
% applied to the proper flux utside of this function.
%
% NOTE: can be applied for temperature thresholds as well (i.e. snow
% modules). This simply means that S becomes T, and Smax T0.
% Check for inputs and use defaults if not provided
% NOTE: this is not very elegant, but it is more than a factor 10 faster then:
% if ~exist('r','var'); r = 0.01; end
% if ~exist('e','var'); e = 5.00; end
if nargin == 2
r = 0.01;
e = 5.00;
elseif nargin == 3
r = r{1};
e = 5.00;
elseif nargin == 4
r = r{1};
e = e{1};
end
% Calculate multiplier
Smax = max(Smax,0); % this avoids numerical instabilities when Smax<0
if r*Smax == 0
out = 1 ./ (1+exp((S-Smax+r*e*Smax)/(r)));
else
out = 1 ./ (1+exp((S-Smax+r*e*Smax)/(r*Smax)));
end
end
function [out] = evap_5(p1,S,Smax,Ep,dt)
%evap_5 evaporation based on scaled current water storage, for a fraction
%of the surface
% Copyright (C) 2019, 2021 Wouter J.M. Knoben, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Evaporation from bare soil scaled by relative storage
% Constraints: Ea <= Ep
% Ea <= S/dt
% @(Inputs): p1 - fraction of area that is bare soil [-]
% S - current storage [mm]
% Smax - maximum storage [mm]
% Ep - potential evapotranspiration rate [mm/d]
% dt - time step size [d]
out = max(min((1-p1).*S./Smax.*Ep,S/dt),0);
end
function [out] = evap_6(p1,p2,S,Smax,Ep,dt)
%evap_6 evaporation based on scaled current water storage, a wilting point,
%a constraining factor and limited by potential rate.
% Copyright (C) 2019, 2021 Wouter J.M. Knoben, Luca Trotter
% This file is part of the Modular Assessment of Rainfall-Runoff Models
% Toolbox (MARRMoT).
% MARRMoT is a free software (GNU GPL v3) and distributed WITHOUT ANY
% WARRANTY. See <https://www.gnu.org/licenses/> for details.
% Flux function
% ------------------
% Description: Transpiration from vegetation at the potential rate if
% storage is above a wilting point and scaled by relative
% storage if not
% Constraints: Ea <= Ep
% Ea <= S/dt
% @(Inputs): p1 - fraction vegetated area [-]
% p2 - wilting point as fraction of Smax
% S - current storage [mm]
% Smax - maximum storage [mm]
% Ep - potential evapotranspiration rate [mm/d]
% dt - time step size [d]
out = min([p1.*Ep,p1*Ep*S./(p2*Smax),S/dt]);
end
Note
This standardized MARRMoT structure is not identical to the original named model. p01... follow exact source order; s01... are fixed initial stores, defaulting to zero. Octave + optim are required. Solver behavior can differ across runtime versions.
Simulation
from basinforge import Basin, get_model
basin = Basin.from_csv("basin.csv", basin_id="A", area_km2=1200,
q_unit="m3/s", timestep="daily")
q_mm = get_model("MARRMOT_47").simulate(basin)
q_m3s = basin.to_m3s(q_mm)
Supply your actual data and catchment area; temperature-dependent models require a temperature column. For non-daily models, choose an appropriate warmup in model steps.
See calibration, input requirements, sources and verification limitations.