Let's include units in the force field file

[mikemhenry]

We can do what SMIRNOFF force field format does: https://github.com/openforcefield/openforcefield/blob/master/The-SMIRNOFF-force-field-format.md

For example <HarmonicAngleForce angle_unit="radian" k_unit="kilojoules_per_mole/radian**2">

I'm not a fan of kilojoules_per_mole/radian**2 and would rather kJ/(mole radian**2) but whatever way we decide, should be 'machine readable' so code could do unit conversions, as well as a human.

[chrisiacovella]

This is a good idea. Until this change is put into place, I suggest all force field files should start with a comment that clearly states the expected units. We should add this to the force field template immediately.

[richardjgowers]

Yeah having just filled in a force field, I would have much preferred to have used the native units. It's a lot easier to check that a typo hasn't been made!

[davidlmobley]

Ours (SMIRNOFF) are parsed by simtk.unit so that's where the kilojoules_per_mole/radian**2 comes from.

[mikemhenry]

• [ ] units
• [ ] functional forms
• [ ] things like r_cut, shifted

We can add them first as xml comments, then add it to the schema, if the ff doesn't care about r_cut, we can either suggest a default, or not list one

[richardjgowers]

I’m pretty sure all FFs have a defined cutoff they were made for (and others are technically wrong) so it’s very integral to include this.

On Mar 11, 2019 at 12:50 PM, <Mike Henry (mailto:notifications@github.com)> wrote:

units

functional forms

things like r_cut, shifted

We can add them first as xml comments, then add it to the schema, if the ff doesn't care about r_cut, we can either suggest a default, or not list one

— You are receiving this because you commented. Reply to this email directly, view it on GitHub (https://github.com/mosdef-hub/foyer/issues/176#issuecomment-471672785), or mute the thread (https://github.com/notifications/unsubscribe-auth/AI0jB5hXPOIBi2SNzwcC6OkxyEcT5xcwks5vVqV2gaJpZM4V2LNN).

[mattwthompson]

The difficulty here is defining at the engine level exactly what's in the "setup" part and what's in the "details of MD setup" part. There are some things that fit neatly into one or the other (force field constants are in the setup side, timestep is on the MD side) but some like FF cutoff are a little more amorphous. In GROMACS it's in the .mdp file with other MD parameters but in other engines it's stored more closely to the force field.

However, the cutoff distance and cutoff handling are inarguably a part of faithfully reproducing the force field (assuming the authors are diligent enough to specify it!) so it can't be ignored. At bare minimum we should try to store it as metadata and print out to the user, i.e. "ok this XML is supposed to have a cutoff of 12 A and no tail correction"

[jennyfothergill]

I don't know if this comment belongs here or #220, but I think these issues could use a boost! As a user I spend too much time confused about what units I'm in through the conversion from mbuild/parmed/openbabel/openmm. I realize veteran users probably know these by heart, but for a new user it is very confusing. And it seems many unit conversions in our workflows are silent, which is even more confusing. It'd be nice if the standard units were listed in the docs or there were a way to query the units in the code!

[rsdefever]

@jennyfothergill I think this will come into play as the gmso backend starts to be integrated into foyer (soon, I hope!). I could perhaps be talked into working on an overhaul of the foyer docs. I had started this a few weeks back but time.

[jennyfothergill]

Thanks, Ryan! It's hard to justify a big revamp of the docs when big changes are on the way, but I think it is a great idea to make sure to document things like units moving forward. I love the explicit units in gmso, so I really hope to see that used in future.