Project Plan: Adoption of Interchange backend as export machinery for ForceField.create_openmm_system

Primary Driver

@Matt Thompson

Approver

@Jeffrey Wagner

Supporting Drivers

@Jeffrey Wagner

Stakeholders

@Jeffry Setiadi @Lily Wang @Michael Shirts Richard Gowers @Joshua Horton Irfan Alibay, Hyesu Jang,

Decision authority

Milestone completion: Unanimity of Primary Driver and Approver

Significant spec changes: Unanimity of Primary Driver and Approver in upon consultation of stakeholders

Discussion/ Notification venue

The #developers slack channel, with a 3-day feedback period for any major decision, in which all stakeholders are tagged

Objective

Replace current Toolkit code that generates OpenMM systems with Interchange in a way that does not unduly affect users or FF developers

Due date

End of November 2022

Key outcomes

Interchange code replaces all the create_force and postprocess_system methods from the OFF toolkit. FF fitting experimentation migrates to use Interchange.

Status

not started / in progress / complete

Must have:

• A feature freeze on ParameterHandlers while this milestone is being undertaken

• Nonbonded force combination kwarg equivalence

• Implementation of charge_from_molecules and partial_bondorders_from_molecules kwargs

• Regression tests that achieve agreement to 6 decimal places while comparing serialized OpenMM System objects generated by the 0.10.6 toolkit and the 0.11.0 release candidate. Included in this test set are:

  • The 9104 SMILES from the public industry data set parameterized with Sage, with default conformer generation.

    • Using this file:

  • All condensed phase systems used for fitting Sage, using Sage parameters

    • Using this file:

  • For 5-10 diverse molecules that have interpolated parameters assigned with

    • WBO-interpolated bonds

    • WBO-interpolated torsions

    • SB drew up some molecules and made up torsion terms, sent to MT. MT chose these molecules without much expertise or care: input needed

• The 0.11.0 toolkit release candidate + Interchange will pass the vsite test suite as added in #1252

  • Further, since the above test suite examines everything except exceptions and energies, one molecule+FF permutation from the 0.10.6 vsite geometry tests will be used to compare single-point energies in both 0.10.6 and the 0.11.0 release candidate.

• Every built-in handler and their associated attributes must be able to be stored in an Interchange object and be exported to an OpenMM system (with exceptions for things that shouldn’t be passed on, like that OpenMM shouldn’t know partial_bondorder_method="am1-wiberg" , or that PME was requested if the topology is non-periodic, though the structure of the regression tests should make it clear that these AREN’T being checked).

• Value propagation testing: “for every attribute of every built-in parameter handler (e.g. cutoff, v-site distance, bond length): an OpenMM system created using openff-2.0.0.offxml but with the attribute of the handler perturbed yields an OpenMM system with that value also modified, again to ensure that changes to parameter attributes are actually captured and its not just the default values that get passed through”

  • In most cases, only the value of one attribute needs to be changed at a time. The propagation of these changed values can be tested by comparing the output OpenMM systems, written as XML, and compared via deepdiff

• Disagreements between Interchange and Toolkit found as a result of this testing will be resolved as follows:

  • The SMIRNOFF committee may decide to modify or extend the SMIRNOFF spec in response to issues that arise from this, and only the resulting SMIRNOFF spec should be considered correct behavior.

  • If the Toolkit had a bug or was violating the SMIRNOFF spec, then Interchange should proceed with the correct values per the spec

  • If the difference is within allowed error or is agreed to be acceptable (as determined by both Primary Driver and Approver), then it is acceptable. Either the Primary Driver or Approver may require that the difference be documented.

  • For externally-calculated properties such as partial charges and Wiberg bond orders, differences with a relative magnitude over 1e-6 must be shown to be either:

    • A bug in 0.10.X, or

    • Unavoidably stochastic (root cause is in OE or RD/AT implementation)

      • To determine this, we will run OE charge/WBO assignment for a mol 1000x, for each atom, calculate a charge average, and the deviation. If the deviation is greater that 1e-6, then we can conclude that the issue is stochastic.

• OpenFF Toolkit 0.11.0 will only support the Interchange backend for create_openmm_system. There will be a feature freeze on 0.10.Z line except for backporting critical bugfixes (“bugs that affect assigned parameters to 6 decimal places (kcal/mol)”, or “bugs that both Approver and Driver agree need to be backported”).

•  

Nice to have:

• GBSA support

Not in scope:

• The current custom ParameterHandler plugins, which specify create_force and postprocess_system and sometimes find_matches, won’t be supported in Interchange when OFFTK 0.11.0 is released.

Must have:

• “User Adoption” milestone passed

• GBSA support by end of June 2022

• Plugin support (may be the subject of a project by itself) specced (reference implementation, base classes/composition requirements, API points explicit, entry points, inter-handler dependencies, registration system for exporters/importers) by MT as driver and JW as approver decided, by end of (X date), code available by end of (Y date), and current plugin support deprecated by (Y+5 months) to allow for plugins to port over.

Nice to have:

• Drivers from this working group assist or open PR to port custom plugins to new plugin interface

Not in scope:

• (Same as “not in scope” above) The current custom ParameterHandler plugins, which specify create_force and postprocess_system and sometimes find_matches, won’t be supported in Interchange when OFFTK 0.11.0 is released.

Finalize spec (this page)

Regression testing (at least all “must have”s from “User adoption scope” board above)

“User adoption”: Replace default behavior of create_openmm_system to use Interchange in 0.11.0 OFF Toolkit release

Full plugin support (at least all “must have”s from “Deprecation of previous code scope” board above)

X date)

Begin create_force/ postprocess_system/parameterhandler plugin deprecation window

Y date)

Remove create_force/ postprocess_system / ParameterHandler create_force and postprocess_system plugin support from OpenFF Toolkit

Y+5 months