DISCOTRESS tutorials

Learn to get started using DISCOTRESS with these tutorials, then apply the methods to your own Markov chains!

Numerical estimate of the 𝔄 ← 𝔅 first passage time (FPT) distribution from dynamical simulations; one of many quantities that can be computed using DISCOTRESS.

Finite Markov chains are network models that can be used to model phenomena as varied and exciting as:

• animal movement within an ecosystem, such as migration 🐦 🦜 or foraging 🐘 🌴
• the variation in populations of species within an ecosystem, for example arising from predator-prey interactions 🐺 🦌, competition for limited resources 🐻 🐟, or the introduction of a parasite 🦟 or invasive species 🐍
• the evolution of organisms or genes characterised by the fitness for their environment 🦒 🐢
• epidemic spread of a disease in a population 🦠 💉
• climate dynamics 🌦️ 🌪️
• the fluctuating status of financial markets 💸 📈
• social groups 👪 👫
• structural changes in molecular and condensed matter systems, for example a protein or DNA molecule folding to its functional shape 🧬 ⚛️
• the distribution of molecule copy numbers in biochemical or chemical reaction cycles or gene regulatory networks 🧪 🧫

We are typically interested in a particular 𝔄 ← 𝔅 first passage process on the Markov chain. That is, we wish to understand the dynamical process of first hitting an absorbing (target) set of nodes 𝔄 for paths beginning within the initial set of nodes 𝔅. We may want to know: what is the average time to reach the 𝔄 state? Which nodes are most likely to be visited along an 𝔄 ← 𝔅 path? How many times is each node visited along an 𝔄 ← 𝔅 path on average? If the 𝔄 ← 𝔅 transition is slow (i.e. low probability) compared to random fluctuations, then linear algebra methods to solve for exact dynamical properties are numerically unstable and the standard kinetic Monte Carlo method to simulate paths is inefficient and therefore unfeasible. DISCOTRESS includes implementations of advanced algorithms that negate these problems. The software is highly flexible, and can also be used to efficiently simulate long-timescale trajectories that are not conditioned on initial and target states.

Overview of tutorials

The following tutorials use simple example Markov chains to demonstrate various key features of the algorithms available in DISCOTRESS, allowing you to familiarise yourself with the capabilities and flexibility of the software:

• mfpt_ctmc: you will learn to exactly compute key dynamical properties characterising an 𝔄 ← 𝔅 transition in a continuous-time Markov chain (CTMC), using numerically stable state reduction algorithms. Namely: mean first passage times (MFPTs), committor and absorption probabilities, and the stationary distribution.
• mfpt_dtmc: repeats the same exercise for a discrete-time Markov chain (DTMC).
• kmc_ab: you will learn to use the standard kinetic Monte Carlo (kMC) algorithm to simulate 𝔄 ← 𝔅 paths.
• kps_ab: you will learn to use the kinetic path sampling (kPS) algorithm to simulate 𝔄 ← 𝔅 paths.
• kmc_steadystate: you will learn to use the kMC algorithm to simulate long trajectories of fixed time and extract steady-state (i.e. equilibrium) statistics for 𝔄 ← 𝔅 transition paths.
• dimredn: you will learn to use kinetic path sampling (kPS) to simulate many short nonequilibrium trajectories initialised from each community, from which a coarse-grained Markov chain can be estimated and validated.
• rea: you will learn to use the recursive enumeration algorithm (REA) to determine the k 𝔄 ← 𝔅 first passage paths associated with the highest probabilities.

Scripts to help you process the output of DISCOTRESS simulations are available here.