TestSystems for Double Well in WCA Fluid

[dwhswenson]

This PR adds (two generalizations of) a test system that has been frequently used in rare events. I'm calling these DoubleWellDimer_WCAFluid and DoubleWellChain_WCAFluid. In both cases, we start with the existing WCAFluid test system, and add bonded interactions of the form $h (1 - ((r - r_0 - w) / w)^2)^2$. This is a symmetric potential with a minimum at $(r_0, 0)$, a maximum at $(r_0+w, h)$, and a second minimum at $(r_0 + 2w, 0)$. The widely-used test system adds this interaction between 2 atoms, so there is one dimer in the WCA fluid.

For the DoubleWellDimer_WCAFluid, the system will create bonds between pairs of atoms, so the bonds are created between atom 0 and 1, atom 2 and 3, etc., resulting in multiple separated dimers, each dimer connected by the double-well potential. This is similar to what was done in Swenson and Bolhuis, JCP 2014. The standard example is ndimers=1.

For the DoubleWellChain_WCAFluid, the system will create a chain of bonds of the desired length, so bonds are created between atom 0 and 1, atom 1 and 2, etc. For nchained=1, this is just the WCA fluid; for nchained=2, this is identical to the DoubleWellDimer_WCAFluid with ndimers=1, and for nchained=3 this is the same as the potential used in Rogal and Bolhuis, JCP 2008.

The clever bit in the implementation is to recognize that the same algorithm works for both; the only difference is in which atom pairs are selected to have the custom bond force added to them.

• Implement feature / fix bug
• Add tests
• Update documentation as needed
• Update changelog

[andrrizzi]

LGTM, thanks!

[dwhswenson]

Let me add another commit with docs and changelog update ;-)

Also, regarding tests: There are a few other things that I would usually test, but I don't see the appropriate place to do that within the OpenMMTools test suite. In particular, some of setups are equivalent under certain circumstances (0 dimers is the same as chain length 0 or 1, and also the same as the WCAFluid; 1 dimer is the same as chain of length 2 atoms). I would usually add a test that the topologies are equivalent for these. Also, I'd usually add tests to check that the expected errors get raised.

Any recommended way/location to add these extra tests?

[These already participate in default tests for testsystems (potential energy, topology, properties)]

[andrrizzi]

Let me add another commit with docs and changelog update ;-)

Thanks! I appreciate.

Any recommended way/location to add these extra tests?

I think an extra test function(s) in tests/test_testsystems.py will be good enough. Unless you think there are reasons to separate them in a different file.

[jchodera]

Thanks for contributing this!

[dwhswenson]

I think this is ready now! I added a few simple tests, and also added this to the docs and to the release notes. The existing WCAFluid test system made it easy to implement these 2 generalizations, which I needed for some projects I'm working on.

(The rest of this comment is just FYI stuff related to how my current funding source will take credit for funding me while I wrote this PR)

The work in this PR will be part of an E-CAM module. As such, a description of it will eventually be included in the list of classical MD software modules that E-CAM has produced, and will be delivered as part of a document to be made publicly available. The in-progress documentation about this particular E-CAM module can be seen on the E-CAM modules GitLab repository.

None of this requires any further work from the OpenMMTools development team. This is just how E-CAM accounts for its contributions to various software projects. My work in this PR has been supported by the European Union's Horizon 2020 research and innovation programme, grant agreement No 676531 (project E-CAM).

[jchodera]

Looks great, thanks!