Update readme (#6)

* Add description of G-PCCA method.

* Add some usage info.

* fix style

* render pyGPCCA italic

* Fix linting errors

* Add partial installation instructions

* Add some description of slepc/petsc

* Fix typos

* Fix indentation

* add cite badge

* Remove TODOs, fix linting

* update paper badge

* [ci skip] Fix linting

* Fix functools error.

* Add more keywords.

* Do not warn on usused type: ignore

Co-authored-by: Bernhard Reuter <43750470+msmdev@users.noreply.github.com>
Co-authored-by: Marius Lange <marius.lange@t-online.de>
Co-authored-by: Bernhard Reuter <bernhard-reuter@gmx.de>

.mypy.ini

@@ -1,7 +1,7 @@
 [mypy]
 warn_redundant_casts = True
 warn_unused_configs = True
-warn_unused_ignores = True
+warn_unused_ignores = False
 
 disallow_untyped_calls = True
 disallow_untyped_defs = True

.scripts/ci/install_dependencies.sh

@@ -10,6 +10,7 @@ function install_petsc_macos {
     ./configure --with-cc=mpicc --with-cxx=mpicxx --with-debugging=0 --with-mpi=1
     make all
     make check
+    # make install  # only to move the files into the appropriate location
 
     popd
 }
@@ -22,6 +23,7 @@ function install_slepc_macos {
     ./configure --with-arpack-dir=/usr/local/Cellar/arpack
     make all
     make check
+    # make install  # only to move into the appropriate location
 
     popd
 }
@@ -41,6 +43,7 @@ elif [[ "$RUNNER_OS" == "macOS" ]]; then
 
     popd
 
+    # this seems to be only necessary on the CI
     echo "Symlinking numpy"
     python -m pip install --upgrade pip
     pip install numpy

README.rst

@@ -1,15 +1,138 @@
-|PyPI| |Conda| |CI| |Coverage|
+|PyPI| |Conda| |CI| |Coverage| |Cite|
 
 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.
+
 Installation
 ------------
-To install the development version of *pyGPCCA* from GitHub, run::
+We support multiple ways of installing *pyGPCCA*. If any problems arise during the installation,
+please refer to `Installation troubleshooting`_.
+
+Conda
+=====
+*pyGPCCA* is available as a `conda package <https://anaconda.org/conda-forge/pygpcca>`_ 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 the leading Schur vectors. These are optional
+dependencies - if they're not present, we compute a full Schur decomposition instead and sort it using the method
+introduced by `Brandts (2002)`_. Note that this scales cubically in sample number, making it essential to use
+`PETSc`_/`SLEPc`_ for large sample numbers. `PETSc`_/`SLEPc`_ implement iterative methods to only compute
+the leading Schur vectors, which is computationally much less expensive.
+
+PyPI
+====
+In order to install *pyGPCCA* from `The Python Package Index <https://pypi.org/project/pygpcca/>`_, run::
+
+    pip install pygpcca
+    # or with libraries utilizing PETSc/SLEPc
+    pip install pygpcca[slepc]
+
+Development version
+===================
+If you want to use the development version of *pyGPCCA* from `GitHub <https://github.com/msmdev/pygpcca>`_, run::
 
     pip install git+https://github.com/msmdev/pygpcca
 
+Usage
+-----
+Afterwards *pyGPCCA* can be imported in Python as::
+
+  import pygpcca as gp
+
+*pyGPCCA* can be used as outlined in the following:
+
+- Initialize a GPCCA object with a transition matrix ``P``::
+
+    gpcca = gp.GPCCA(P)
+
+- Get a list of minChi values for numbers of macrostates ``m`` in an interval ``[2, 30]`` to determine an interval
+  ``[m_min, m_max]`` of (nearly) optimal numbers of macrostates for clustering::
+
+    minChi_list = gpcca.minChi(2, 30)
+
+- Optimize the clustering for numbers of macrostates ``m`` in the previously determined interval ``[m_min, m_max]`` and
+  find the optimal number of macrostates ``n_metastable`` in the given interval::
+
+    gpcca.optimize({'m_min':2, 'm_max':10})
+
+- Afterwards, the optimal number of macrostates ``n_metastable`` can be accessed via::
+
+    gpcca.n_metastable
+
+- The optimal coarse-grained matrix can be accessed via::
+
+    gpcca.coarse_grained_transition_matrix
+
+- The memberships are available via::
+
+    gpcca.memberships
+
+Installation troubleshooting
+----------------------------
+During the installation of ``petsc``, ``petsc4py``, ``slepc``, and ``slepc4py``, the following error(s) might appear::
+
+    ERROR: Failed building wheel for <package name>
+
+However, this should be fine if in the end, it also outputs::
+
+    Successfully installed <package name>
+
+To quickly verify that the packages have been installed, you can run::
+
+    python3 -c "import petsc4py; import slepc4py; print(petsc4py.__version__, slepc4py.__version__)"
+
+Debian-based systems
+====================
+Below are an alternative steps for installing `PETSc`_/`SLEPc`_, in case any problems arise, especially when installing
+from `PyPI`_::
+
+    # install dependencies
+    sudo apt-get update -y
+    sudo apt-get install gcc gfortran libopenmpi-dev libblas-dev liblapack-dev petsc-dev slepc-dev -y
+
+    # install a message passing interface for Python
+    pip install --user mpi4py
+
+    # install petsc and and petsc4py
+    pip install --user petsc
+    pip install --user petsc4py
+
+    # install slepc and slepc4py
+    pip install --user slepc
+    pip install --user slepc4py
+
+macOS
+=====
+The most robust way is to follow the `PETSc installation guide`_ and the `SLEPc installation guide`_ or to take a look
+at our continuous integration `steps <./.scripts/ci/install_dependencies.sh>`_ for macOS.
+
+The installation steps can be roughly outlined as::
+
+    # install dependencies
+    brew install gcc open-mpi openblas lapack arpack
+
+    # follow the PETSc installation steps
+    # follow the SLEPc installation steps
+
+    # install petsc4py
+    pip install --user petsc4py
+    # install slepc4py
+    pip install --user petsc4py
+
 .. |PyPI| image:: https://img.shields.io/pypi/v/pygpcca
     :target: https://pypi.org/project/pygpcca
     :alt: PyPI
@@ -25,3 +148,13 @@ To install the development version of *pyGPCCA* from GitHub, run::
 .. |Coverage| image:: https://img.shields.io/codecov/c/github/msmdev/pygpcca/main
     :target: https://codecov.io/gh/msmdev/pygpcca
     :alt: Coverage
+
+.. |Cite| image:: https://img.shields.io/badge/DOI-10.1021%2Facs.jctc.8b00079-blue
+    :target: https://doi.org/10.1021/acs.jctc.8b00079
+    :alt: Cite
+
+.. _`PETSc`: https://www.mcs.anl.gov/petsc/
+.. _`SLEPc`: https://slepc.upv.es/
+.. _`Brandts (2002)`: https://doi.org/10.1002/nla.274
+.. _`PETSc installation guide`: https://www.mcs.anl.gov/petsc/documentation/installation.html
+.. _`SLEPc installation guide`: https://slepc.upv.es/documentation/instal.htm

pygpcca/_gpcca.py

@@ -33,7 +33,7 @@
 from typing import Dict, List, Tuple, Union, Callable, Optional, TYPE_CHECKING
 
 try:
-    from functools import cached_property
+    from functools import cached_property  # type: ignore[attr-defined]
 except ImportError:
     from functools import lru_cache
 

pygpcca/_sorted_schur.py

@@ -4,8 +4,9 @@
 # With contributions of Marius Lange and Michal Klein.
 # Based on the original MATLAB GPCCA code authored by Bernhard Reuter, Susanna Roeblitz and Marcus Weber,
 # Zuse Institute Berlin, Takustrasse 7, 14195 Berlin
-# We like to thank A. Sikorski and M. Weber for pointing us to SLEPc for partial Schur decompositions of sparse matrices.
-# Further parts of sorted_krylov_schur were developed based on the function krylov_schur 
+# We like to thank A. Sikorski and M. Weber for pointing us to SLEPc for partial Schur decompositions of
+# sparse matrices.
+# Further parts of sorted_krylov_schur were developed based on the function krylov_schur
 # https://github.com/zib-cmd/cmdtools/blob/1c6b6d8e1c35bb487fcf247c5c1c622b4b665b0a/src/cmdtools/analysis/pcca.py#L64,
 # written by Alex Sikorski, as a prototype.
 # --------------------------------------------------
@@ -210,8 +211,9 @@ def sorted_krylov_schur(
         Array of shape `(k,)` containing the error, based on the residual
         norm, of the `i`th eigenpair at index `i`.
     """  # noqa: D205, D400
-    # We like to thank A. Sikorski and M. Weber for pointing us to SLEPc for partial Schur decompositions of sparse matrices.
-    # Further parts of sorted_krylov_schur were developed based on the function krylov_schur 
+    # We like to thank A. Sikorski and M. Weber for pointing us to SLEPc for partial Schur decompositions of
+    # sparse matrices.
+    # Further parts of sorted_krylov_schur were developed based on the function krylov_schur
     # https://github.com/zib-cmd/cmdtools/blob/1c6b6d8e1c35bb487fcf247c5c1c622b4b665b0a/src/cmdtools/analysis/pcca.py#L64,
     # written by Alex Sikorski, as a prototype.
     from petsc4py import PETSc

setup.py

@@ -67,8 +67,23 @@
     keywords=sorted(
         {
             "GPCCA",
+            "G-PCCA",
             "Generalized Perron Cluster Cluster Analysis",
             "Markov state model",
+            "Markov state modeling",
+            "coarse-graining",
+            "spectral clustering",
+            "non-equilibrium system",
+            "non-reversible process",
+            "non-autonomous process",
+            "cyclic states",
+            "metastable states",
+            "molecular dynamics",
+            "cellular dynamics",
+            "molecular kinetics",
+            "cellular kinetics",
+            "Schur decomposition",
+            "Schur vectors",
         }
     ),
 )