Merge pull request #51 from wehs7661/update_docs

Update the documentation of `ensemble_md`
wehs7661 · Apr 30, 2024 · 552573d · 552573d
2 parents a293ca6 + e2fb74a
commit 552573d
Show file tree

Hide file tree

Showing 24 changed files with 763 additions and 771 deletions.
diff --git a/docs/_static/REXEE_illustration.png b/docs/_static/REXEE_illustration.png
diff --git a/docs/_static/REXEE_more_configs.png b/docs/_static/REXEE_more_configs.png
diff --git a/docs/_static/algorithm.png b/docs/_static/algorithm.png
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -0,0 +1,6 @@
+.math {
+    text-align: left;
+}
+.eqno {
+    float: right;
+}
diff --git a/docs/analysis.rst b/docs/analysis.rst
diff --git a/docs/api/api_ensemble_EXE.rst → docs/api/api_replica_exchange_EE.rst b/docs/api/api_ensemble_EXE.rst → docs/api/api_replica_exchange_EE.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -52,6 +52,8 @@
     'sphinx.ext.extlinks',
     'sphinx.ext.todo',
     'nbsphinx',
+    'sphinx_collapse',
+    # 'sphinxcontrib.pseudocode',
 ]
 
 autosummary_generate = True
@@ -106,6 +108,8 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_css_files = ['css/custom.css']
+
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
@@ -191,4 +195,6 @@
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
     'pymbar': ('https://pymbar.readthedocs.io/en/latest/', None),
     'alchemlyb': ('https://alchemlyb.readthedocs.io/en/latest/', None),
-}
+}
+
+numfig = True  # necessary for the algorithm to show (see https://github.com/xxks-kkk/sphinxcontrib-pseudocode/issues/18)
diff --git a/docs/examples/run_REXEE_modify_inputs.ipynb b/docs/examples/run_REXEE_modify_inputs.ipynb
@@ -5,7 +5,7 @@
    "id": "87324540",
    "metadata": {},
    "source": [
-    "# Tutorial 3: REXEE for multiple serial mutations"
+    "# Tutorial 3: Multi-topology REXEE (MT-REXEE) simulations"
    ]
   },
   {

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -1,23 +1,18 @@
 1. Introduction
 ===============
 :code:`ensemble_md` is a Python package that provides methods for setting up, 
-running, and analyzing GROMACS simulation ensembles. The current implementation is
-mainly for synchronous replica exchange (REX) of expanded ensemble (EE), abbreviated as
-REXEE. In the future, we will develop methods like asynchronous REXEE, or multi-topology REXEE.
-In the current implementation, the module :code:`subprocess`
-is used to launch GROMACS commands, but we will switch to `SCALE-MS`_ for this purpose
-in the future when possible.
-
-
-.. _`SCALE-MS`: https://scale-ms.readthedocs.io/en/latest/
+running, and analyzing GROMACS simulation ensembles. Currently, the package implements
+all the necessary algorithms for running synchronous replica exchange (REX) of expanded ensembles (EE), abbreviated as
+REXEE, as well as its multi-topology (MT) variation MT-REXEE. Our future work includes
+implementing asynchronous REXEE and other possible variations of the REXEE method.
 
 
 2. Installation
 ===============
 2.1. Requirements
 -----------------
-Before installing :code:`ensemble_md`, one should have working versions of `GROMACS`_. Please refer to the linked documentation for full installation instructions.
-All the other pip-installable dependencies of :code:`ensemble_md` (specified in :code:`setup.py` of the package)
+Before installing :code:`ensemble_md`, one should have a working version of `GROMACS`_. Please refer to the GROMACS documentation for full installation instructions.
+All the other pip-installable dependencies required by :code:`ensemble_md` (specified in :code:`setup.py` of the package)
 will be automatically installed during the installation of the package.
 
 .. _`GROMACS`: https://manual.gromacs.org/current/install-guide/index.html
@@ -32,31 +27,36 @@ will be automatically installed during the installation of the package.
 2.3. Installation from source
 -----------------------------
 One can also install :code:`ensemble_md` from the source code, which is available in our
-`github repository`_. Specifically, execute the following commands:
+`GitHub repository`_. Specifically, one can execute the following commands:
 ::
 
     git clone https://github.com/wehs7661/ensemble_md.git
     cd ensemble_md/
     pip install .
 
-If you are interested in contributing to the project, append the 
-last command with the flag :code:`-e` to install the project in the editable mode 
-so that changes you make in the source code will take effects without re-installation of the package. 
-(Pull requests to the project repository are welcome!)
+If you would like to install the package in the editable mode, simply append the last command with the flag :code:`-e`
+so that changes you make in the source code will take effect without re-installation of the package. This is particularly
+useful if you would like to contribute to the development of the package. (Pull requests and issues are always welcome!)
 
-.. _`github repository`: https://github.com/wehs7661/ensemble_md.git
+.. _`GitHub repository`: https://github.com/wehs7661/ensemble_md.git
 
 3. Testing
 ==========
-To perform unit tests for this package, execute the following command in the home directory of the project:
+3.1. Tests for the functions that do not use MPI
+------------------------------------------------
+Most of the tests in this package do not require MPI. To perform unit tests for these functions, execute the following command in the home directory of the project:
 ::
 
     pytest -vv --disable-pytest-warnings --cov=ensemble_md --cov-report=xml --color=yes ensemble_md/tests/
 
-or 
+Note that the flags :code:`--cov` and :code:`--cov-report` are just for generating a coverage report and can be omitted. 
+These flags require that :code:`pytest-cov` be installed. 
 
+3.2. Tests for the functions that use MPI
+-----------------------------------------
+For the tests that require MPI (all implemented in :code:`tests/test_mpi_func.py`), one can use the following command:
 ::
 
-    python -m pytest -vv --disable-pytest-warnings --cov=ensemble_md --cov-report=xml --color=yes ensemble_md/tests/
+    mpirun -np 4 pytest -vv --disable-pytest-warnings --cov=ensemble_md --cov-report=xml --color=yes ensemble_md/tests/test_mpi_func.py --with-mpi
 
-Note that the flags :code:`--cov` and :code:`--cov-report` require that :code:`pytest-cov` be installed. 
+Note that the flag :code:`--with-mpi` requires that :code:`pytest-mpi` be installed.
diff --git a/docs/index.rst b/docs/index.rst
@@ -25,11 +25,6 @@ the future.
    simulations
    :maxdepth: 2
    :caption: Launching REXEE simulations:
-
-.. toctree::
-   analysis
-   :maxdepth: 2
-   :caption: Data analysis:
 
 .. toctree::
    examples/run_REXEE
@@ -39,12 +34,17 @@ the future.
    :caption: Tutorials:
 
 .. toctree::
-   api/api_ensemble_EXE
+   api/api_replica_exchange_EE.rst
    api/api_analysis
    api/api_utils
    :maxdepth: 2
    :caption: API documentation:
 
+.. toctree::
+   references
+   :maxdepth: 1
+   :caption: References:
+
 Others
 ======
 

diff --git a/docs/references.rst b/docs/references.rst
@@ -0,0 +1,6 @@
+.. -*- coding: utf-8 -*-
+
+References
+==========
+
+.. [Hsu2024] Hsu, Wei-Tse, and Michael R. Shirts. "Replica exchange of expanded ensembles: A generalized ensemble approach with enhanced flexibility and parallelizability." arXiv preprint arXiv:2308.06938 (2023). doi: `10.48550/arXiv.2308.06938 <https://doi.org/10.48550/arXiv.2308.06938>`_.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -11,4 +11,6 @@ seaborn
 matplotlib
 pyemma
 pymbar==4.0.1
-
+sphinx-collapse
+ruptures
+# sphinxcontrib-pseudocode