Improve RTD and README (#15)

* Ask to cite JCTC (2018) in index.rst.

* Add License badge to index.rst.

* Add Download badges to index.rst.

* Add F. Paul to __credits__.

* Add Acknowledgements to RTD.

* Add Acknowledgements to README.rst.

* Incorporate README.rst into index.rst.

* Include Reference to SRSchur.

README.rst

@@ -1,4 +1,36 @@
-|PyPI| |Conda| |Cite| |CI| |Docs| |Coverage|
+|PyPI| |Conda| |Cite| |CI| |Docs| |Coverage| |License| |PyPIdownloads|
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/pygpcca
+    :target: https://pypi.org/project/pygpcca/
+    :alt: PyPI
+
+.. |Conda| image:: https://img.shields.io/conda/vn/conda-forge/pygpcca
+    :target: https://anaconda.org/conda-forge/pygpcca
+    :alt: Conda
+
+.. |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
+
+.. |CI| image:: https://img.shields.io/github/workflow/status/msmdev/pygpcca/CI/main
+    :target: https://github.com/msmdev/pygpcca/actions
+    :alt: CI
+
+.. |Docs|  image:: https://img.shields.io/readthedocs/pygpcca
+    :target: https://pygpcca.readthedocs.io/en/latest
+    :alt: Documentation
+
+.. |Coverage| image:: https://img.shields.io/codecov/c/github/msmdev/pygpcca/main
+    :target: https://codecov.io/gh/msmdev/pygpcca
+    :alt: Coverage
+
+.. |License| image:: https://img.shields.io/github/license/msmdev/pyGPCCA?color=green
+    :target: https://github.com/msmdev/pyGPCCA/blob/main/LICENSE.txt
+    :alt: License
+
+.. |PyPIdownloads| image:: https://static.pepy.tech/personalized-badge/requests?period=total&units=international_system&left_color=grey&right_color=blue&left_text=pypi%20downloads
+    :target: https://pepy.tech/project/requests
+    :alt: PyPI - Downloads
 
 pyGPCCA - Generalized Perron Cluster Cluster Analysis
 =====================================================
@@ -15,6 +47,10 @@ utilizing real Schur vectors instead of eigenvectors. |br|
 *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)`_.
+
+.. _JCTC (2018): https://pubs.acs.org/doi/abs/10.1021/acs.jctc.8b00079
+
 Installation
 ------------
 We support multiple ways of installing *pyGPCCA*. If any problems arise, please consult the
@@ -30,6 +66,8 @@ Conda
 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)
 
+.. _`PETSc`: https://www.mcs.anl.gov/petsc/
+
 PyPI
 ++++
 In order to install *pyGPCCA* from `The Python Package Index <https://pypi.org/project/pygpcca/>`_, run::
@@ -42,32 +80,28 @@ Example
 -------
 Please refer to our `example usage <https://pygpcca.readthedocs.io/en/latest/example.html>`_ in the documentation.
 
-.. |PyPI| image:: https://img.shields.io/pypi/v/pygpcca
-    :target: https://pypi.org/project/pygpcca/
-    :alt: PyPI
-
-.. |Conda| image:: https://img.shields.io/conda/vn/conda-forge/pygpcca
-    :target: https://anaconda.org/conda-forge/pygpcca
-    :alt: Conda
-
-.. |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
-
-.. |CI| image:: https://img.shields.io/github/workflow/status/msmdev/pygpcca/CI/main
-    :target: https://github.com/msmdev/pygpcca/actions
-    :alt: CI
-
-.. |Docs|  image:: https://img.shields.io/readthedocs/pygpcca
-    :target: https://pygpcca.readthedocs.io/en/latest
-    :alt: Documentation
-
-.. |Coverage| image:: https://img.shields.io/codecov/c/github/msmdev/pygpcca/main
-    :target: https://codecov.io/gh/msmdev/pygpcca
-    :alt: Coverage
-
-.. _`PETSc`: https://www.mcs.anl.gov/petsc/
+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. |br|
+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.
+
+.. _`Marcus Weber`: https://www.zib.de/members/weber
+.. _`CMD`: https://www.zib.de/numeric/cmd
+.. _`ZIB`: https://www.zib.de/
+.. _`Fabian Paul`: https://github.com/fabian-paul
+.. _`SRSchur`: http://m2matlabdb.ma.tum.de/SRSchur.m?MP_ID=119
+.. _`Jan Brandts`: https://doi.org/10.1002/nla.274
+.. _`Python code`: https://gist.github.com/fabian-paul/14679b43ed27aa25fdb8a2e8f021bad5
+.. _`Alexander Sikorski`: https://www.zib.de/members/sikorski
 .. _`SLEPc`: https://slepc.upv.es/
+.. _`code example`: https://github.com/zib-cmd/cmdtools/blob/1c6b6d8e1c35bb487fcf247c5c1c622b4b665b0a/src/cmdtools/analysis/pcca.py#L64
 
 .. |br| raw:: html
 

docs/source/acknowledgements.rst

@@ -0,0 +1,22 @@
+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.
+
+.. _`Marcus Weber`: https://www.zib.de/members/weber
+.. _`CMD`: https://www.zib.de/numeric/cmd
+.. _`ZIB`: https://www.zib.de/
+.. _`Fabian Paul`: https://github.com/fabian-paul
+.. _`SRSchur`: http://m2matlabdb.ma.tum.de/SRSchur.m?MP_ID=119
+.. _`Jan Brandts`: https://doi.org/10.1002/nla.274
+.. _`Python code`: https://gist.github.com/fabian-paul/14679b43ed27aa25fdb8a2e8f021bad5
+.. _`Alexander Sikorski`: https://www.zib.de/members/sikorski
+.. _`SLEPc`: https://slepc.upv.es/
+.. _`code example`: https://github.com/zib-cmd/cmdtools/blob/1c6b6d8e1c35bb487fcf247c5c1c622b4b665b0a/src/cmdtools/analysis/pcca.py#L64

docs/source/index.rst

@@ -1,19 +1,5 @@
-|PyPI| |Conda| |Cite| |CI| |Docs| |Coverage|
-
-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. |br|
-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. |br|
-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. |br|
-*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.
+.. include:: ../../README.rst
+    :end-line: 60
 
 .. include:: _key_contributors.rst
 
@@ -25,32 +11,9 @@ under study. Utilizing *pyGPCCA*, metastable states as well as cyclic kinetics c
     installation
     api
     example
+    acknowledgements
     references
 
-.. |PyPI| image:: https://img.shields.io/pypi/v/pygpcca
-    :target: https://pypi.org/project/pygpcca/
-    :alt: PyPI
-
-.. |Conda| image:: https://img.shields.io/conda/vn/conda-forge/pygpcca
-    :target: https://anaconda.org/conda-forge/pygpcca
-    :alt: Conda
-
-.. |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
-
-.. |CI| image:: https://img.shields.io/github/workflow/status/msmdev/pygpcca/CI/main
-    :target: https://github.com/msmdev/pygpcca/actions
-    :alt: CI
-
-.. |Docs|  image:: https://img.shields.io/readthedocs/pygpcca
-    :target: https://pygpcca.readthedocs.io/en/latest
-    :alt: Documentation
-
-.. |Coverage| image:: https://img.shields.io/codecov/c/github/msmdev/pygpcca/main
-    :target: https://codecov.io/gh/msmdev/pygpcca
-    :alt: Coverage
-
 .. |br| raw:: html
 
   <br/>

pygpcca/_gpcca.py

@@ -33,6 +33,7 @@
     "Susanna Roeblitz",
     "Marius Lange",
     "Michal Klein",
+    "Fabian Paul",
     "Alexander Sikorski",
 ]