# Software

DREAM Suite | MATLAB Packages | R Packages | Python Packages | Fortran Packages | Other Languages | Parallel Computation

## DREAM Suite

DREAM Suite (DIRECT LINK or http://www.dreamsuite.eu) is a software package for Bayesian inference of numerical simulation models. The program has been developed by PC-Progress in cooperation with Dr. Jasper Vrugt and can be used for the rapid development of applications based on the theory of Markov chain Monte Carlo (MCMC) simulation and the DiffeRential Evolution Adaptive Metropolis (DREAM) method. The package includes more than twenty different examples illustrating the main capabilities and functionalities of DREAM Suite. These examples are available including C++ source code, are easy to adapt and can serve as templates for other inference problems. Plugin modules for new projects can be simply generated using the build-in C++ code generator and finished in Microsoft Visual Studio (free Community Edition 2015 or 2013).

As COM server DREAM Suite is readily combined with many other programming languages so that users can rapidly combine their models and data with the GUI and implement the solver and graphical interface for Bayesian inference. We hope that DREAM Suite facilitates the further growth of Bayesian methods in science, engineering, philosophy, medicine, economy, sport and law. New examples are continuously published in the peer-reviewed literature and added to the program (LINK with few examples). The figures below summarize a few pages of the GUI and simplifies considerably the implementation and use of Bayesian methods.

A demo version of DREAM Suite can be downloaded at the following LINK or the website http://www.pc-progress.com/en/Default.aspx?dream-downloads. A user manual can be downloaded HERE and a technical manual of the DREAM method itself can be found HERE. For questions about DREAM Suite please contact PC-Progress at support@pc-progress.com.

## MATLAB Packages

Some of the codes can be downloaded directly below by a right mouse click (“save link as”) on the relevant links “(Download MATLAB Code)”. After download, you will need to rename the extension “PDF” to “RAR” and unzip! Detailed instructions are provided in the respective manuals of each code. Those codes for which a direct download is not possible, you can request by filling out the Software Request Document .

FDCFIT – MATLAB package for fitting of flow duration curves. This package returns the optimized coefficients of each of the fifteen default functions and provides graphical output including summary statistics of the quality of fit. This package includes the mathematical functions proposed by Sadegh et al. (2016) . This toolbox is also useful for diagnostic model evaluation as the optimized coefficients can be used as summary metrics.

The FDC is a signature catchment characteristic that depicts graphically the relationship between the exceedance probability of streamflow and its magnitude. This curve is relatively easy to create and interpret, and is used widely for hydrologic analysis, water quality management, and the design of hydroelectric power plants (among others). While several physically-based and probabilistic/mathematical functions have been used to model the empirical FDCs, they fail to characterize adequately the mid-section and tails of the FDC at low and high exceedance probabilities, respectively, and the large differences between the FDCs of watersheds with contrasting hydrologic behaviors. The work of Sadegh et al. (2016) builds on the idea presented by Vrugt and Sadegh (2013) and introduces several commonly used models of the soil water characteristic (SWC) as new class of closed-form parametric expressions for the FDC. These soil water retention functions (WRF) are relatively simple to use, contain two or three parameters, and mimic closely the empirical FDCs of the 438 MOPEX watersheds.

DOWNLOAD FDCFIT MATLAB CODE [ Use right mouse click (“save link as”) and after download rename extension .pdf to .rar and unzip using WinRAR – detailed instructions provided in Appendix A of FDCFIT manual ]

**DREAM** – Differential Evolution Adaptive Metropolis (DREAM) Markov chain Monte Carlo (MCMC) sampling of the posterior probability density function. This code runs multiple different chains simultaneously for global exploration, and automatically tunes the scale and orientation of the proposal distribution using differential evolution (Vrugt et al. 2008) (Vrugt et al. 2009). The algorithm maintains detailed balance and ergodicity and is generally superior to other adaptive MCMC sampling approaches, especially in the presence of high-dimensionality and multimodality. This algorithm is a follow up on the SCEM-UA global optimization algorithm (Vrugt et al. 2003) (which is available upon request) and is especially designed to take full advantage of the power of distributed computer networks.

The DREAM MATLAB toolbox provides scientists and engineers with an arsenal of options and utilities to solve posterior sampling problems involving (among others) bimodality, high-dimensionality, summary statistics, bounded parameter spaces, dynamic simulation models, formal/informal likelihood functions, diagnostic model evaluation, data assimilation, Bayesian model averaging, distributed computation, and informative/noninformative prior distributions. The toolbox supports parallel computing and includes tools for convergence analysis of the sampled chain trajectories and post-processing of the results.

DOWNLOAD DREAM MATLAB CODE [ Use right mouse click (“save link as”) and after download rename extension .pdf to .rar and unzip using WinRAR – detailed instructions provided in Appendix A of DREAM manual ]

**DREAM _{(ZS)}** – Differential Evolution Adaptive Metropolis (DREAM) Markov chain Monte Carlo (MCMC) of the posterior probability density function. DREAM

_{(ZS)}is based on the original DREAM algorithm, but uses sampling from an archive of past states to generate candidate points in each individual chain (Vrugt et al. 2008) (Vrugt et al. 2009). Sampling from the past circumvents the need for a large number of parallel chains, designed to accelerate convergence for high-dimensional problems. Experience with DREAM

_{(ZS)}suggests that about three parallel chains are needed to appropriately explore the posterior pdf, reducing time required for burn-in. Moreover, DREAM

_{(ZS)}does not require outlier detection and removal, maintaining detailed balance at every single step in each of the parallel chains. Finally, DREAM

_{(ZS)}contains a snooker update to generate jumps beyond parallel direction updates and increase diversity of candidate points.

DOWNLOAD DREAM_{(ZS)} MATLAB CODE [ Use right mouse click (“save link as”) and after download rename extension .pdf to .rar and unzip using WinRAR – detailed instructions provided in Appendix A of DREAM manual ]

**MT-DREAM _{(ZS)}** – Multi-try variant of DREAM

_{(ZS)}that simultaneously creates multiple different proposal points in each individual chain using parallel direction and snooker sampling from an archive of past states (Laloy and Vrugt, 2012). This code is especially designed to speed-up posterior exploration of CPU-intensive simulation models and receives spectacular performance improvements over other adaptive MCMC approaches on a distributed computing network.

DOWNLOAD MT-DREAM_{(ZS)} MATLAB CODE [ Use right mouse click (“save link as”) and after download rename extension .pdf to .rar and unzip using WinRAR – detailed instructions provided in Appendix A of DREAM manual ]

**DREAM _{(D)}** – Special variant of DREAM tailored specifically for non-continuous, discrete, and combinatorial posterior parameter estimation problems (Vrugt and ter Braak, 2011). Classical examples of this type include the traveling salesman problem, resource allocation, Markov switching models (quantitative finance) and optimization of experimental design strategies (selecting one or multiple different measurement locations in time/space from a discrete set of possibilities). The DREAM

_{(D)}code includes two additional proposal distributions that involve random and directed swapping of coordinates of the parameter vector. The resulting moves are fully Markovian, and resolve the parameter space at fixed points.

DOWNLOAD DREAM_{(D)} MATLAB CODE [ Use right mouse click (“save link as”) and after download rename extension .pdf to .rar and unzip using WinRAR – detailed instructions provided in Appendix A of DREAM manual ]

**DREAM _{(ABC)}** – Approximate Bayesian Computation (ABC) using DREAM. This variant of DREAM for likelihood free inference and diagnostic model evaluation. The likelihood free approach was introduced in the statistical literature about three decades ago (Diggle and Gratton (1984) for cases when an explicit likelihood (objective) function is difficult to specify or cannot be justified. This class of methods is also referred to as Approximate Bayesian Computation (ABC) and is currently a “hot” topic in statistics. The key idea of ABC is that summary statistics of the calibration data coupled with a small tolerance,

*ε*should provide a good approximation of the posterior parameter distribution. This statistical methodology relaxes the need for an explicit likelihood function in favor of one or multiple different summary statistics rooted in systems/environmental theory that together have a clearer and more compelling diagnostic power than some average measure of the size of the error residuals (Vrugt and Sadegh, 2013) (Sadegh and Vrugt, 2013).

The DREAM_{(ABC)} methodology replaces the discrete (0/1) acceptance kernel of Population Monte Carlo (PMC) simulation with a continuous rule. Furthermore, Gibbs sampling (subspace search) dramatically enhances search efficiency in high-dimensional parameter spaces. Details of this procedure can be found in Sadegh and Vrugt (2014).

DOWNLOAD DREAM_{(ABC)} MATLAB CODE [ Use right mouse click (“save link as”) and after download rename extension .pdf to .rar and unzip using WinRAR – detailed instructions provided in Appendix A of DREAM manual ]

**DATA ASSIMILATION**

**Particle-DREAM:** Posterior state estimation using particle Markov chain Monte Carlo (MCMC) simulation. Particle-DREAM numerically approximates the evolving posterior state distribution, *p*_{θ}(**x**_{1:t}|**ỹ**_{1:t})_{t>1} using sequential Monte Carlo sampling and MCMC resampling with DREAM (Vrugt et al. 2013). An initial ensemble of particles is created from the prior state distribution, *p*(**x**_{0}). These particles are propagated forward by sampling from an importance density, and confronted with the next available observation using a likelihood function. This helps partition the state space into productive and unproductive regions. The importance weights of the individual particle trajectories are subsequently updated, and used to assess whether resampling is necessary. If the effective sample size has dropped below a user-defined threshold bad particles are relinquished and MCMC simulation with DREAM is used to create more promising trajectories that adequately capture the evolving posterior state distribution.

**P-DREAM _{(IP)}:** If the parameters are unknown, the prior density,

*p*(

*θ*) can be used simultaneously with the model state trajectories using inference of the joint density,

*p*(

*θ*,

**x**

_{1:t}|

**ỹ**

_{1:t}) ∝

*p*(

*θ*)

*p*

_{θ}(

**x**

_{1:t}|

**ỹ**

_{1:t}). This implementation assumes the parameters to be time-invariant. The key idea is to run Particle-DREAM with a number of different Markov chains (Vrugt et al. 2013). These chains are generated with DREAM and used to generate samples from the posterior parameter distribution. Each time a candidate point,

*θ*

^{i}, is created in each individual chain, Particle-DREAM is used to resolve the state estimation problem and approximate

*p*

_{θi}(

**x**

_{1:t}|

**ỹ**

_{1:t}). The marginal likelihood,

*p*

_{θi}(

**ỹ**

_{1:t}) is then used to decide whether to accept the proposal or not. This filter draws from our previous SODA work (see below), but implements some important changes to make sure that the filter converges to the exact posterior parameter and state distribution.

**P-DREAM _{(VP)}:** The P-DREAM

_{(IP)}filter assumes the model parameters to be invariant. This hypothesis is convenient, but might not be justified when the system of interest experiences functional changes. One way to account for this nonstationarity is to allow the parameters to vary dynamically with time. We therefore introduce an alternative variant of Particle-DREAM, called P-DREAM

_{(VP)}that considers the model parameters to be time-variant and approximates the joint density,

*p*(

*θ*

_{1:t},

**x**

_{1:t}|

**ỹ**

_{1:t})

_{t>1}using state augmentation (Vrugt et al. 2013).

**SODA:** Simultaneous Optimization and Data Assimilation method. This method consist of an inner Ensemble Kalman Filter (EnKF) loop for recursive state estimation conditioned on an assumed parameter set, and an outer global optimization loop (SCEM-UA) for batch estimation of the high probability region of the posterior density of the parameters (Vrugt et al. 2005) (Vrugt et al. 2005) (Vrugt et al. 2006) . This approach improves the treatment of model structural model and input error during calibration, and the time series of sequential state updates (innovations) creates inspiration for model structural improvements.

**SINGLE OBJECTIVE OPTIMIZATION**

**AMALGAM-SO:** A Multi ALgorithm Genetically Adaptive Method for Single Objective Optimization. This method simultaneously merges the strengths of the Covariance Matrix Adaptation (CMA) evolution strategy, Genetic Algorithm (GA) and Particle Swarm Optimizer (PSO) for population evolution and implements a self-adaptive learning strategy to automatically tune the number of offspring these three individual algorithms are allowed to contribute during each generation (Vrugt et al. 2009). Simulation results have shown that AMALGAM-SO scales well with increasing number of dimensions, converges in the close proximity of the global minimum for functions with noise induced multimodality. The method is especially designed to take full advantage of the power of distributed computer networks.

**AMALGAM** – A Multi ALgorithm Genetically Adaptive Method for multiobjective optimization. This method runs multiple different search strategies simultaneously for population evolution (NSGA-II, Differential Evolution, Adapive Metropolis Sampling, and Particle Swarm Optimization) and adaptively updates the preference of each of these individual methods based on their reproductive success (Vrugt and Robinson, 2007) . This ensures a fast,reliable and computationally efficient solution to multiobjective optimization problems. This algorithm is a follow up on the MOSCEM-UA global optimization algorithm (Vrugt et al. 2003) (can be obtained upon request) and is especially designed to take full advantage of the power of distributed computer networks.

The MATLAB toolbox of AMALGAM provides scientists and engineers with an arsenal of options and utilities to solve multiobjective optimization problems involving (among others) multimodality, high-dimensionality, bounded parameter spaces, dynamic simulation models, and distributed multi-core computation. The AMALGAM toolbox supports parallel computing to permit inference of CPU-intensive system models, and provides convergence diagnostics and graphical output. Four different case studies are used to illustrate the main capabilities and functionalities of the AMALGAM toolbox.

DOWNLOAD AMALGAM MATLAB CODE [ Use right mouse click (“save link as”) and after download rename extension .pdf to .rar and unzip using WinRAR – detailed instructions provided in Appendix A of AMALGAM manual ]

**MODELAVG** – Predictive uncertainty analyses are typically carried out using a single conceptual model of the system under consideration, rejecting a priori valid alternative plausible models and possibly underestimating uncertainty in the model itself (Vrugt et al. 2006) (Vrugt and Robinson, 2007) . Model averaging is a statistical methodology that is frequently utilized in the statistical and meteorological literature to account explicitly for conceptual model uncertainty. The motivating idea behind model averaging is that, with various competing models at hand, each having its own strengths and weaknesses, it should be possible to combine the individual model forecasts into a single new forecast that, up to one’s favorite standard, is at least as good as any of the individual forecasts.

The MODELAVG toolbox implements a suite of different model averaging techniques, including (among others) equal weights averaging (EWA), Bates-Granger model averaging (BGA), Bayesian model averaging (BMA), Mallows model averaging (MMA), and Granger-Ramanathan averaging (GRA). The toolbox returns the posterior distribution of the weights and associated parameters of each model averaging method, along with graphical output of the results. Markov chain Monte Carlo simulation with the DREAM algorithm is used for Bayesian inference (Vrugt et al. 2008) within the context of BMA and MMA. The MODELAVG toolbox enables users to choose different conditional (forecast) distributions for the ensemble members (Gaussian, Gamma) with a homoscedastic (constant) or heteroscedastic (non-constant) variance.

DOWNLOAD MODELAVG MATLAB CODE [ Use right mouse click (“save link as”) and after download rename extension .pdf to .rar and unzip using WinRAR – detailed instructions provided in Appendix A of MODELAVG manual ]

NOTE: The original BMA approach presented by Raftery et al. (2005) assumes that the conditional pdf of each individual model is adequately described with a rather standard Gaussian or Gamma statistical distribution, possibly with a heteroscedastic variance. A paper by (Rings et al. 2012) analyzed the advantages of using BMA with a flexible representation of the conditional pdf using a joint Particle-DREAM, BMA and Gaussian mixture modeling framework. The conditional pdf of each ensemble member was derived from the forecast pdf derived with Particle-DREAM.

**OTHERS**

**GLUE:**: Generalized Likelihood Uncertainty Estimation. This methodology (philosophy), originally developed by Beven and coworkers (Beven and Binley, 1992; Beven, 2006), provides an alternative to formal Bayesian approaches for situations in which simple statistical assumptions regarding the distributional properties of the error residuals cannot be justified. To this end, it uses an informal likelihood measure to avoid over conditioning and exclude parts of the model (parameter) space that might provide acceptable fits to the data and be useful in prediction. The standard GLUE method uses a rather inefficient (Latin Hypercube) sampling methodology to find the acceptable solutions. This package implements Markov chain Monte Carlo simulation with DREAM to significantly speed up computationally efficiency (Blasone et al. 2008) . The interested reader is also referred to (Vrugt and Beven, 2016) for a demonstration how the DREAM_{(ABC)} package can be used to sample limits of acceptability. Details of this procedure can be found in Sadegh and Vrugt (2014).

**DE-MC:**: Differential Evolution Markov Chain. MATLAB implementation of the algorithm developed by Cajo ter Braak (2006). This code can be activated within DREAM by changing a few values of the algorithmic variables.

**MOCOM-UA:**: MultiObjective COMplex evolution algorithm. MATLAB implementation of the algorithm developed by Yapo et al. (1998).

**SCE-UA:**: Shuffled Complex Evolution optimization algorithm. MATLAB implementation of the algorithm developed by Duan et al. (1990).

**ABC-PMC** Population Monte Carlo sampling. This is similar as a simple rejection (aka importance sampling) algorithm but adaptively updates the covariance of the multinormal proposal distribution by sequentially decreasing the value of *ε*. This significantly enhances sampling efficiency (Vrugt and Sadegh, 2013).

**ABC-GLUE** Implementation that is similar to GLUE. The methodology uses population Monte Carlo simulation with continuous updating of the covariance of the multinormal proposal distribution by adaptively decreasing the value of *ε*. Details of this methodology can be found in (Sadegh and Vrugt, 2013).

## R Packages

**DREAM:** https://r-forge.r-project.org/projects/dream/

**BMA:** http://cran.r-project.org/web/packages/BMA/index.html

## Python Packages

**DREAM:** http://pypi.python.org/pypi/multichain_mcmc/0.2.2

## Fortran Packages

**DREAM:**Fortran90 version by Guannan Zhang

## Other Languages

Many of my MATLAB codes have been translated by others in other commonly used languages (C, C++, Fortran, R, Python). This involves much older versions than the MATLAB codes I distribute – some of these codes can be downloaded directly from this page. I do not keep track of the translated codes – in part because I cannot also support these codes and because this involves much older versions with far fewer options and capabilities (see latest versions of manuals).

## Parallel Computation

The MATLAB codes I develop use the MATLAB distributed computing toolbox. This is a built-in functionality that is easy to request in the DREAM and AMALGAM packages if running in Windows and provides a reasonable speed up as most of the time is typically spent in the plugin model of the user and not the MATLAB code itself. Please refer to Laloy and Vrugt (2012) for a distributed implementation of the DREAM package, and Vrugt et al. (2006) for an openMPI implementation of the SCEM-UA algorithm in Octave. I would recommend to use DREAM Suite for distributed Bayesian inference. This C++ based solver provides an excellent speed-up which facilitates inference of complex CPU-intensive physics models. DREAM Suite is readily linked to many different programming languages and allows users to work with their own existing plugin codes.