Introduction to Markov state modeling with the PyEMMA software

This work is licensed under a Creative Commons Attribution 4.0 International License.

PyEMMA (EMMA = Emma's Markov Model Algorithms) is an open source Python/C package for analysis of extensive molecular dynamics (MD) simulations.

Content

The first notebook 📓 in this tutorial guides through the basic analysis workflow using real MD data of a pentapeptide:

We keep the details minimal throughout the showcase but point to the more specialized notebooks which allow you to go in-depth on selected topics.

In detail, the remaining eight notebooks revisit all aspects shown in the showcase, provide additional details and variants, and contain exercises (and solutions) to self-check your learning progress:

1. Data-I/O and featurization ➜ 📓
2. Dimension reduction and discretization ➜ 📓
3. MSM estimation and validation ➜ 📓
4. MSM analysis ➜ 📓
5. PCCA and TPT analysis ➜ 📓
6. Expectations and observables ➜ 📓
7. Hidden Markov state models (HMMs) ➜ 📓
8. Common problems & bad data situations ➜ 📓

Please note that this is a work in progress and we value any kind of feedback that helps us improving this tutorial.

Installation

We recommended to install the PyEMMA tutorials with conda. The following command will create a new environment that comes with all the dependencies of the tutorial.

If you do not have conda, please follow the instructions here:

https://conda.io/miniconda.html

Installing the tutorials as a package

After installing miniconda, you can install the tutorial either via

conda create -n pyemma_tutorials -c conda-forge pyemma_tutorials

... or you can also install the tutorial in an existing environment by

conda install -c conda-forge pyemma_tutorials

If you intend to install with pip, for which can not give any support, you feel free to run:

pip install git+https://github.com/markovmodel/pyemma_tutorials

Manual installation

If you wish to install the tutorial manually, you will need the following packages (including all their dependencies):

• pyemma
• mdshare
• nglview
• nbexamples
• jupyter_contrib_nbextensions

This can be done, for example, with conda:

conda install -c conda-forge pyemma mdshare nglview nbexamples jupyter_contrib_nbextensions

After installing jupyter_contrib_nbextensions, you need to activate the toc2 and exercise2 extensions:

jupyter nbextension enable toc2/main
jupyter nbextension enable exercise2/main

Now all remains is to clone the repository to get the tutorial notebooks:

git clone https://github.com/markovmodel/pyemma_tutorials.git

Usage

Now we have a fresh conda environment containing the notebooks and the software to run them. We can now just activate the environment and run the notebook server by invoking:

conda activate pyemma_tutorials  # skip this, if you have installed in your root environment or used pip to install.
pyemma_tutorials

The last command will start the notebook server and your browser should pop up pointing to a list of notebooks. You can choose either to preview or to create your own copy of the notebook. The latter will create a copy of the chosen notebook in your home directory, so your changes will not be lost after shutting down the notebook server.

If you have a manual installation, move to the repository's notebook directory...

cd path_to_pyemma_tutorials/notebooks

... and start the notebook server there:

jupyter notebook

Deinstallation

To uninstall you can remove the whole environment which will also uninstall the contained software again:

conda env remove -n pyemma_tutorials

or if you have installed the package directly

conda remove pyemma_tutorials