Merge pull request #42 from chrisjonesBSU/fix-rtd

Update doc strings and readthedocs build

Author: chrisjonesBSU

.github/workflows/CI.yaml

@@ -40,7 +40,7 @@ jobs:
         run: python -m build && pip install dist/*.whl
 
       - name: Test (OS -> ${{ matrix.os }} / Python -> ${{ matrix.python-version }})
-        run: python -m pytest -v --cov=msibi --cov-report=xml --cov-append --cov-config=setup.cfg --color yes --pyargs msibi 
+        run: python -m pytest -v --cov=msibi --cov-report=xml --cov-append --cov-config=setup.cfg --color yes --pyargs msibi
 
       - name: Upload Coverage Report
         uses: codecov/codecov-action@v5
@@ -77,4 +77,4 @@ jobs:
         run: python -m build && pip install dist/*.whl
 
       - name: Test (OS -> ${{ matrix.os }} / Python -> ${{ matrix.python-version }})
-        run: python -m pytest -v --color yes --pyargs msibi 
+        run: python -m pytest -v --color yes --pyargs msibi

.readthedocs.yml

@@ -1,16 +1,22 @@
 version: 2
+
 formats:
   - htmlzip
-  - pdf
+
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "mambaforge-4.10"
+    python: "miniconda-latest"
 
 conda:
   environment: docs/environment-docs.yml
 
 sphinx:
   builder: html
-  configuration: docs/source/conf.py
-  fail_on_warning: false 
+  configuration: docs/conf.py
+  fail_on_warning: True
+
+python:
+  install:
+    - method: pip
+      path: .

README.md

@@ -79,7 +79,7 @@ AB_bond.save_potential("AB_bond.csv")
 
 ```python
 import hoomd
-from msibi import MSIBI, State, Pair, Bond, Angle 
+from msibi import MSIBI, State, Pair, Bond, Angle
 
 optimizer = MSIBI(
 	nlist=hoomd.md.nlist.Cell,
@@ -99,18 +99,18 @@ optimizer.add_state(stateA)
 optimizer.add_state(stateB)
 optimizer.add_state(stateC)
 
-# Add bond and set a harmonic force (e.g. fit to Boltzmann inverse of the distribtion) 
+# Add bond and set a harmonic force (e.g. fit to Boltzmann inverse of the distribtion)
 bondAA = Bond(type1="A", type2="A", optimize=False)
 bondAA.set_harmonic(r0=1.4, k=800)
 optimize.add_force(bondAA)
 
-# Add angle and load previously obtained table potential 
+# Add angle and load previously obtained table potential
 angleAA = Angle(type1="A", type2="A", type3="A", optimize=False)
 angleAA.set_from_file("angleAA.csv")
 optimize.add_force(angleAA)
 
 # Create a Pair instance to be optimized.
-pairAA = Pair(type1="A", type2="A", optimize=True, r_cut=3.0, nbins=100) 
+pairAA = Pair(type1="A", type2="A", optimize=True, r_cut=3.0, nbins=100)
 # Call the set_lj() method to set an initial guess potential
 pairAA.set_lj(r_min=0.001, r_cut=3.0, epsilon=1.0, sigma=1.0)
 optimizer.add_force(pairAA)

docs/environment-docs.yml

@@ -2,13 +2,13 @@ name: msibi-docs
 channels:
   - conda-forge
 dependencies:
-  - sphinx==7.2.4
-  - sphinx_rtd_theme==1.3.0
+  - sphinx==8.2
+  - sphinx_rtd_theme>=3.0
   - freud >= 3.0
   - gsd >= 3.0
   - hoomd >= 4.0
   - python >= 3.10
   - pandas
-  - numpy <= 2.0
+  - numpy < 2.0
   - cmeutils >= 1.3
   - more-itertools

docs/source/conf.py

@@ -21,6 +21,8 @@
     "sphinx.ext.mathjax",
 ]
 autodoc_mock_imports = []
+# Order class methods and properties as they appear in code
+autodoc_member_order = "bysource"
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

docs/source/examples.rst

@@ -0,0 +1,14 @@
+.. _examples:
+============
+Examples
+============
+
+Below are some examples of how to use the ``msibi`` API.
+
+Example 1
+---------------------------------------
+Example 1 code
+
+Example 2
+---------------------------------------
+Example 2 code

docs/source/index.rst

@@ -1,12 +1,19 @@
 MSIBI: Multi-state Iterative Boltzmann Inversion
 =============================================================================================
 
-This is a python package that implements the MSIBI coarse-graining method for molecular dynamics.
+**MSIBI** is a Python package that implements the Multi-state Iterative Boltzmann Inversion (MS-IBI) method for coarse-graining in molecular dynamics.
+
+This implementation provides an intuitive Python API for running iterative Boltzmann inversion (IBI) across multiple states (MS-IBI) or a single state. It is designed to make it easy to chain together multiple optimization runs—for example, you can first optimize a coarse-grained bond-stretching interaction, then hold it fixed while optimizing other interactions like bond bending or non-bonded pair potentials.
+
+MSIBI uses the HOOMD-blue simulation engine under the hood for coarse-grained simulations; however, it does not require that the target (atomistic) simulations are also performed with HOOMD-blue. The resulting coarse-grained potentials are exported in a tabulated format compatible with other simulation engines such as LAMMPS and GROMACS.
 
 
 Quick start
 ===========
 .. toctree::
+    :maxdepth: 1
+
+    examples
     installation
 
 
@@ -17,6 +24,8 @@ Resources
 
 - `MSIBI paper <https://doi.org/10.1063/1.4880555>`_: Explanation of the MSIBI method.
 
+- `HOOMD-Blue <https://hoomd-blue.readthedocs.io/en/latest/>`_: Python package used to perform molecular dynamics simulations on CPUs and GPUs.
+
 
 .. toctree::
    :maxdepth: 1
@@ -29,7 +38,7 @@ Resources
 
 Citation
 ========
-If you use msibi in your research, please cite the following paper:
+If you use the ``msibi`` python package in your research, please cite the following paper:
 
 .. code-block:: bibtex
 

docs/source/installation.rst

@@ -2,8 +2,11 @@
 Installation
 ============
 
+These examples use the `anaconda package manager <https://www.anaconda.com/download>`_.
+
 Install from anaconda (Coming Soon)
 ---------------------------------------
+
 msibi is available on `conda-forge <https://anaconda.org/conda-forge/msibi>`_
 ::
 
@@ -19,7 +22,7 @@ Install from source
     $ git clone git@github.com:mosdef-hub/msibi.git
     $ cd msibi
 
-2. Set up and activate environment:
+2. Install dependency packages and msibi from source:
 ::
 
     $ mamba env create -f environment.yml
@@ -28,7 +31,9 @@ Install from source
 
 .. note::
 
-    To install a GPU compatible version of HOOMD-blue in your msibi environment, you need to manually set the CUDA version **before installing msibi**.
+    ``msibi`` utilizes HOOMD-Blue under-the-hood to run query simulations. This means that you are able to leverage HOOMD-Blue's GPU capability
+    in your optimiation runs if your HOOMD-Blue installation is compatible with GPUs.
+    To install a GPU compatible version of HOOMD-Blue in your msibi environment, you need to manually set the CUDA version **before installing msibi**.
     This is to ensure that the HOOMD build pulled from conda-forge is compatible with your CUDA version.
     To set the CUDA version, run the following command before installing msibi::