MARRMoT's scope is limited to conceptual hydrological models and the code currently includes no spatial discretization of inputs or catchment response. Models are expected to be used in a lumped fashion, although users could create their own interface to use MARRMoT code to represent within-catchment variability using multiple lumped model structures. Required model inputs are standardized across all MARRMoT models, and every model only requires time series of precipitation, potential evapotranspiration, and optionally temperature (used by certain snow modules). Model outputs are equally standardized and provide time series of simulated flow, total evaporation fluxes, and optionally model states and internal fluxes. The models are set up such that they can use a user-specified time step size (e.g. daily, hourly) which is currently effectively the temporal resolution of the forcing data. Models and flux equations internally account for this time step size so that parameter values can use consistent units, regardless of the temporal resolution of the forcing data. The main goal of this setup is ease of use so that it is straightforward to switch between different model structures within an experiment.

MARRMoT models are based on written documentation only, not on existing computer code. This choice is motivated by our aim to produce traceable code and by several practical concerns. The documentation we base our models on is traceable through our cited sources. Computer code for hydrologic models tends to be less traceable than their documentation: code might be unavailable, code might not be accompanied by a persistent identifier, or multiple versions of the same model (using the same model name) might be available, which complicates finding the “original” computer code. This is supported by various authors who developed the original models: “Today many versions of the HBV model exist, and new codes are constantly developed by different groups ... ” (Lindström et al., 1997); “... TOPMODEL is not a single model structure [...] but more a set of conceptual tools” (Beven et al., 1995).

First, MARRMoT uses a distinct separation of model equations as state-space formulations and the numerical approach used to solve these equations. In the theoretical process of developing a new hydrological model, the modeller ideally goes through several distinct steps (e.g. Beven, 2012; Clark and Kavetski, 2010; Gupta et al., 2012). To start, the modeller develops a mental, perceptual model of catchment behaviour based on observations and/or other knowledge (i.e. expert opinion). Next, this model is simplified into an abstraction that shows the connection of the most important fluxes and storages (also termed a conceptual model, but this is a distinctly different meaning than when applied to a bucket-type hydrologic model). These relations are then formalized as ordinary differential equations (ODEs) and their constitutive functions in a mathematical model. Finally, creating computer code to solve these equations sequentially as a time series is done with the procedural model. In practice, however, these stages are often not distinct and tend to overlap (e.g. Kavetski et al., 2003), a process referred to as “ad hoc” modelling. Overlap of the mathematical and procedural model can lead to altered model behaviour and difficulty with parameter estimation (Clark and Kavetski, 2010; Kavetski and Clark, 2010; Kavetski et al., 2003). A clear separation between model equations and the code used to solve those equations gives computer code that is easier to understand and update with new time-stepping schemes or flux equations relative to code into which the model equations are interwoven with the numerical scheme.

Second, MARRMoT gives the possibility to choose a numerical method to approximate the ODEs in discrete time steps. Currently, a fixed-step implicit Euler method is recommended as default, and an explicit Euler method is provided for result matching with previous studies. Many implementations of hydrologic models use the explicit Euler method to approximate storage changes (Schoups et al., 2010; Singh and Woolhiser, 2002). The explicit Euler method relies on storage values at the start of a time step to estimate flux sizes in the current time step: FLUX(t) = f(STORE(t-1)). This method is easy to implement and fast to compute but has several disadvantages: it has low accuracy and only conditional stability, which can lead to large numerical errors and the amplification of such errors under certain conditions (Clark and Kavetski, 2010; Kavetski and Clark, 2010; Schoups et al., 2010). Implicit methods such as implicit Euler instead rely on an iterative procedure that relates flux size to storage at the end of a time step: FLUX(t) = f(STORE(t)). These methods require more intensive iterative computation but avoid the aforementioned issues even when implemented with fixed time step sizes (Kavetski et al., 2006; Schoups et al., 2010). Higher-order numerical approximation methods are currently not provided in MARRMoT but can be included in a straightforward manner. Note that fixed time step size refers to the use of a single time step size throughout a simulation (i.e. no adaptive sub-stepping is used; see Sect. 5.3.5) and does not prescribe the time step size (e.g. hourly, daily)

Third, MARRMoT removes threshold discontinuities in model equations through logistic smoothing (Clark et al., 2008; Kavetski and Kuczera, 2007). Hydrologic processes are often characterized by thresholds, e.g. snowmelt starts when a certain temperature is exceeded and saturation excess flow occurs when the soil is saturated. Introducing threshold behaviour into hydrologic models leads to discontinuities in the model's objective function, which can complicate parameter estimation when small changes in parameter values may lead to large changes in objective function value or in the gradient thereof (Kavetski and Kuczera, 2007). Smoothing model equations avoids these discontinuities but also involves a fundamental change to the model equations. Kavetski and Kuczera (2007) recommend logistic functions to smooth threshold equations that closely resemble the original threshold function but are continuous throughout the function's domain. MARRMoT smooths storage-based thresholds with a logistic function (Clark et al., 2008): 1Qo=Qin1-ΦS,Smax,ρS,ε,2ΦS,Smax,ρS,ε=11+eS-Smax+ωεω, where Qo and Qin are flux output and input, respectively, and ϕ the smoothing operator. S and Smax are current and maximum storage, respectively, ω represents the degree of smoothing according to ω=ρSSmax, and ε is a coefficient that ensures that S does not exceed Smax. ρS and ε can be specified by the user or used with default values of 0.01 and 5.00, respectively (Clark et al., 2008). Temperature-based thresholds are smoothed with a different logistic function (Kavetski and Kuczera, 2007): 3PS=PΦT,Tt,ρT,4ΦT,T0,ρT=11+eT-T0ρT, where PS is precipitation as snow, P incoming precipitation, and ϕ the smoothing operator. T and T0 are the current and threshold temperatures, respectively, and ρT is the smoothing parameter with default value 0.01.

Fourth, MARRMoT solves all model equations simultaneously rather than sequentially. Operator-splitting (OS) numerical approximations integrate fluxes sequentially and can be useful in cases such as large systems of partial differential equations, for which computational speed would otherwise be a limiting factor (Fenicia et al., 2011). Sequential calculation of model fluxes is common practice in many hydrologic models (e.g. SACRAMENTO and GR4J), but this approach assumes that fluxes occur in a predetermined order. It is preferable to integrate model fluxes simultaneously to avoid “physically unsatisfying assumption(s)” (Fenicia et al., 2011; Santos et al., 2018). MARRMoT follows this recommendation, barring certain cases in which the model is divided into two distinct parts due to a delay function, in which case simultaneous solving of the first and second part of the model is impossible.

Figure 1 shows the setup of the MARRMoT framework, including what the framework requires (i.e. data, model options, etc.) and provides for a given modelling study. Each model has its own separate model function, which contains both the numerical implementation of the model (i.e. the ODEs and fluxes that make up this model, as given in Sects. S2, S3, and S4) and the necessary code to handle user input, run the model to produce a time series, and generate output. The user is expected to provide the following inputs: time series of climate variables, initial values for each model store, choice of numerical integration method and settings for MATLAB solvers, and values for each model parameter. Note that the solver selection relates to time-stepping numerics, not parameter selection and/or optimization. Optionally, MARRMoT's provided parameter range guidance (Sect. S5) can inform the choice of parameter values. Parameter ranges have been standardized as much as possible across all models such that similar processes use the same range of possible parameter values across models (e.g. this ensures that all models that have an interception component with a maximum capacity can use the same range, 0–5 mm, for their respective interception capacity parameter). Each model generates a time series of total simulated flow and total simulated evaporation as default output. Optionally, users can request variables with time series of storages and internal fluxes, as well as a summary of the main water balance components. The user manual provides several workflow examples that showcase possible uses of MARRMoT: the examples cover (i) the application of a single model with a single parameter set to a single catchment, (ii) random parameter sampling from provided parameter ranges for a single model, (iii) the application of three different models to a single catchment, and (iv) calibration of a single parameter set for a single model. These examples can easily be adapted to work with multiple catchments if desired.

The basic building blocks inside each model function are flux functions. Each flux function describes a single flux, for example evaporation from an interception store, water exchange between two soil moisture stores, or baseflow from groundwater. Flux functions are kept separate from the model functions, and each model calls several flux functions as needed. This allows for consistency across models (if errors are present in any flux function, at least they are the same in all models), easy implementation of new flux equations, and facilitation of studies that are specifically interested in differences between various mathematical equations that all represent the same flux or process. The inputs required and output returned by each flux function vary. See Sect. S3 for a full overview of the mathematical functions used to represent fluxes in each model description, relevant constraints, numerical implementation of each flux in MARRMoT, and a list of models that use each flux function. Various models use a unit hydrograph approach to delay flows within the model and/or simulate flow routing. See Sect. S4 for a full overview of the unit hydrographs currently implemented in MARRMoT.

Table 1 shows an overview of the model structures currently implemented in MARRMoT and the main reference(s) that these model structures are based on (see Sect. 5.3.3 for a discussion of the comparability of MARRMoT models and their original counterparts). Some of the source models have a long history of application, and others are part of model comparison or development studies. MARRMoT development was not guided by a specific modelling objective (e.g. droughts, floods), and the current selection of model structures mainly aims for variety in the range of model structures. The user manual provides guidance on changing and expanding the framework, and, due to its open nature, these additions can be shared with the wider community. Each model is internally different from the others, either through using different configurations of stores and their connections, through using different flux equations, or both. Models with sequential numbering (e.g. mopex1, mopex2) are part of the same study and tend to be similar but more elaborate as the number increases. Detailed model descriptions can be found in Sect. S2. The model code as currently provided was extensively checked for water balance errors during development using multiple parameter sets for each model, both randomly sampled and using all combinations of extreme values with MARRMoT's provided parameter ranges. These errors were generally of the order of 1E-12 or smaller, showing that the water balance is properly accounted for in each model.

Figure 2 provides a summarized overview of the model differences expressed through the number of stores, number of parameters, and hydrological processes represented. Models use between one and eight stores and between 1 and 23 parameters. The number of parameters tends to increase with the number of stores, but exceptions exist. Most model stores are used to track moisture availability (i.e. across all models 162 stores are used, 155 of which track moisture availability); deficit stores are much rarer (i.e. only 7 out of 162 stores are used to track moisture deficit). Soil moisture storage is the most commonly modelled concept occurring in every model. Routing stores (e.g. “fast flow routing”) are included in 18 models, groundwater stores in 13 models, snow storage in 12, interception in 10, unit hydrograph routing also in 10, surface depression storage in 2, and channel storage in 1 model. However, these numbers should not be seen as representative of all conceptual models because our model overview is necessarily incomplete and some of our models are part of model development studies (wherein a model is modified until satisfactory performance is obtained). These studies skew the number of stores in certain categories.

Reproducibility of computational hydrology is rarely achieved, primarily because data and code are not regularly made available (Hutton et al., 2016). In the case of hydrologic models, this results in many different versions of the same model being in circulation, made either by different people with different interpretations of the original publication and/or including their own model variant. Without publicly available code, only stating a model's name in a study is insufficient for knowing which equations and numerical methods make up that particular instance of the model. Conclusions from any modelling study are thus conditional on a certain set of equations that are unknown to the reader, which makes the generalizability of findings low. However, there is a trend in hydrology towards open and shareable research. Large-scale hydrologic datasets (e.g. CAMELS, Addor et al., 2017; CAMELS-CL, Alvarez-Garreton et al., 2018; GSIM, Do et al., 2018; Gudmundsson et al., 2018) are commonly made available, and certain journals already enforce better coding and sharing practices. Much work is being done on benchmarking data uncertainty (e.g. McMillan et al., 2012) and model performance (e.g. Seibert et al., 2018), which encourages objective conclusions about the strengths and weaknesses of any model and investigation. By making a multi-model toolbox based on various established models available as open-source code, we hope to contribute to this trend of more transparent and reproducible science. Furthermore, this toolbox lowers the threshold for model comparison studies and can help to diminish “legacy” reasons for model application (i.e. choosing to use a certain model for reasons other than the model's perceived appropriateness for the task at hand, such as convenience or past experience; Addor and Melsen, 2019).

Our model overview (Sect. S2) and compilation of these models in a single framework allows for unique lessons and insights into the current state of conceptual models (conditional on the sample of model structures we have selected).

The core of this selection of conceptual models is a soil moisture accounting (SMA) module. Every model includes some form of soil moisture store in which moisture is kept and from which moisture is evaporated. Despite this, surface processes, rather than those in the subsurface (both vadose and groundwater zones), tend to be modelled in the greatest detail. For example, intricate snow (e.g. Lindström et al., 1997; Schaefli et al., 2005), interception (e.g. Fukushima, 1988), and surface depression storage (e.g. Chiew and McMahon, 1994; Leavesley et al., 1983; Markstrom et al., 2015) conceptualizations exist among the models, but subsurface processes tend to be much more abstract. This is the same observation as made in Vinogradov et al. (2011). This is understandable because surface processes are easier to observe and formulate hypotheses about, but the subsurface is a crucial component in the water balance (as evidenced by the presence of an SMA component in every single model). A next step in conceptual modelling can be to explicitly formulate hypotheses of subsurface catchment configurations and testing these. For example, the “fill-and-spill” hypothesis (Tromp-Van Meerveld and McDonnell, 2006) could be compared to more traditional subsurface conceptualizations such as linear reservoirs. Framing research as testing alternative hypotheses (Clark et al., 2011) and using modelling tools such as MARRMoT allows for the testing of these ideas in a controlled manner.

A striking difference exists among models that take evaporation from multiple stores. Certain models use the potential evapotranspiration (PET) rate to limit evaporation from each individual store (e.g. MODHYDROLOG, Chiew and McMahon, 1994; NAM, Nielsen and Hansen, 1973; HYCYMODEL, Fukushima, 1988), whereas others use PET as the maximum that can be evaporated from all stores combined (e.g. ECHO, Schaefli et al., 2014; PRMS, Leavesley et al., 1983; Markstrom et al., 2015; CLASSIC, Crooks and Naden, 2007). This can lead to situations in which a model evaporates water at a net rate higher than PET. Depending on the way PET is estimated (see e.g. McMahon et al., 2013, for an overview of PET estimation methods) and which reference crop is used compared to the vegetation in the catchment being modelled, either assumption might be appropriate. Evaporation is a significant component of the water balance (McMahon et al., 2013) and a proper choice in any modelling effort is thus important.

Another difference is the distinction between process-aggregated and process-explicit models. Process-aggregated models (e.g. GR4J, Perrin et al., 2003; IHACRES, Croke and Jakeman, 2004; Littlewood et al., 1997) do not attempt to model individual hydrologic processes but focus on the flows resulting from an aggregation of overall catchment behaviour. Process-explicit models (e.g. MODHYDROLOG, Chiew and McMahon, 1994; FLEX-Topo, Savenije, 2010) explicitly include a variety of hydrologic processes deemed important for a certain modelling purpose. Process-aggregated models tend to have a small number of parameters, which can be preferable when calibrating a model to streamflow only. Process-explicit models are more intuitive when simulating changing conditions due to their explicit process representation, under the strong assumption that the model's equations and parameters can be related to the real-world processes the model intends to simulate.

Summarizing, even within this subset of all hydrologic models, conceptual models exist in a wide variety of shapes and sizes. They are easy-to-use tools to test whether detailed findings from experimental catchments are applicable to many different catchment types worldwide. This approach combines the thorough understanding developed in well-monitored catchments with the ability to generalize conclusions through extensive testing of these findings in other places.