Merge pull request #39 from cmelab/mosdef

MSIBI Revamp

Author: chrisjonesBSU

.codecov.yml

@@ -0,0 +1,11 @@
+comment:
+    layout: "reach, diff, flags, files"
+    behavior: default
+    require_changes: false  # if true: only post the comment if coverage changes
+    require_base: no        # [yes :: must have a base report to post]
+    require_head: yes       # [yes :: must have a head report to post]
+    branches:               # branch names that can post comment
+        - "main"
+ignore:
+    - "msibi/tests"
+    - "setup.py"

.coveragerc

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+  schedule:
+    - cron:  "0 0 * * *"
+
+jobs:
+  test:
+    if: github.event.pull_request.draft == false
+    name: MSIBI Tests (python)
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v4
+        name: Checkout Branch / Pull Request
+
+      - name: Install Mamba
+        uses: mamba-org/setup-micromamba@v2
+        with:
+          environment-file: environment-dev.yml
+          create-args: >-
+            python=${{ matrix.python-version }}
+
+      - name: Install Package
+        run: python -m pip install -e .
+
+      - 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 
+
+      - name: Upload Coverage Report
+        uses: codecov/codecov-action@v5
+        with:
+          name: MSIBI-Coverage
+          verbose: true
+
+  arch-test:
+    if: github.event.pull_request.draft == false
+    name: MSIBI Tests (arch)
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macOS-latest, ubuntu-latest]
+        python-version: ["3.12"]
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v4
+        name: Checkout Branch / Pull Request
+
+      - name: Install Mamba
+        uses: mamba-org/setup-micromamba@v2
+        with:
+          environment-file: environment-dev.yml
+          create-args: >-
+            python=${{ matrix.python-version }}
+
+      - name: Install Package
+        run: python -m pip install -e .
+
+      - name: Test (OS -> ${{ matrix.os }} / Python -> ${{ matrix.python-version }})
+        run: python -m pytest -v --color yes --pyargs msibi 

.github/workflows/CI.yaml

@@ -0,0 +1,41 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: "50 6 * * 0"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ python ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: ${{ matrix.language }}
+          queries: +security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v2
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/codeql.yml

@@ -1,9 +1,10 @@
 # Default files
+*.ipynb
 *.pyc
 *.dcd
 .DS_Store
 *.egg-info
-
+*.idea/
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.gitignore

@@ -0,0 +1,32 @@
+ci:
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit.com hooks
+    for more information, see https://pre-commit.ci
+  autofix_prs: true
+  autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
+  autoupdate_schedule: weekly
+  skip: [ ]
+  submodules: false
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.1 # Ruff version
+    hooks:
+      - id: ruff
+        args: [--fix, --extend-ignore=E203]
+      - id: ruff-format
+        args: [--line-length=80]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        exclude: 'msibi/tests/assets/.*'
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        name: isort (python)
+        args:
+          [ --profile=black, --line-length=80 ]
+        exclude: 'msibi/tests/assets/.* '

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+version: 2
+formats:
+  - htmlzip
+  - pdf
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "mambaforge-4.10"
+
+conda:
+  environment: docs/environment-docs.yml
+
+sphinx:
+  builder: html
+  configuration: docs/source/conf.py
+  fail_on_warning: false 

.readthedocs.yml

@@ -1,20 +1,128 @@
-MultiState Iterative Boltzmann Inversion
+<img src="/docs/images/msibi.png" height="300">
+
+# MultiState Iterative Boltzmann Inversion (MS-IBI)
 ----------------------------------------
-[![Build Status](https://travis-ci.org/mosdef-hub/msibi.svg?branch=master)](https://travis-ci.org/mosdef-hub/msibi)
-[![Coverage Status](https://coveralls.io/repos/ctk3b/msibi/badge.svg?branch=master)](https://coveralls.io/r/ctk3b/msibi?branch=master)
+[![pytest](https://github.com/mosdef-hub/msibi/actions/workflows/pytest.yml/badge.svg)](https://github.com/mosdef-hub/msibi/actions/workflows/pytest.yml)
+[![codecov](https://codecov.io/gh/mosdef-hub/msibi/branch/main/graph/badge.svg?token=7NFPBMBN0I)](https://codecov.io/gh/mosdef-hub/msibi)
+[![Citing MSIBI](https://img.shields.io/badge/DOI-10.1063%2F1.4880555-blue.svg)](http://dx.doi.org/10.1063/1.4880555)
 
-A package to help you manage and run pair potential optimizations using
-multistate iterative Boltzmann inversion.
+A package to help you manage and run coarse-grain potential optimizations using multistate iterative Boltzmann inversion.
 
-Install from source:
-```python
+## Installing MSIBI
+
+### Install from conda-forge (Coming soon):
+```
+mamba install -c conda-forge msibi
+```
+
+### Install from source:
+```bash
 git clone https://github.com/mosdef-hub/msibi.git
 cd msibi
+mamba env create -f environment.yml
+mamba activate msibi
 pip install .
 ```
 
+## Using MSIBI
+The MSIBI package is designed to be very object oriented. Any force optimization runs requires at least one `msibi.state.State` instance, `msibi.force.Force` instance and `msibi.optimize.MSIBI` instance. More state and forces can be added as needed. Multiple forces can be added with some held fixed while others are being optimized after each iteation. MSIBI is designed to allow for optimization of both intra-molecular and inter-molecular potentials.
+
+MSIBI uses [Hoomd-Blue](https://hoomd-blue.readthedocs.io/en/latest/) to run optimization simulations. It is not required that you be familiar with Hoomd to use MSIBI as the simulation script is automatically generated and ran. However, it is required that you pass in the choice of [Hoomd method](https://hoomd-blue.readthedocs.io/en/latest/module-md-methods.html), [Hoomd neighbor list](https://hoomd-blue.readthedocs.io/en/latest/module-md-nlist.html), and [Hoomd thermostat](https://hoomd-blue.readthedocs.io/en/latest/module-md-methods-thermostats.html) to the `msibi.optimize.MSIBI` class. Since MSIBI utilizes Hoomd-Blue, this means that MSIBI can run on GPUs, see [Hoomd's installation guide](https://hoomd-blue.readthedocs.io/en/latest/installation.html) for instructions on ensuring your environment includes a GPU build of hoomd.
+
+### Quick Example:
+Here is a simple example using MSIBI to learn a bond-stretching force from a single state point:
+
+```python
+# This is the context/management class for MSIBI
+# Set simulation parameters, call `add_state` and `add_force` methods to store other MSIBI objects.
+optimizer = MSIBI(
+	nlist=hoomd.md.nlist.Cell,
+    integrator_method=hoomd.md.methods.ConstantVolume,
+	thermostat=hoomd.md.methods.thermostats.MTTK,
+    thermostat_kwargs={"tau": 0.1},
+    method_kwargs={},
+	dt=0.0001,
+	gsd_period=int(1e3)
+)
+
+# Create a State instance, pass in a path to the target trajectory
+stateA = State(name="A", kT=5.0, traj_file="cg_trajectory.gsd", alpha0=0.7, n_frames=100)
+
+# For each force you want to optimize, create an instance, set optimize=True
+AA_bond = Bond(type1="A", type2="A", optimize=True, nbins=80)
+AA_bond.set_polynomial(x_min=0.0, x_max=0.5, x0=0.22, k2=100000, k3=0, k4=0)
+AA_bond.smoothing_window = 5
+AB_bond = Bond(type1="A", type2="B", optimize=True, nbins=80)
+AB_bond.set_polynomial(x_min=0.0, x_max=0.5, x0=0.22, k2=100000, k3=0, k4=0)
+AB_bond.smoothing_window = 5
+# Add all states and forces to the optimization class (MSIBI)
+optimizer.add_state(stateA)
+optimizer.add_force(AA_bond)
+optimizer.add_force(AB_bond)
+optimizer.run_optimization(n_iterations=10, n_steps=2e5)
+
+# See distribution comparison
+AA_bond.plot_distribution_comparison(state=stateA)
+AB_bond.plot_distribution_comparison(state=stateA)
+
+<<<<<<< HEAD
+# Run 20 MSIBI iterations
+optimizer.run_optimization(n_steps=2e6, n_iterations=20)
+pairAA.save_potential("pairAA.csv")
+```
 
-#### Citation [![Citing MSIBI](https://img.shields.io/badge/DOI-10.1063%2F1.4880555-blue.svg)](http://dx.doi.org/10.1063/1.4880555)
+### Example: Multiple states, multiple forces
+- Here is an example of learning a pair potential using multiple state points and forces.
+- In this example, we set fixed bond and angle potentials that are included during iteration simulations.
+- The bond potential will set a fixed harmonic force, while the angle potential will be set from a table potential file.
+- This illustrates a use case of stringing together multiple MSIBI optimizations.
+	- For example, one MSIBI optimization can be used to learn and obtain a coarse-grained angle potential table file which can then be set and held fixed while learning pair potentials in a subsequent MSIBI optimization.
+
+```python
+import hoomd
+from msibi import MSIBI, State, Pair, Bond, Angle 
+
+optimizer = MSIBI(
+	nlist=hoomd.md.nlist.Cell,
+    integrator_method=hoomd.md.methods.ConstantVolume,
+	thermostat=hoomd.md.methods.thermostats.MTTK,
+    thermostat_kwargs={"tau": 0.1},
+    method_kwargs={},
+	dt=0.0001,
+	gsd_period=int(1e4)
+)
+
+# Create 3 State instances, pass in a path to the target trajectory
+stateA = State(name="A", kT=2.0, traj_file="stateA.gsd", alpha=0.2, n_frames=50)
+stateB = State(name="B", kT=4.0, traj_file="stateB.gsd", alpha=0.5, n_frames=50)
+stateC = State(name="C", kT=6.0, traj_file="stateC.gsd", alpha=0.3, n_frames=50)
+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) 
+bondAA = Bond(type1="A", type2="A", optimize=False)
+bondAA.set_harmonic(r0=1.4, k=200)
+optimize.add_force(bondAA)
+
+# 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) 
+# 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)
+
+# Run 20 MSIBI iterations
+optimizer.run_optimization(n_steps=2e6, n_iterations=20)
+pairAA.save_potential("pairAA.csv")
+```
+
+
+## Citing MSIBI
 Details of the underlying method and its validation can be found [here](http://dx.doi.org/10.1063/1.4880555).
 
 If you use this package, please cite the above paper. The BibTeX reference is
@@ -25,10 +133,7 @@ If you use this package, please cite the above paper. The BibTeX reference is
       journal = "The Journal of Chemical Physics",
       year = "2014",
       volume = "140",
-      number = "22", 
-      doi = "http://dx.doi.org/10.1063/1.4880555" 
+      number = "22",
+      doi = "http://dx.doi.org/10.1063/1.4880555"
 }
 ```
-
-
-