Merge pull request #52 from wehs7661/add_tutorials

Add tutorials for running and analyzing REXEE simulations (#52)

.circleci/config.yml

@@ -2,11 +2,14 @@ version: 2.1
 
 jobs:
   test:
-    machine:
-      # Note that ubuntu with versions later than 2022 triggers an interative prompt that gets CI stuck
-      image: ubuntu-2004:202107-02
+    docker:
+      - image: cimg/python:<<parameters.python-version>>
     environment:
-      PYTHON_VERSION: "3.8"
+      PYTHON_VERSION: "<<parameters.python-version>>"
+    parameters:
+      python-version:
+        type: string
+    resource_class: large
     steps:
       - checkout
 
@@ -21,10 +24,17 @@ jobs:
           name: Installing dependencies for GROMACS
           command: |
             sudo apt-get update
+            sudo apt-get install -y software-properties-common
             sudo apt install build-essential
             sudo apt-get install ccache libblas-dev libfftw3-dev liblapack-dev libmpich-dev libxml2-dev mpich ninja-build
             wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null
             sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ focal main' -y
+            
+            # The following three lines are required to install libss1.1, which is not available in the default environment
+            wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
+            sudo dpkg -i ./libssl1.1_1.1.1f-1ubuntu2_amd64.deb
+            rm -f libssl1.1_1.1.1f-1ubuntu2_amd64.deb
+
             sudo apt install cmake && cmake --version
 
       - run:
@@ -74,9 +84,19 @@ jobs:
       - store_test_results:
           path: test-results
 
+# we are not testing Python 3.12. as it seems to have some conflicts with versioneer.py. Will look into this more in the future.
 workflows:
   continuous-integration:
     jobs:
-      - test
-
-
+      - test:
+          name: test-python-3.8
+          python-version: "3.8"
+      # - test:
+      #     name: test-python-3.9
+      #     python-version: "3.9"
+      - test:
+          name: test-python-3.10
+          python-version: "3.10"
+      - test:
+          name: test-python-3.11
+          python-version: "3.11"

.github/ISSUE_TEMPLATE/bug_report.md

@@ -21,7 +21,7 @@ If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
  - OS: [e.g. iOS]
- - Version [e.g. 0.1.2]
+ - Version of `ensemble_md` [e.g. 0.1.2]
 
 **Additional context**
 Add any other context about the problem here.

.gitignore

@@ -105,3 +105,6 @@ ENV/
 # profraw files from LLVM? Unclear exactly what triggers this
 # There are reports this comes from LLVM profiling, but also Xcode 9.
 *profraw
+
+# Others
+.DS_Store

README.md

@@ -6,20 +6,25 @@ Ensemble Molecular Dynamics
 [![Documentation Status](https://readthedocs.org/projects/ensemble-md/badge/?version=latest)](https://ensemble-md.readthedocs.io/en/latest/?badge=latest)
 [![GitHub Actions Lint Status](https://github.com/wehs7661/ensemble_md/actions/workflows/lint.yaml/badge.svg)](https://github.com/wehs7661/ensemble_md/actions/workflows/lint.yaml)
 [![PyPI version](https://badge.fury.io/py/ensemble-md.svg)](https://badge.fury.io/py/ensemble-md)
-[![DOI](https://img.shields.io/badge/DOI-arxiv.org%2Fabs%2F2308.06938-green)](https://arxiv.org/abs/2308.06938)
-
+[![python](https://img.shields.io/badge/Python-3.8%20|%203.9%20|%203.10%20|%203.11-4BC51D.svg?style=flat&logo=python&logoColor=white)](https://www.python.org)
+[![DOI](https://img.shields.io/badge/DOI-10.1021/acs.jctc.4c00484-4BC51D)](https://pubs.acs.org/doi/epdf/10.1021/acs.jctc.4c00484)
 [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
 [![Downloads](https://static.pepy.tech/badge/ensemble-md)](https://pepy.tech/project/ensemble-md)
-[![Twitter Follow](https://img.shields.io/twitter/follow/WeiTseHsu?style=social)](https://twitter.com/WeiTseHsu)
 
-**ensemble_md** is a Python package that provides methods for setting up, running, and analyzing molecular dynamics ensembles in GROMACS. 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. For installation instructions, theory overview, tutorials, and API references, please visit the [documentation](https://ensemble-md.readthedocs.io/en/latest/?badge=latest).
+
+`ensemble_md` is a Python package that provides methods for setting up, 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. For installation instructions, theory overview, tutorials, and API references, please visit the [documentation](https://ensemble-md.readthedocs.io/en/latest/?badge=latest) and our [JCTC paper](https://pubs.acs.org/doi/epdf/10.1021/acs.jctc.4c00484).
+
+### Reference
+If you use any components of the Python package `ensemble_md` or the REXEE method in your research, please cite the following paper:
+
+Hsu, W. T., & Shirts, M. R. (2024). Replica Exchange of Expanded Ensembles: A Generalized Ensemble Approach with Enhanced Flexibility and Parallelizability. *Journal of Chemical Theory and Computation*. doi: [10.1021/acs.jctc.4c00484](https://doi.org/10.1021/acs.jctc.4c00484)
 
 ### Copyright
 
 Copyright (c) 2022, Wei-Tse Hsu
 
 
-#### Acknowledgements
+### Acknowledgements
 
 Project based on the 
 [Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms) version 1.6.