/pyGPCCA

pyGPCCA - python GPCCA: Generalized Perron Cluster Cluster Analysis package to coarse-grain reversible and non-reversible Markov State Models.

Primary LanguagePythonGNU Lesser General Public License v3.0LGPL-3.0

PyPI Conda Cite CI Documentation Coverage License PyPI - Downloads

pyGPCCA - Generalized Perron Cluster Cluster Analysis

Generalized Perron Cluster Cluster Analysis program to coarse-grain reversible and non-reversible Markov State Models.

Markov State Models (MSM) enable the identification and analysis of metastable states and related kinetics in a very instructive manner. They are widely used, e.g. to model molecular or cellular kinetics.
Common state-of-the-art Markov state modeling methods and tools are very well suited to model reversible processes in closed equilibrium systems. However, most are not well suited to deal with non-reversible or even non-autonomous processes of non-equilibrium systems.
To overcome this limitation, the Generalized Robust Perron Cluster Cluster Analysis (G-PCCA) was developed. The G-PCCA method implemented in the pyGPCCA program readily handles equilibrium as well as non-equilibrium data by utilizing real Schur vectors instead of eigenvectors.
pyGPCCA enables the semiautomatic coarse-graining of transition matrices representing the dynamics of the system under study. Utilizing pyGPCCA, metastable states as well as cyclic kinetics can be identified and modeled.

If you use pyGPCCA or parts of it, please cite JCTC (2018).

Installation

We support multiple ways of installing pyGPCCA. If any problems arise, please consult the troubleshooting section in the documentation.

Conda

pyGPCCA is available as a conda package and can be installed as:

conda install -c conda-forge pygpcca

This is the recommended way of installing, since this package also includes PETSc/SLEPc libraries. We use PETSc/SLEPc internally to speed up the computation of leading Schur vectors (both are optional).

PyPI

In order to install pyGPCCA from The Python Package Index, run:

pip install pygpcca
# or with libraries utilizing PETSc/SLEPc
pip install pygpcca[slepc]

Example

Please refer to our example usage in the documentation.

Key Contributors

Acknowledgements

We thank Marcus Weber and the Computational Molecular Design (CMD) group at the Zuse Institute Berlin (ZIB) for the longstanding and productive collaboration in the field of Markov modeling of non-reversible molecular dynamics. M. Weber, together with K. Fackeldey, had the original idea to employ Schur vectors instead of eigenvectors in the coarse-graining of non-reversible transition matrices.
Further, we would like to thank Fabian Paul for valuable discussions regarding the sorting of Schur vectors and his effort to translate the original Sorting routine for real Schur forms SRSchur published by Jan Brandts from MATLAB into Python code, M. Weber and Alexander Sikorski for pointing us to SLEPc for sorted partial Schur decompositions, and A. Sikorski for supplying us with an code example and guidance how to interface SLEPc in Python. The development of pyGPCCA started - based on the original GPCCA program written in MATLAB - at the beginning of 2020 in a fork of MSMTools, since it was planned to integrate GPCCA into MSMTools at this time. Due to this, some similarities in structure and code (indicated were evident) can be found. Futher the utility functions found in pygpcca/utils/_utils.py originate from MSMTools.