OFF-EP 0008 — Periodicity-dependent vdW methods and "no-cutoff" option

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

@@ -0,0 +1,82 @@
+# OFF-EP 0008 — Specifying different vdW methods for periodic and non-periodic systems and allow "no-cutoff" vdW interactions
+
+**Status:** Draft
+
+**Authors:** Matt Thompson
+
+**Stakeholders:** All who have implemented a SMIRNOFF parser
+
+**Acceptance criteria:** Majority of SMIRNOFF committee
+
+**Created:** 2023-08-01
+
+**Discussion:** Issues [#51](https://github.com/openforcefield/standards/pull/51) and
+[#7](https://github.com/openforcefield/standards/issues/7)
+
+**Implementation:** [PR #53](https://github.com/openforcefield/standards/pull/53)
+
+## Abstract
+
+This OFF-EP splits the current `method` attribute in the vdW section into separate attributes for periodic and non-periodic systems. It also adds `"no-cutoff"` as a supported method.
+
+## Motivation and Scope
+
+The `method` attribute in the vdW section specifies what sort of cut-off scheme should be used, if any, for vdW
+interactions. It does this without consideration for whether or not the system is periodic. Conventionally, however,
+different schemes are used for periodic systems (cut-off interactions with various corrections) and non-periodic
+systems (no cut-off). This causes an issue for existing implementations, which favor the use of a "no cut-off" scheme
+for non-periodic systems despite not being a part of the SMIRNOFF specification.
+
+Additionally, the current specification implies that the only supported vdW method is `"cutoff"` and, by extension, that vdW
+interactions without a cut-off are not supported by SMIRNOFF despite its common use.
+
+## Usage and Impact
+
+As these proposed changes bring the specification in line with existing implementations, such as how OpenFF software
+implements the SMIRNOFF specification, there should be no practical impact on existing workflows and simulations.
+Software that implements the SMIRNOFF specification will need to be updated to support new attributes. Additionally,
+developers may choose to implement an up-converter from older versions of the vdW section.
+
+## Backward compatibility
+
+Because this change expands the information content of the vdW section and adds attributes that do not currently exist,
+it can be understood as strictly backwards-incompatible. However, most implementations do not strictly follow the
+specification in its current form and the proposed changes bring the specification in line with this implementation and
+community practices more broadly.
+
+## Detailed description
+
+The vdW method section is updated to version 0.4.
+
+The `method` attribute is removed from the vdW section and replaced with two new attributes: `periodic_method` and
+`nonperiodic_method`. These encode the method that should be used for periodic and non-periodic systems,
+respectively.
+
+Either `periodic_method` or `nonperiodic_method` can take the following values:
+
+* `"cutoff"`: The vdW interaction is truncated at a distance specified by the `cutoff` attribute.
+* `"no-cutoff"`: The vdW interaction is not truncated.
+
+The default values, and the implied up-conversion from `method="cutoff"` of version 0.3, are `periodic_method="cutoff"`
+and `nonperiodic_method="no-cutoff"`.
+
+Other attributes in the vdW section, such as `potential`, are not affected.
+
+## Alternatives
+
+The existing `method` section could remain but specify both periodic and non-periodic methods. The result would be
+something like `method="periodic=cutoff,non-periodic=no-cutoff"`. This is unappealing, however, as it forces two
+details into one setting, is non-trivial to parse, and makes future extensions to the set of supported methods more difficult.
+
+## Discussion
+
+* [Ambiguity with periodicity](https://github.com/openforcefield/standards/pull/51)
+* [Lack of (explicit) support for non-cut-off interactions](https://github.com/openforcefield/standards/issues/7)
+* A similar change to the Electrostatics section was accepted in OFF-EP 0005
+
+## Copyright
+
+*This template is based upon the [``numpy`` NEP template](https://github.com/numpy/numpy/blob/master/doc/neps/nep-template.rst) and the
+[``conda-forge`` CFEP template.](https://github.com/conda-forge/cfep/blob/master/cfep-00.md)*
+
+*All OFF-EPs are explicitly [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).*

docs/standards/smirnoff.md

@@ -317,7 +317,7 @@ As an example of a complete SMIRNOFF force field specification, see [a recent fo
 
 van der Waals force parameters, which include repulsive forces arising from Pauli exclusion and attractive forces arising from dispersion, are specified via the `<vdW>` tag with sub-tags for individual `Atom` entries, such as:
 ```XML
-<vdW version="0.3" potential="Lennard-Jones-12-6" combining_rules="Lorentz-Berthelot" scale12="0.0" scale13="0.0" scale14="0.5" scale15="1.0" switch_width="8.0*angstrom" cutoff="9.0*angstrom">
+<vdW version="0.4" potential="Lennard-Jones-12-6" combining_rules="Lorentz-Berthelot" scale12="0.0" scale13="0.0" scale14="0.5" scale15="1.0" switch_width="1.0*angstrom" cutoff="9.0*angstrom" periodic_method="cutoff" nonperiodic_method="no-cutoff">
    <Atom smirks="[#1:1]" sigma="1.4870*angstrom" epsilon="0.0157*kilocalories_per_mole"/>
    <Atom smirks="[#1:1]-[#6]" sigma="1.4870*angstrom" epsilon="0.0157*kilocalories_per_mole"/>
    ...
@@ -326,6 +326,13 @@ van der Waals force parameters, which include repulsive forces arising from Paul
 For standard Lennard-Jones 12-6 potentials (specified via `potential="Lennard-Jones-12-6"`), the `epsilon` parameter denotes the well depth, while the size property can be specified either via providing the `sigma` attribute, such as `sigma="1.3*angstrom"`, or via the `r_0/2` (`rmin/2`) values used in AMBER force fields (here denoted `rmin_half` as in the example above).
 The two are related by `r0 = 2^(1/6)*sigma` and conversion is done internally into the `sigma` values used in OpenMM.
 
+Different cut-off treatments can be applied to periodic and non-periodic systems using the `periodic_method` and `nonperiodic_method` attributes, respectively. Each can take the following values:
+
+* `"cutoff"`: The vdW interaction is truncated at a distance specified by the `cutoff` attribute.
+* `"no-cutoff"`: The vdW interaction is not truncated.
+
+By default, `periodic_method="cutoff` and `nonperiodic_method="no-cutoff"`. If either attribute is set to `no-cutoff`, other attributes dealing with the cut-off are ignored.
+
 Attributes in the `<vdW>` tag specify the scaling terms applied to the energies of 1-2 (`scale12`, default: 0), 1-3 (`scale13`, default: 0), 1-4 (`scale14`, default: 0.5), and 1-5 (`scale15`, default: 1.0) interactions,
 as well as the distance at which a switching function is applied (`switch_width`, default: `"1.0*angstrom"`), and the cutoff (`cutoff`, default: `"9.0*angstroms"`). Version 0.3 assumes that the long-range dispersion handling is isotropic.
 
@@ -339,7 +346,7 @@ Support for [other Lennard-Jones mixing schemes](https://en.wikipedia.org/wiki/C
 
 Later revisions will add support for additional potential types (e.g., `Buckingham-exp-6`), as well as the ability to support arbitrary algebraic functional forms using a scheme such as
 ```XML
-<vdW version="0.3" potential="4*epsilon*((sigma/r)^12-(sigma/r)^6)" scale12="0.0" scale13="0.0" scale14="0.5" scale15="1" switch_width="8.0*angstrom" cutoff="9.0*angstrom">
+<vdW version="0.3" potential="4*epsilon*((sigma/r)^12-(sigma/r)^6)" scale12="0.0" scale13="0.0" scale14="0.5" scale15="1" switch_width="1.0*angstrom" cutoff="9.0*angstrom">
    <CombiningRules>
       <CombiningRule parameter="sigma" function="(sigma1+sigma2)/2"/>
       <CombiningRule parameter="epsilon" function="sqrt(epsilon1*epsilon2)"/>
@@ -362,6 +369,7 @@ Later revisions will also provide support for special interactions using the `<A
 | vdW section tag version | Tag attributes and default values                                                                                                                                                                                 | Required parameter attributes                 | Optional parameter attributes |
 |-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|-------------------------------|
 | 0.3                     | `potential="Lennard-Jones-12-6`, `combining_rules="Lorentz-Berthelot"`, `scale12="0"`, `scale13="0"`, `scale14="0.5"`, `scale15="1.0"`, `cutoff="9.0*angstrom"`, `switch_width="1.0*angstrom"`, `method="cutoff"` | `smirks`, `epsilon`, (`sigma` OR `rmin_half`) | `id`, `parent_id`             |
+| 0.4                     | `potential="Lennard-Jones-12-6`, `combining_rules="Lorentz-Berthelot"`, `scale12="0"`, `scale13="0"`, `scale14="0.5"`, `scale15="1.0"`, `cutoff="9.0*angstrom"`, `switch_width="1.0*angstrom"`, `periodic_method="cutoff"`, `nonperiodic_method="no-cutoff"` | `smirks`, `epsilon`, (`sigma` OR `rmin_half`) | `id`, `parent_id`             |
 
 
 ### `<Electrostatics>`