OFF-EP 0005b

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

@@ -0,0 +1,144 @@
+# OFF-EP 0005 — Allow different electrostatics methods to be used on period and non-periodic systems
+
+**Status:** Accepted
+
+**Authors:** Matt Thompson and John Chodera, Jeffrey Wagner, Simon Boothroyd
+
+**Stakeholders:** Simon Boothroyd, Jeffrey Wagner, David Mobley, John Chodera
+
+**Acceptance criteria:** Unanimity
+
+**Created:** 2020-03-15
+
+**Discussion:** [Issue #29](https://github.com/openforcefield/standards/issues/29)
+
+**Implementation:** [``openff-standards``](https://github.com/openforcefield/openff-standards)
+
+## Abstract
+
+This change refines the way the `<Electrostatics>` tag defines behavior in periodic
+(i.e., condensed-phase) and non-periodic (i.e., gas phase) systems to clarify the
+intended true electrostatics models in each case. Implementations are permitted
+to make approximations to these specified models---e.g. Particle-Mesh Ewald (PME)---
+as a controlled approximation to Ewald provided the approximation accuracy is controlled.
+
+## Motivation and Scope
+
+In version 0.3 of the `<Electrostatics>` tag, the default electrostatics method is
+`method="PME"`, with `reaction-field` also a permitted choice.
+
+These definitions present several issues that this OFF-EP attempts to solve:
+
+* `PME` is intended to be a permissible approximation to the true electrostatics model, Ewald
+* The boundary conditions (e.g. dielectric at infinity) for the Ewald sum are not specified
+* The Ewald method is only intended for periodic systems; unmodified vacuum electrostatics are intended for non-periodic systems
+* The treatment of intramolecular electrostatics exceptions is unspecified
+* The choice `reaction-field` does not uniquely specify the functional form for the true reaction-field model intended; many variants are available
+* The solvent dielectric constant was not specified.
+* Cutoffs were not specified
+* The physical constants used to compute the potential were unspecified
+
+To solve these issues, this OFF-EP proposes:
+
+* The `method` attribute is replaced with `periodic_potential` in analogy to other parameters that use the `potential` term to specify the functional form or a common choice
+* The `periodic_potential` attribute defaults to `Ewald3D-ConductingBoundary` as a valid keyword that states that the Ewald periodic sum with conducting boundary conditions should be the true potential used for periodic systems
+* PME (and other methods) are permissible approximations to Ewald as long as they are controlled.
+* For reaction field or other methods, the `periodic_potential` can specify the exact functional form used for the periodic potential or a keyword denoting a common choice, along with the optional `cutoff` and `solvent_dielectric` attributes
+* The `nonperiodic_potential` attribute defaults to `Coulomb` indicating the Coulomb potential is to be used in non-periodic systems, though other functional forms are accepted.
+* The `exception_potential` attribute defaults to `Coulomb`, indicating the Coulomb potential is to be used for exceptions, though other functional forms are accepted.
+* We explicitly specify which self-consistent physical constants should be used.
+
+## Usage and Impact
+
+Since most force fields use some flavor of PME for periodic systems and something similar to
+`nonperiodic_potential="Coulomb"` for non-periodic systems, the default attributes for this tag will
+likely be the most commonly-used. Splitting `method` out into explicit attributes to specify periodic,
+nonperiodic, and exception potential energy terms, however, makes it less
+ambiguous how electrostatics should be handled in each case and decouples the method used in each
+case.
+
+Users are recommended to consider upgrading from the default attribute values of 0.3 to 0.4 to avoid
+continuing to use this ambiguity. Implementations may wish to execute this up-conversion automatically (see below).
+
+If backward-compatibility is provided as specified below, users of old force fields will not need to update their force field definitions.
+
+## Backward compatibility
+
+Implementations may wish to add up-converters from old versions. An up-converter could convert the following tag header
+```
+<Electrostatics version="0.3" method="PME" scale12="0.0" scale13="0.0" scale14="0.833333" scale15="1.0"/>
+```
+to a header using version 0.4, which for this case could be
+```
+<Electrostatics version="0.4" periodic_potential="Ewald3D-ConductingBoundary" nonperiodic_potential="Coulomb" exception_potential="Coulomb" scale12="0.0" scale13="0.0" scale14="0.833333" scale15="1.0"/>
+```
+
+Concretely, the following conversions should be performed:
+
+|  0.3 `method`    |  0.4 `periodic_potential`    |  0.4 `nonperiodic_potential`  |  0.4 `exception_potential`  |
+|------------------|------------------------------|-------------------------------|-----------------------------|
+|  `PME`           | `Ewald3D-ConductingBoundary` | `Coulomb`                     | `Coulomb`                   |
+| `reaction-field` | `charge1*charge2/(4*pi*epsilon0)*(1/r + k_rf*r^2 - c_rf); k_rf=(cutoff^(-3))*(solvent_dielectric-1)/(2*solvent_dielectric+1); c_rf=cutoff^(-1)*(3*solvent_dielectric)/(2*solvent_dielectric+1)`             | `Coulomb`                     | `Coulomb`                   |
+|  `Coulomb`       | `Ewald3D-ConductingBoundary` | `Coulomb`                     | `Coulomb`                   |
+
+If the 0.3 section's `method` does not actually involve the use of a `cutoff` or `switch_width` (such as is the case if `method="PME"`), those values may be set to their defaults in the 0.4 `Electrostatics` section.
+
+The value of the 0.4 `Electrostatics` section's `solvent_dielectric` should be set to `none`.
+
+## Detailed description
+
+### In the general SMIRNOFF spec description
+
+A section is added stating that [CODATA 2018](https://physics.nist.gov/cuu/Constants/index.html) physical constants are used in all released SMIRNOFF versions to date.
+Future OFF-EPs may migrate the specification of which self-consistent physical constants are used to a higher-level attribute.
+
+### In the `Electrostatics` section
+
+The `method` tag attribute is **removed** and replaced with `periodic_potential`, `nonperiodic_potential`, and `exception_potential`.
+
+The optional `solvent_dielectric` tag attribute is added to specify the solvent dielectric used with finite-ranged potentials, defaulting to `none`.
+
+For `periodic_potential`:
+
+* `Ewald3D-ConductingBoundary` (default) denotes that the Ewald potential with conducting (dielectric 0) boundary conditions are used
+* A function denotes that the specified function should be used, which may make use of `cutoff`, `switch_width`, and/or `solvent_dielectric` terms
+* Future OFF-EPs may add specific keywords for common choices of reaction field electrostatics
+
+For `nonperiodic_potential`:
+
+* `Coulomb` (default) denotes that the standard Coulomb potential should be used with no cutoff or reaction-field attenuation
+* A function denotes that the specified function should be used, which may make use of `cutoff`, `switch_width`, and/or `solvent_dielectric` terms
+
+For `exception_potential`:
+
+* `Coulomb` (default) denotes that the standard Coulomb potential should be used with no cutoff or reaction-field attenuation
+* A function denotes that the specified function should be used, which may make use of `cutoff`, `switch_width`, and/or `solvent_dielectric` terms
+
+## Examples
+
+Ewald electrostatics (permitting PME to be used) are used for periodic systems; Coulomb used for non-periodic:
+```
+<Electrostatics version="0.4" periodic_cutoff="None" periodic_potential="Ewald3D-ConductingBoundary" nonperiodic_potential="Coulomb" exception_potential="Coulomb" scale12="0.0" scale13="0.0" scale14="0.833333" scale15="1.0"/>
+```
+
+Shifted reaction field electrostatics (e.g. from [OpenMM](http://docs.openmm.org/7.6.0/userguide/theory/02_standard_forces.html#coulomb-interaction-with-cutoff)) are used for periodic systems; Coulomb used for non-periodic:
+```
+<Electrostatics version="0.4" periodic_potential="charge1*charge2/(4*pi*epsilon0)*(1/r + k_rf*r^2 - c_rf); k_rf=(cutoff^(-3))*(solvent_dielectric-1)/(2*solvent_dielectric+1); c_rf=cutoff^(-1)*(3*solvent_dielectric)/(2*solvent_dielectric+1)" solvent_dielectric="78.5" periodic_cutoff="12*angstroms" nonperiodic_potential="Coulomb" exception_potential="Coulomb" scale12="0.0" scale13="0.0" scale14="0.833333" scale15="1.0"/>
+```
+
+## Alternatives
+
+See [OFF-EP 0005](https://github.com/openforcefield/standards/pull/30).
+
+## Discussion
+
+- Toolkit [#1084](https://github.com/openforcefield/openff-toolkit/issues/1084)
+- Standards [#29](https://github.com/openforcefield/standards/issues/29)
+- Alternatives: [OFF-EP 0005](https://github.com/openforcefield/standards/pull/30)
+
+## Copyright
+
+This template is based upon the
+[OFF-EP template](https://openforcefield.github.io/standards/enhancement-proposals/off-ep-template/).
+
+This document is explicitly [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).

docs/index.md

@@ -27,6 +27,7 @@ stages of discussion or completion.
 ##### Accepted Proposals
 
 * [OFF-EP 1 — Clarify that constraint distances override equilibrium bond distances](enhancement-proposals/off-ep-0001.md)
+* [OFF-EP 5 — Resolve ambiguity over PME electrostatics for nonperiodic systems](enhancement-proposals/off-ep-0005.md)
 * [OFF-EP 6 — Define virtual site exclusion policy](enhancement-proposals/off-ep-0006.md)
 
 ##### Open Proposals

docs/standards/smirnoff.md

@@ -104,6 +104,10 @@ The `<Date>` tag should conform to [ISO 8601 date formatting guidelines](https:/
 !!! todo
     Should we have a separate `<Metadata>` or `<Provenance>` section that users can add whatever they want to? This would minimize the potential for accidentally colliding with other tags we add in the future.
 
+### Physical constants
+
+All published SMIRNOFF specification versions are intended for use with CODATA 2018 physical constants.  
+
 ### Parameter generators
 
 Within the `<SMIRNOFF>` tag, top-level tags encode parameters for a force field based on a SMARTS/SMIRKS-based specification describing the chemical environment the parameters are to be applied to.
@@ -364,13 +368,27 @@ Later revisions will also provide support for special interactions using the `<A
 
 Electrostatic interactions are specified via the `<Electrostatics>` tag.
 ```XML
-<Electrostatics version="0.3" method="PME" scale12="0.0" scale13="0.0" scale14="0.833333" scale15="1.0"/>
+<Electrostatics version="0.4" periodic_potential="Ewald3D-ConductingBoundary" nonperiodic_potential="Coulomb" exception_potential="Coulomb" scale12="0.0" scale13="0.0" scale14="0.833333" scale15="1.0"/>
 ```
-The `method` attribute specifies the manner in which electrostatic interactions are to be computed:
 
-* `PME` - [particle mesh Ewald](https://docs.openmm.org/latest/userguide/theory.html#coulomb-interaction-with-particle-mesh-ewald) should be used (DEFAULT); can only apply to periodic systems
-* `reaction-field` - [reaction-field electrostatics](https://docs.openmm.org/latest/userguide/theory.html#coulomb-interaction-with-cutoff) should be used; can only apply to periodic systems
-* `Coulomb` - direct Coulomb interactions (with no reaction-field attenuation) should be used
+Some methods for computing electrostatic interactions are not valid for periodic systems, so
+separate methods must be specified for periodic (`periodic_potential`) and non-periodic
+(`nonperiodic_potential`) systems.
+
+The `periodic_potential` attribute specifies the manner in which electrostatic interactions are to be computed in periodic systems. Allowed values are:
+
+* `Ewald3D-ConductingBoundary` (default) denotes that a method like [particle mesh Ewald](https://docs.openmm.org/latest/userguide/theory.html#coulomb-interaction-with-particle-mesh-ewald) should be used
+* A function denotes that the specified function should be used, which may make use of `cutoff`, `switch_width`, and/or `solvent_dielectric` terms
+
+The `nonperiodic_potential` attribute specifies the manner in which electrostatic interactions are to be computed in non-periodic systems. Allowed values are:
+
+* `Coulomb` (default) denotes that the standard Coulomb potential should be used with no cutoff or reaction-field attenuation
+* A function denotes that the specified function should be used, which may make use of `cutoff`, `switch_width`, and/or `solvent_dielectric` terms
+
+The `exception_potential` attribute specifies the treatment of intramolecular electrostatics exceptions, such as scaled 1-4 interactions. Allowed values are:
+
+* `Coulomb` (default) denotes that the standard Coulomb potential should be used with no cutoff or reaction-field attenuation
+* A function denotes that the specified function should be used, which may make use of `cutoff`, `switch_width`, and/or `solvent_dielectric` terms
 
 The interaction scaling parameters applied to atoms connected by a few bonds are
 
@@ -381,11 +399,14 @@ The interaction scaling parameters applied to atoms connected by a few bonds are
 
 Currently, no child tags are used because the charge model is specified via different means (currently library charges or BCCs).
 
-For methods where the cutoff is not simply an implementation detail but determines the potential energy of the system (`reaction-field` and `Coulomb`), the `cutoff` distance must also be specified, and a `switch_width` if a switching function is to be used.
+For potentials where the cutoff determines the potential energy of the system (such as custom expression or reaction field methods), the appropriate `cutoff` distance must also be specified, and the appropriate `switch_width` should be set to a numerical value if a switching function is to be used.
+
+It is possible to define an Electrostatics section where no potential uses `cutoff`, `switch_width`, or `solvent_dielectric`. In these cases it is strongly recommended that these values be set to `none` to avoid ambiguity. 
 
 | Electrostatics section tag version | Tag attributes and default values                                                                                                         | Required parameter attributes | Optional parameter attributes |
 |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|-------------------------------|
-| 0.3                                | `scale12="0"`, `scale13="0"`, `scale14="0.833333"`, `scale15="1.0"`, `cutoff="9.0*angstrom"`, `switch_width="0*angstrom"`, `method="PME"`  | N/A                           | N/A                           |
+| 0.3                                | `scale12="0"`, `scale13="0"`, `scale14="0.833333"`, `scale15="1.0"`, `cutoff="9.0*angstrom"`, `switch_width="0*angstrom"`, `method="PME"` | N/A                           | N/A                           |
+| 0.4                                | `scale12="0"`, `scale13="0"`, `scale14="0.833333"`, `scale15="1.0"`, `cutoff="none"`, `switch_width="none"`, `periodic_potential="Ewald3D-ConductingBoundary"`, `nonperiodic_potential="Coulomb"`, `exception_potential="Coulomb"`, `solvent_dielectric="none"`   | N/A                           | N/A                           |
 
 
 ### `<Bonds>`

mkdocs.yml

@@ -10,6 +10,7 @@ nav:
     - 'OFF-EP 0 - Purpose and Process': 'enhancement-proposals/off-ep-0000.md'
     - 'OFF-EP X - Template': 'enhancement-proposals/off-ep-template.md'
     - 'OFF-EP 1 - Clarify that constraint distances override equilibrium bond distances': 'enhancement-proposals/off-ep-0001.md'
+    - 'OFF-EP 5 - Resolve ambiguity over PME electrostatics for nonperiodic systems': 'enhancement-proposals/off-ep-0005.md'
     - 'OFF-EP 6 - Define virtual site exclusion policy': 'enhancement-proposals/off-ep-0006.md'
 
 markdown_extensions: