OFF-EP 0003

docs/enhancement-proposals/off-ep-0003.md

@@ -0,0 +1,90 @@
+# OFF-EP 0003 — Allow fractional bond order interpolation between arbitrary fractional bond order interpolation points
+
+**Status:** Proposed
+
+**Authors:** Matt Thompson, [email protected]
+
+**Stakeholders:** David Mobley, John Chodera, Jeffrey Wagner, Simon Boothroyd
+
+**Acceptance criteria:** Unanimity
+
+**Created:** 2021-11-23
+
+**Discussion:** [Issue #8](https://github.com/openforcefield/standards/issues/8)
+
+**Implementation:** [PR #23](https://github.com/openforcefield/standards/pull/23)
+
+## Abstract
+
+This OFF-EP explicitly documents that non-integer bond orders can be used for interpolating parameters.
+
+## Motivation and Scope
+
+The SMIRNOFF specification describes a process by which fractional bond orders can be used to
+interpolate parameters for
+[bond](https://openforcefield.github.io/standards/standards/smirnoff/#fractional-bond-orders) and
+[proper
+torsion](https://openforcefield.github.io/standards/standards/smirnoff/#fractional-torsion-bond-orders)
+forces. The examples provided use bond orders of 1 and 2 as the basis of interpolation between
+their associated parameters. Work by the Open Force Field Initiative has suggested cases in which it
+would be useful to have non-integer bond orders such that i.e. parameters are interpolated between
+bond orders of 1.0 and 1.2 in a different way than they may be between bond orders of 1.2 and 2.0.
+The current specification does not explicitly forbid non-integer bond orders, but the section
+describes the process of parameter interpolation using an example that does. Also, the current
+implementation in the OpenFF Toolkit does not support non-integer bond orders.
+
+## Usage and Impact
+
+In practice, most bonds in molecules have bond orders very near 1.0 or 2.0 and values such as 1.5
+are much less common. This results in training data being clumped near 1.0 and 2.0 and often the
+slopes of each cluster are not identical. For example, the slope associated with a cluster at 1.0 -
+1.2 might be different from a cluster at 1.8-2.0. @pavankum describes this in more detail in
+[issue #8](https://github.com/openforcefield/standards/issues/8). Being able to have different
+slopes associated with each cluster, i.e. by using 1.0, 1.5, and 2.0 instead of just 1 and 2, would
+enable a force field to account for these differences. Such a parameter may look like
+
+```
+<Bonds version="0.3" potential="harmonic" fractional_bondorder_method="AM1-Wiberg" fractional_bondorder_interpolation="linear">
+    <Bond
+        smirks="[#6X3:1]!#[#6X3:2]"
+        k1="820.0*kilocalories_per_mole/angstrom**2"
+        k2="1000.0*kilocalories_per_mole/angstrom**2"
+        k3="1098*kilocalories_per_mole/angstrom**2"
+        length1="1.45*angstrom"
+        length2="1.43*angstrom"
+        length3="1.35*angstrom"
+        bondorder1="1.0"
+        bondorder2="1.5"
+        bondorder3="2.0"
+
+    />
+/>
+```
+
+## Backward compatibility
+
+This OFF-EP adds an attribute to the `<Bonds/>` and `<ProperTorsions/>` sections that is required in
+order to use parameter interpolation. No functionality is removed, so forwards compatibility could
+be provided with a converter. Functionality is added, however, so backwards compatbility cannot be
+guaranteed.
+
+## Detailed description
+
+This section should provide a detailed description of the proposed
+change. It should include examples of how the new functionality would be
+used, intended use-cases and pseudo-code illustrating its use.
+
+The following is added to the `Fractional torsion bond orders` subsection of the
+`<ProperTorsions>` section.
+
+## Alternatives
+
+There is no alternative route to this behavior in the current SMIRNOFF specification.
+
+## Discussion
+
+- [Issue #8](https://github.com/openforcefield/standards/issues/8)
+
+## Copyright
+
+*All OFF-EPs are explicitly [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).*

docs/standards/smirnoff.md

@@ -424,7 +424,15 @@ For example, these parameters:
 can be replaced by a single parameter line by first invoking the `fractional_bondorder_method` attribute to specify a method for computing the fractional bond order and `fractional_bondorder_interpolation` for specifying the procedure for interpolating parameters between specified integral bond orders:
 ```XML
 <Bonds version="0.3" potential="harmonic" fractional_bondorder_method="AM1-Wiberg" fractional_bondorder_interpolation="linear">
-    <Bond smirks="[#6X3:1]!#[#6X3:2]" k_bondorder1="820.0*kilocalories_per_mole/angstrom**2" k_bondorder2="1098*kilocalories_per_mole/angstrom**2" length_bondorder1="1.45*angstrom" length_bondorder2="1.35*angstrom"/>
+    <Bond
+        smirks="[#6X3:1]!#[#6X3:2]"
+        k1="820.0*kilocalories_per_mole/angstrom**2"
+        k2="1098*kilocalories_per_mole/angstrom**2"
+        length1="1.45*angstrom"
+        length2="1.35*angstrom"
+        bondorder1="1.0"
+        bondorder2="2.0"
+        />
     ...
 ```
 This allows specification of force constants and lengths for bond orders 1 and 2, and then interpolation between those based on the partial bond order.
@@ -436,6 +444,7 @@ This allows specification of force constants and lengths for bond orders 1 and 2
 |---------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|-------------------------------|
 | 0.3                       | `potential="harmonic"`, `fractional_bondorder_method="none"`, `fractional_bondorder_interpolation="linear"`                 | `smirks`, `length`, `k`                       |  `id`, `parent_id`            |
 | 0.4                       | `potential="(k/2)*(r-length)^2"`, `fractional_bondorder_method="AM1-Wiberg"`, `fractional_bondorder_interpolation="linear"` | `smirks`, `length`, `k`                       |  `id`, `parent_id`            |
+| 0.5                       | `potential="(k/2)*(r-length)^2"`, `fractional_bondorder_method="AM1-Wiberg"`, `fractional_bondorder_interpolation="linear"`, `bondorder` | `smirks`, `length`, `k`                       |  `id`, `parent_id`            |
 
 
 ### `<Angles>`
@@ -524,6 +533,9 @@ This works even when barrier heights for more than two integer bond orders are s
 In other words, a fractional bond order of 3.2 would yield an interpolated `k#` value determined by the interpolation line between ``k#_bondorder2`` and ``k#_bondorder3``.
 A fractional bond order of .9 would yield an interpolated `k#` value determined by the interpolation line between ``k#_bondorder1`` and ``k#_bondorder2``.
 
+The bond orders used here for interpolation between are all integers, however they do not
+necessarily need to be integers. For example, bond orders 1.0, 1.5, and 2.0 could be to produce a
+different slope between the range 1.0 to 1.5 and 1.5 to 2.0
 
 Some key usage points:
 
@@ -533,7 +545,8 @@ Some key usage points:
 |  ProperTorsions section tag version | Tag attributes and default values                                                                                                                                   | Required parameter attributes                            | Optional parameter attributes  |
 |-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------------------------|
 | 0.3                                 | `potential="k*(1+cos(periodicity*theta-phase))"`, `default_idivf="auto"`                                                                                            | `smirks`, `k`, `phase`, `periodicity`                    | `idivf`, `id`, `parent_id`     |
-| 0.4                                 | `potential="k*(1+cos(periodicity*theta-phase))"`, `default_idivf="auto"`, `fractional_bondorder_method="AM1-Wiberg"`, `fractional_bondorder_interpolation="linear"` | `smirks`, (`k` OR `k_bondorder`), `phase`, `periodicity` | `idivf`, `id`, `parent_id`     |
+| 0.4                                 | `potential="k*(1+cos(periodicity*theta-phase))"`, `default_idivf="auto"`, `fractional_bondorder_method="AM1-Wiberg"`, `fractional_bondorder_interpolation="linear"`, | `smirks`, (`k` OR `k_bondorder`), `phase`, `periodicity` | `idivf`, `id`, `parent_id`     |
+| 0.5                                 | `potential="k*(1+cos(periodicity*theta-phase))"`, `default_idivf="auto"`, `fractional_bondorder_method="AM1-Wiberg"`, `fractional_bondorder_interpolation="linear"`, `bondorder` | `smirks`, (`k` OR `k_bondorder`), `phase`, `periodicity` | `idivf`, `id`, `parent_id`     |
 
 
 ### `<ImproperTorsions>`