Skip to content

Commit

Permalink
updates readme file for v0.2.1
Browse files Browse the repository at this point in the history
  • Loading branch information
thibhlln committed Aug 24, 2019
1 parent 62cafb2 commit 6a200a2
Showing 1 changed file with 2 additions and 22 deletions.
24 changes: 2 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,37 +67,17 @@ Mockler, E., O’Loughlin, F., and Bruen, M.: Understanding hydrological flow pa

SMARTpy is designed to read CSV (Comma-Separated Values) files and NetCDF (Network Common Data Form) input files (for rain, peva, and flow), as well as to write CSV and NetCDF output files (for discharge series, and monte carlo simulation results). However, the use of NetCDF files requires the Python package `netCDF4` to be installed on the Python implementation where SMARTpy is installed (specific pre-requisites prior the installation of `netCDF4` exist and can be found at [unidata.github.io/netcdf4-python](http://unidata.github.io/netcdf4-python/)).

## Objective Functions

For single simulations in SMARTpy, if observed discharge timeseries are available, the performance of the simulation can be assessed with a set of 8 objective functions:
* Nash-Sutcliffe Efficiency (NSE)
* Nash-Sutcliffe Efficiency on the log discharge series (lgNSE)
* Nash-Sutcliffe Efficiency on the square root discharge series (rtNSE)
* Bounded Nash-Sutcliffe Efficiency (C2M)
* Kling-Gupta Efficiency (KGE)
* Spearman Rank Correlation Coefficient (Rho)
* Mean Absolute Relative Error (MARE)
* Percent Bias (PBias)
* Ground Water contribution to run-off (GW) [specific to the SMART model]

For Monte Carlo simulations in SMARTpy, the 8 objective functions above will be calculated, as well as 4 additional objective functions available from `spotpy`:
* The three components of the Kling-Gupta Efficiency
* correlation coefficient c: error in dynamics (KGEc)
* alpha: error in variability (KGEa)
* central tendency beta: error in volume (KGEb)
* Root Mean Square Error (RMSE)
* Bias (Bias)

## Monte Carlo Simulations

The `montecarlo` suite of classes that comes with `smartpy` gives access to various options for Monte Carlo simulations. The parameter space of the SMART model can be explored using Latin Hypercube Sampling (`LHS`) for any sample size required. Once the sampling is complete for on a given simulation period, the performance of the whole set of parameter sets can be evaluated on another simulation period with `Total`, or the set of parameter sets can be conditioned according to their own performances against observed discharge data on any of the objective function(s) calculated by SMARTpy (using `GLUE` to distinguish from behavioural and non-behavioural parameter sets, or using `Best` to retain a pre-defined number of best performing samples) and the resulting subset of parameter sets can be evaluated on another simulation period.

## Parallel Computing

If Monte Carlo simulations are required, it is important to make use of the available computer power to reduce the runtime. Personal Computers now commonly feature several processor cores that can be used to run as many run of the SMART model in parallel (*i.e.* at the same time), not to mention High Performance Clusters, where the benefits of parallel computing will be even more significant. The `montecarlo` classes of `smartpy` are using the `spotpy` package to give access to an easy way to run simulations in parallel. `spotpy` itself requires `mpi4py` to operate, which applies to `smartpy` by extension. So before using `montecarlo` with `parallel='mpi'`, a Message Passing Interface (MPI) library (*e.g.* Open MPI) and `mpi4py` need to be installed on your machine, and `spotpy` needs to be installed too. Any of the `montecarlo` classes can take an optional argument parallel, its default value is set to 'seq' (for sequential computing), but can be set to 'mpi' if your setup allows it.
If Monte Carlo simulations are required, it is important to make use of the available computer power to reduce the runtime. Personal Computers now commonly feature several processor cores that can be used to run as many runs of the SMART model in parallel (*i.e.* at the same time), not to mention High Performance Clusters, where the benefits of parallel computing will be even more significant. The `montecarlo` classes of `smartpy` are using the `spotpy` package to give access to an easy way to run simulations in parallel. `spotpy` itself requires `mpi4py` to operate, which applies to `smartpy` by extension. So before using `montecarlo` with `parallel='mpi'`, a Message Passing Interface (MPI) library (*e.g.* Open MPI) and `mpi4py` need to be installed on your machine, and `spotpy` needs to be installed too. Any of the `montecarlo` classes can take an optional argument parallel, its default value is set to 'seq' (for sequential computing), but can be set to 'mpi' if your setup allows it (for parallel computing).

## Version History

* 0.2.1 [24 Aug 2019]: [General enhancements](https://github.com/ThibHlln/smartpy/releases/tag/v0.2.1)
* 0.2.0 [16 Nov 2018]: [Speed improvement by making use of new version of SMARTcpp](https://github.com/ThibHlln/smartpy/releases/tag/v0.2.0)
* 0.1.4 [12 Nov 2018]: [General enhancements](https://github.com/ThibHlln/smartpy/releases/tag/v0.1.4)
* 0.1.3 [24 Jul 2018]: [Version improved for Monte Carlo simulations with parallel computing](https://github.com/ThibHlln/smartpy/releases/tag/v0.1.3)
Expand Down

0 comments on commit 6a200a2

Please sign in to comment.