Welcome to pyREVS’s documentation!

pyREVS is a modular implementation of rare-event sampling algorithms in stochastic dynamical systems. Initially focused on Trajectory-adaptive Multilevel Splitting (TAMS), pyREVS is now amendable to other algorithms of the Importance Splitting (IS) family. pyREVS was developed to specifically handle (computationally) expensive stochastic models, where integrating the model can take hours to days on supercomputers and using a naive Monte-Carlo approach is impractical.

Warning

PR#173 introduced significant changes to the source code and API, as well as the scope of the package. The documentation has been mostly updated, but might still refers solely to TAMS or pyTAMS in some locations. Please report any issues to the GitHub repository

Installation:

To install pyREVS, simply use pip in your favorite environment manager to get the latest stable version:

pip install pyrevs

or if you plan on modifying the code or test the shipped-in examples, install from sources:

git clone git@github.com:nlesc-eTAOC/pyREVS.git
cd pyREVS
pip install -e .

Quick start:

Only if you have used the second option above you can readily test pyREVS on a simple problem:

cd pyREVS/examples/DoubleWell2D
python sample_dw2dim.py

otherwise, please read through this documentation and in particular follow the tutorials Section to see how to implement your own model within pyREVS.

User guide:

• Theory
  • Stochastic dynamical systems
  • Rare events
  • Adaptive multilevel splitting
  • Trajectory-adaptive multilevel splitting
  • TAMS algorithm
  • Simple 1D double well
• Validation
  • 1D Ornstein-Uhlenbeck process
  • 2D double well case
• Usage
  • Running pyREVS
  • Controls
  • Accessing the database
• Tutorials
  • 1D double well
  • Bi-channel problem
  • 2D Boussinesq model

Developer guide:

• Implementation
  • Data structures & storage
  • Workers & parallelism
  • Algorithm
• Extension
• pyrevs
  • Submodules

Documentation

The documentation pages are distributed with the code in the docs folder as “reStructuredText” files. The HTML is built automatically whenever changes are pushed to the main branch on GitHub. A local version can also be built as follows:

cd <pyREVS_root_folder>/docs
make html

Indices and tables

• Index

• Module Index

• Search Page