Update create_hoomd_simulation to support new HOOMD v3 API

[joaander]

PR Summary:

Change create_hoomd_simulation to work with the new HOOMD v3 API. It now returns a snapshot and a forcefield (which is a list of HOOMD force compute objects). create_hoomd_simulation no longer needs to initialize a HOOMD Device or Simulation context.

Users can inspect and modify the returned objects as needed before constructing a simulation using them.

Example:

Here is an example snippet which is an adaptation of https://github.com/cmelab/CG-Tutorial

Call create_hoomd_simulation:

from mbuild.formats.hoomd_simulation import create_hoomd_simulation
import hoomd

snapshot, forcefield, values = create_hoomd_simulation(struc, 
                                                       r_cut=1.2,
                                                       auto_scale=True)

Construct the integrator and GSD output:

langevin = hoomd.md.methods.Langevin(filter=hoomd.filters.All(),
                                     kT=1.0,
                                     seed=1)
integrator = hoomd.md.Integrator(dt=0.0001,
                                 methods=[langevin],
                                 forces=forcefield)

gsd = hoomd.dump.GSD(filename='traj.gsd',
                     trigger=hoomd.triggers.PeriodicTrigger(int(1e5)),
                     overwrite=True)

Modify an object in the force field:

for force in forcefield:
    if isinstance(force, hoomd.md.pair.LJ):
        force.r_cut.default = 1.2

Assemble and run the simulation:

sim = hoomd.Simulation(hoomd.device.GPU())
sim.create_state_from_snapshot(snapshot)
sim.operations.integrator = integrator
sim.operations.add(gsd)
sim.operations.schedule()

sim.run(3e5)

PR Checklist

---

• Includes appropriate unit test(s)
• Appropriate docstring(s) are added/updated
• Code is (approximately) PEP8 compliant
• Issue(s) raised/addressed?

[joaander]

This draft is a work in progress. It works with the HOOMD branch feature/new-object-API which is currently under heavy development. Currently, feature/new-object-API only implements LJ pair, harmonic bonds, and Langevin integration for MD. As we implement more MD forces, we will uncomment and update the corresponding calls in this draft PR.

Also note that the API in feature/new-object-API is not finalized and may change prior to release.

[joaander]

closes #696

[codecov]

Codecov Report

Merging #698 into master will decrease coverage by 0.00%.
The diff coverage is 0.00%.

@@            Coverage Diff             @@
##           master     #698      +/-   ##
==========================================
- Coverage   82.25%   82.24%   -0.01%     
==========================================
  Files          57       58       +1     
  Lines        4706     4969     +263     
==========================================
+ Hits         3871     4087     +216     
- Misses        835      882      +47     

Impacted Files	Coverage Δ
mbuild/formats/hoomd_simulation.py	0.00% <0.00%> (ø)
mbuild/formats/hoomd_snapshot.py	0.00% <0.00%> (ø)
mbuild/lib/recipes/alkane.py	38.88% <0.00%> (-47.48%)	⬇️
mbuild/lattice.py	96.27% <0.00%> (-1.12%)	⬇️
mbuild/formats/lammpsdata.py	87.65% <0.00%> (-0.43%)	⬇️
mbuild/box.py	97.67% <0.00%> (ø)
mbuild/__init__.py	100.00% <0.00%> (ø)
mbuild/formats/par_writer.py	89.70% <0.00%> (ø)
mbuild/lib/moieties/silane.py	100.00% <0.00%> (ø)
mbuild/conversion.py	90.05% <0.00%> (ø)
... and 3 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c0cdd44...c488e41. Read the comment docs.

[mikemhenry]

Few API changes:
hoomd.filters.All - > hoomd.filter.All

hoomd.trigger.PeriodicTrigger -> hoomd.triggers.Periodic

[mikemhenry]

We need to expose the neighbor list we create/use in create_hoomd_simulation. At first I just stuffed it into hoomd_objects but that makes the integration line a bit weird:
integrator = hoomd.md.Integrator(dt=0.0001, methods=[langevin], forces=forcefield[1:])
So instead I think it will be cleaner to return the nl object with create_hoomd_simulation, then a user can pas that into the save_forcefield function to ensure it gets logged. That way when we read in the logged state, we are sure to get the correct neighbor list exclusions without relying on some heuristic (ie if there is a special pair, add 1-4 excluistions).

[mikemhenry]

Updated testing script:

import mbuild as mb
from foyer import Forcefield
from mbuild.formats.hoomd_simulation import create_hoomd_simulation, save_forcefield

import hoomd

smiles = "CCCCCCCCCCCC"
mb_dodecane = mb.load(smiles, smiles=True)

box = mb.box.Box([10, 10, 10])
my_box = mb.packing.fill_box(mb_dodecane, n_compounds=10, box=box)
my_box_pmd = my_box.to_parmed(box=box)

ff = Forcefield(name="oplsaa")
struc = ff.apply(
    my_box_pmd,
    assert_bond_params=True,
    assert_angle_params=True,
    assert_dihedral_params=False,
)
snapshot, forcefield, nl, values = create_hoomd_simulation(
    struc, r_cut=1.2, auto_scale=True
)
langevin = hoomd.md.methods.Langevin(filter=hoomd.filter.All(), kT=1.0, seed=1)
integrator = hoomd.md.Integrator(dt=0.0001, methods=[langevin], forces=forcefield)


gsd = hoomd.dump.GSD(
    filename="traj.gsd",
    trigger=hoomd.trigger.Periodic(int(1e5)),
    overwrite=True,
)

for force in forcefield:
    if isinstance(force, hoomd.md.pair.LJ):
        force.r_cut.default = 1.2

save_forcefield(forcefield, nl, overwrite=True)

sim = hoomd.Simulation(hoomd.device.CPU())
sim.create_state_from_snapshot(snapshot)
sim.operations.integrator = integrator
sim.operations.add(gsd)
sim.operations.schedule()

sim.run(3e5)

[mikemhenry]

Also quick note, currently is there is a bug where state gets overwritten so it is blank for the objects, @b-butler is working on that.
This has been fixed with glotzerlab/hoomd-blue#729

[mikemhenry]

Okay assuming you have created a forcefield.json and a traj.gsd file, this should work to load the objects and run the simulation.

from mbuild.formats.hoomd_simulation import load_forcefield

import hoomd

forcefield, nl  = load_forcefield()

langevin = hoomd.md.methods.Langevin(filter=hoomd.filter.All(), kT=1.0, seed=1)
integrator = hoomd.md.Integrator(dt=0.0001, methods=[langevin], forces=forcefield)


gsd = hoomd.dump.GSD(
    filename="traj.gsd", trigger=hoomd.trigger.Periodic(int(1e5)), overwrite=True,
)

sim = hoomd.Simulation(hoomd.device.CPU())
sim.create_state_from_gsd("traj.gsd")
sim.operations.integrator = integrator
sim.operations.add(gsd)
sim.operations.schedule()

sim.run(3e5)

[chrisjonesBSU]

We should think about keeping support for create_hoomd_simulation to work with hoomd v2. I'm not sure what the best way to go about this would be. To have separate .py files for each hoomd version? Have separate functions in hoomd_simulation.py

[joaander]

Replaced by #871