From 682ad6243d9fa51a5d03cefbf83d2f9d31248ddf Mon Sep 17 00:00:00 2001 From: chrisjonesBSU Date: Thu, 22 Aug 2024 10:32:20 -0600 Subject: [PATCH] Add simple example to README, bump py version in env files --- README.md | 34 +++++++++++++++++++++++++++++++++- environment-dev.yml | 2 +- environment.yml | 2 +- 3 files changed, 35 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 821c046..20f0307 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ # MultiState Iterative Boltzmann Inversion (MS-IBI) ---------------------------------------- [![pytest](https://github.com/cmelab/msibi/actions/workflows/pytest.yml/badge.svg)](https://github.com/cmelab/msibi/actions/workflows/pytest.yml) -[![codecov](https://codecov.io/gh/cmelab/msibi/branch/master/graph/badge.svg?token=7NFPBMBN0I)](https://codecov.io/gh/cmelab/msibi) +[![codecov](https://codecov.io/gh/cmelab/msibi/branch/main/graph/badge.svg?token=7NFPBMBN0I)](https://codecov.io/gh/cmelab/msibi) A package to help you manage and run pair potential optimizations using multistate iterative Boltzmann inversion. @@ -17,6 +17,38 @@ conda 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. + +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 for Hoomd is automatically generated. 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) + +Here is a simple example using MSIBI to learn a pair force from a single state point: + +```python +import hoomd +from msibi import MSIBI, State, Pair + +optimizer = MSIBI( + nlist=hoomd.md.nlist.Cell, + integrator=hoomd.md.methods.ConstantVolume, + thermostat=hoomd.md.methods.thermostats.MTTK, + dt=0.0001, + gsd_period=int(1e4) +) + +# Create a State instance, pass in a path to the target trajectory +stateA = State(name="A", kT=2.0, traj_file="stateA.gsd", alpha=1.0, n_frames=50) + +# Create a Pair instance to be optimized. Call Pair.set_lj() for the initial guess potential. +pairAA = Pair(type1="A", type2="A", optimize=True, r_cut=3.0, nbins=100) +pairAA.set_lj(r_min=0.001, r_cut=3.0, epsilon=1.0, sigma=1.0) + +optimizer.add_state(stateA) +optimizer.add_force(pairAA) +optimizer.run_optimization(n_steps=5e6, n_iterations=20) +pairAA.save_potential("AA_final.csv") +``` + ### Citation [![Citing MSIBI](https://img.shields.io/badge/DOI-10.1063%2F1.4880555-blue.svg)](http://dx.doi.org/10.1063/1.4880555) Details of the underlying method and its validation can be found [here](http://dx.doi.org/10.1063/1.4880555). diff --git a/environment-dev.yml b/environment-dev.yml index de684dd..704455a 100644 --- a/environment-dev.yml +++ b/environment-dev.yml @@ -5,7 +5,7 @@ dependencies: - freud >=3.0 - gsd >=3.0 - hoomd >=4.0 -- python >=3.9 +- python >=3.10 - pandas - cmeutils >=1.3 - numpy <2.0 diff --git a/environment.yml b/environment.yml index 4b86cd0..4731fe2 100644 --- a/environment.yml +++ b/environment.yml @@ -5,7 +5,7 @@ dependencies: - freud >=3.0 - gsd >=3.0 - hoomd >=4.0 -- python >=3.9 +- python >=3.10 - pandas - cmeutils >=1.3 - numpy <2.0