Skip to content

🦜 DISCOTRESS 🦜 is a software package to simulate and analyse the dynamics on arbitrary Markov chains

License

Notifications You must be signed in to change notification settings

danieljsharpe/DISCOTRESS

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

68 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

DISCOTRESS

Welcome to the DISCOTRESS (DIscrete State COntinuous Time Rare Event Simulation Suite) program, developed by Daniel J. Sharpe.

Getting from B to A in a Markov chain

Probability fluxes (edge thickness), visitation probabilities (node opacity), and stationary probabilities (node size) for the transition from an initial set of nodes, 𝔅, to an absorbing (target) set of nodes, 𝔄, in a Markov chain.

DISCOTRESS is a software package to simulate and analyse the dynamics for arbitrary Markov chains. DISCOTRESS is designed to enable simulation and analysis of the dynamics for discrete- and continuous-time finite Markov chains (DTMCs and CTMCs, respectively) that are nearly reducible. Such Markov chains exhibit strong metastability; that is, there exists a comparatively slow (i.e. low probability) process. In this rare event regime, which is frequently encountered in realistic modeling tasks, standard simulation algorithms are unfeasible owing to their inefficiency, and linear algebra methods for the exact computation of dynamical quantities fail to converge or lead to a severe propagation of numerical error. The advanced methods implemented in DISCOTRESS circumvent these problems.

Discrete-state DTMCs and CTMCs are widely applied models for the stochastic dynamics of many processes. Markov chains are commonly used to represent populations of species in and animal movement within an ecosystem 🦜 🌴, epidemic spread 🦠 🦟, financial markets πŸ’Έ πŸ“ˆ, climate dynamics 🌦️ πŸŒͺ️, gene regulatory and other chemical reaction networks 🧬 πŸ§ͺ, as well as the dynamics of many-particle systems in condensed matter and biological physics βš›οΈ 🧫, and more!

What can I do with DISCOTRESS?

A host of simulation algorithms to sample paths are built in to DISCOTRESS [1,2], including standard kinetic Monte Carlo (BKL), kinetic path sampling (kPS), Monte Carlo with absorbing Markov chains (MCAMC), milestoning, and weighted ensemble (WE) sampling. The software also includes algorithms to perform exact numerical analysis. The flexibility of the software and the relative advantages of the different algorithms allow for a variety of problems to be solved. DISCOTRESS can be used to:

  • sample the ensemble of 𝔄 ← 𝔅 first passage paths (the FPPE) from an initial set of nodes in the Markov chain, denoted 𝔅, to an absorbing (target) set of nodes, denoted 𝔄 [1,2].
  • simulate probability distributions of path properties for the 𝔄 ← 𝔅 FPPE, including the first passage time (FPT) [1,2], path probability [4], and entropy flow distributions of paths.
  • simulate statistics associated with nodes (or groups thereof) for the ensemble of direct 𝔄 ← 𝔅 transition paths (the TPE), namely committor and visitation probabilities [1,2]. These quantities can be calculated for both the nonequilbrium and equilibrium (steady state) TPEs [3].
  • obtain dynamical quantities characterising the 𝔄 ← 𝔅 nonequilibrium and equilibrium FPPE and TPE exactly, including MFPTs, committor and absorption probabilities, expected numbers of node visits, and node visitation probabilities, using numerically stable state reduction methods [2,3,5].
  • obtain dynamical quantities characterising the dynamics in the infinite-time limit, namely the stationary distribution and the average mixing time, using numerically stable state reduction methods [2,3].
  • determine the set of 𝔄 ← 𝔅 first passage paths with the highest probabilities, using a k shortest paths algorithm [4].
  • estimate and validate a coarse-grained Markov chain constructed from multiple short nonequilibrium trajectories [6].

How do I get started?

Requirements: C++17
Dependencies: OpenMP

Refer to the documentation for a list of keywords that may be included in the main input file input.kmc, a description of the other input and output files and their formats, and instructions for downloading and compiling the software.

Try running the tutorial examples to get started!

Use the available analysis scripts to find out what it all means.

Read the FAQs for hints and tips.

Citations

If you use the DISCOTRESS software in your publication, please cite the following articles:

Please cite relevant articles describing particular functionality of DISCOTRESS if you use these features:

Further example applications can be found in the following publications:

More publications for DISCOTRESS are forthcoming.

Please contact me directly to obtain copies of preprints.

For additional citations related to the various simulation and state reduction algorithms implemented in DISCOTRESS, please see the individual .cpp files in the source code.

Contact the author

Would you like to request a new feature in DISCOTRESS? Or simply have a question? Get in touch:

daniel.j.sharpe1995@gmail.com