pyrevs 1.1.0

A package for exploring rare-events in high-dimensional dynamical systems

pyREVS: python Rare-EVent Sampling package

Overview

Rare-events algorithms are powerful techniques allowing to sample rare occurrences of a computational model at a much lower cost than brute force Monte-Carlo. However, running such algorithms on models featuring more than a handfull of dimensions become cumbersome as both compute and memory requirements increase. pyREVS is a modular implementation of rare-event algorithms, initially focused on adaptive multilevel splitting (AMS) and its TAMS variant introduced by Lestang et al., aiming at alleviating the difficulty of performing rare event algorithms on high-dimensional systems such as the ones encountered in geophysical or engineering applications. The package is built from basic building blocks that can be used to implement new rare-event algorithms.

Installation

To install pyREVS from GitHub repository, do:

git clone [e-mail]:nlesc-eTAOC/pyREVS.git
cd pyREVS
python -m pip install .

Note that the latest version of pyREVS is available on PyPI here and can be installed with pip install pyrevs, but built-in examples are not readily available using the PyPI version.

To run the example cases shipped with pyREVS, additional dependencies are required. To install the examples dependencies, run:

python -m pip install .[exec]

You can check that the package was successfully installed using:

pyrevs_check

Quick start

To get started with pyREVS, let's have a look at the classical double-well potential case. Although it is not a high-dimensional system, it provides a good overview of pyREVS capabilities. A 2D version of the double-well is available in the examples folder. To run the case, simply do:

cd examples/DoubleWell2D
python sample_dw2dim.py

This minimal example runs the TAMS 10 times in order to get an estimate of the transition probability as well as the corresponding relative error. For a more in-depth explanation about this case, setting up the model and running the simulations, have a look at the tutorial here.

Documentation

pyREVS documentation is hosted on GitHub here

Contributing

If you want to contribute to the development of pyREVS, have a look at the contribution guidelines.

Acknowledgements

The development of pyREVS was supported by the Netherlands eScience Center in collaboration with the Institute for Marine and Atmospheric research Utrecht IMAU.

This package was created with Cookiecutter and the NLeSC/python-template.