diff --git a/docs/enhancement-proposals/off-ep-0004.md b/docs/enhancement-proposals/off-ep-0004.md new file mode 100644 index 0000000..4008acb --- /dev/null +++ b/docs/enhancement-proposals/off-ep-0004.md @@ -0,0 +1,100 @@ +# OFF-EP 0004 — Handlers specify their dependence on other handlers + +**Status:** Proposed + +**Authors:** Matt Thompson + +**Stakeholders:** David Mobley, John Chodera, Jeffrey Wagner, Simon Boothroyd + +**Acceptance criteria:** + +**Created:** 2021-12-01 + +**Discussion:** [Issue #2](https://github.com/openforcefield/standards/issues/2) + +**Implementation:** [PR #24](https://github.com/openforcefield/standards/pull/24) + +## Abstract + +This OFF-EP requires that handlers state which other handlers they depend on, if any. + +## Motivation and Scope + +There are some cases in which it is not clear which parameter section(s) in a SMIRNOFF force field +depend on each other. For example, it is natural to define a TIP3P force field with a +`` section but neglect to add an `` section. This leads to +difficulties and strange behaviors in implementation. For example, there is no way to know what +cutoff method and distance should be used when the `` section is missing. This +ambiguity could be resolved by requiring that, if a force field defines any charge methods, it must +have a `` section. This sort of approach should be applied generally to all +handlers; developers implementing this SMIRNOFF specification may intuit these relationships over +time, but a better solution would be clarifying them in the specification itself. + +This appears to only be an issue when handlers **require** information from other handlers. There +are some cases in which one section **could** use information from another but does not **require** +it. For example, a `` section does not **require** to information from other sections, +but `` does (``, see above). A `` section that does not +define the distances of constrained bonds will **require** a corresponding `` section, but it +is also possible to define a `` section that does fully define all constraint distances +and does not require a `` section. + + +## Usage and Impact + +This proposal adds requirements to the specification that, in some cases, may require changes to +existing SMIRNOFF implementations. These changes should be improvements in the sense that +relationships between handlers will be clarified, but some changes may be breaking in the sense that +behavior could change. + +For example, continuing with the case of TIP3P water from above, a SMIRNOFF implementation after +this proposal should raise an exception if there is a `` section present but no +`` sectoin present, since the form depends on the latter. This raised exception +would be a breaking change, though it is easy to argue this is an improvement. + +## Backward compatibility + +For cases in which required sections are currently missing, this proposal will break backwards +compatibility by requiring that an exception should be raised. There should be no backwards +incompatibilities with optional handler interdependence. + +Each changed section (``, ``, ``) had its version +bumped to 0.4 to reflect this change. Up-converting from version 0.3 should be straightforward, +assuming that the changes made explicit here were already present implicitly. + + +## Detailed description + +This OFF-EP proposes that each parameter handler section + +* states which other sections **must** be present ("other required sections") and +* states which other sections it **may** interact with ("other optional sections"). + +If, after loading all setions from a file or other data source, a section that must be present +according to some other section is missing, an exception should be raised. + +Parameter handlers do not interact with other handlers not listed in either section. + +This OFF-EP adds the following information to the introduction of the `Parameter sections` section +of the SMIRNOFF specification: + +``` +For cases in which a parameter handler depends on another, each handler specifies which other +handlers must be present if information from another handler is required and also states which other +handlers it may optionally interact with. +``` + +and also updates some existing sections to clarify handler interedependence according to the current +implementation. `` added `` as an optional section and `` +and `` each added `` as a required sections. Each was bumped +to version 0.4. + +## Discussion + +- [Issue #2](https://github.com/openforcefield/standards/issues/2) +- [Toolkit issue #716](https://github.com/openforcefield/openff-toolkit/issues/716) describing the TIP3P case +- [Review of Toolkit PR #833](https://github.com/openforcefield/openff-toolkit/pull/833#issuecomment-816336358) describing the more fundamental issue + + +## Copyright + +*All OFF-EPs are explicitly [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).* diff --git a/docs/standards/smirnoff.md b/docs/standards/smirnoff.md index 16c18d1..7815cc7 100644 --- a/docs/standards/smirnoff.md +++ b/docs/standards/smirnoff.md @@ -220,9 +220,10 @@ For example, to ensure water molecules are assigned partial charges for [TIP3P]( ``` -| LibraryCharges section tag version | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | -|------------------------------------|--------------------------------------|---------------------------------|-------------------------------| -| 0.3 | | `smirks`, `charge` (indexed) | `name`, `id`, `parent_id` | +| LibraryCharges section tag version | Required parameter handlers | Optional parameter handlers | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | +|--|--|------------------------------------|--------------------------------------|---------------------------------|-------------------------------| +| 0.3 | | | | `smirks`, `charge` (indexed) | `name`, `id`, `parent_id` | +| 0.4 | `` | | | `smirks`, `charge` (indexed) | `name`, `id`, `parent_id` | @@ -263,10 +264,11 @@ Note that atoms for which library charges have already been applied are excluded Future additions will provide options for intelligently fragmenting large molecules and biopolymers, as well as a `capping` attribute to specify how fragments with dangling bonds are to be capped to allow these groups to be charged. -| ChargeIncrementModel section tag version | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | -|------------------------------------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|-------------------------------| -| 0.3 | `number_of_conformers="1"`, `partial_charge_method='AM1-Mulliken'` | `smirks`, `charge_increment` (indexed, must be equal to number of tagged atoms in `smirks`) | `name`, `id`, `parent_id` | -| 0.4 | `number_of_conformers="1"`, `partial_charge_method='AM1-Mulliken'` | `smirks`, `charge_increment` (indexed, must be equal to- or one less than- number of tagged atoms in `smirks`) | `name`, `id`, `parent_id` | +| ChargeIncrementModel section tag version | Required parameter handlers | Optional parameter handlers | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | +|--|--|------------------------------------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|-------------------------------| +| 0.3 | | | `number_of_conformers="1"`, `partial_charge_method='AM1-Mulliken'` | `smirks`, `charge_increment` (indexed, must be equal to number of tagged atoms in `smirks`) | `name`, `id`, `parent_id` | +| 0.4 | | | `number_of_conformers="1"`, `partial_charge_method='AM1-Mulliken'` | `smirks`, `charge_increment` (indexed, must be equal to- or one less than- number of tagged atoms in `smirks`) | `name`, `id`, `parent_id` | +| 0.5 | `` | | `number_of_conformers="1"`, `partial_charge_method='AM1-Mulliken'` | `smirks`, `charge_increment` (indexed, must be equal to- or one less than- number of tagged atoms in `smirks`) | `name`, `id`, `parent_id` | @@ -299,6 +301,7 @@ This method is provided solely for convenience in developing and exploring alter A SMIRNOFF force field consists of one or more force field term definition sections. For the most part, these sections independently define how a specific component of the potential energy function for a molecular system is supposed to be computed (such as bond stretch energies, or Lennard-Jones interactions), as well as how parameters are to be assigned for this particular term. +For cases in which a parameter handler depends on another, each handler specifies which other handlers must be present if information from another handler is required and also states which other handlers it may optionally interact with. Each parameter section contains a `version`, which encodes the behavior of the section, as well as the required and optional attributes the top-level tag and SMIRKS-based parameters. This decoupling of how parameters are assigned for each term provides a great deal of flexibility in composing new force fields while allowing a minimal number of parameters to be used to achieve accurate modeling of intramolecular forces. @@ -355,9 +358,9 @@ Later revisions will also provide support for special interactions using the ` ``` -| 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` | +| vdW section tag version | Required parameter handlers | Optional parameter handlers | 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` | ### `` @@ -383,9 +386,9 @@ Currently, no child tags are used because the charge model is specified via diff 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. -| 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 | +| Electrostatics section tag version | Required parameter handlers | Optional parameter handlers | 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 | ### `` @@ -432,10 +435,10 @@ This allows specification of force constants and lengths for bond orders 1 and 2 * `fractional_bondorder_method` defaults to `AM1-Wiberg`. * `fractional_bondorder_interpolation` defaults to `linear`, which is the only supported scheme for now. -| Bonds section tag version | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | -|---------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|-------------------------------| -| 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` | +| Bonds section tag version | Required parameter handlers | Optional parameter handlers | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | +|--|--|--------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|-------------------------------| +| 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` | ### `` @@ -457,9 +460,9 @@ If the `potential` attribute is omitted, it defaults to `harmonic`. **Note that AMBER and CHARMM define a modified functional form**, such that `U(r) = k*(theta-angle)^2`, so that force constants would need to be multiplied by two in order to be used in the SMIRNOFF format. -| Angles section tag version | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | -|-----------------------------|-----------------------------------|-------------------------------|-------------------------------| -| 0.3 | `potential="harmonic"` | `smirks`, `angle`, `k` | `id`, `parent_id` | +| Angles section tag version | Required parameter handlers | Optional parameter handlers | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | +|--|--|-----------------------------|-----------------------------------|-------------------------------|-------------------------------| +| 0.3 | | | `potential="harmonic"` | `smirks`, `angle`, `k` | `id`, `parent_id` | ### `` @@ -530,10 +533,10 @@ Some key usage points: * `fractional_bondorder_method` defaults to `AM1-Wiberg`. * `fractional_bondorder_interpolation` defaults to `linear`, which is the only supported scheme for now. -| 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` | +| ProperTorsions section tag version | Required parameter handlers | Optional parameter handlers | 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` | ### `` @@ -559,9 +562,9 @@ The improper torsion energy is computed as the average over all three impropers This avoids the dependence on arbitrary atom orderings that occur in more traditional typing engines such as those used in AMBER. The *second* atom in an improper (in the example above, the trivalent carbon) is the central atom in the trefoil. -|ImproperTorsions 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` | +|ImproperTorsions section tag version | Required parameter handlers | Optional parameter handlers | 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` | ### `` @@ -611,9 +614,9 @@ The `ACE` model permits two additional parameters to be specified: * The `surface_area_penalty` attribute specifies the surface area penalty for the `ACE` model. (Default: `5.4 calories/mole/angstroms**2`) * The `solvent_radius` attribute specifies the solvent radius. (Default: `1.4 angstroms`) -| GBSA section tag version | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | -|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|-------------------------------| -| 0.3 | `gb_model="OBC1"`, `solvent_dielectric="78.5"`, `solute_dielectric="1"`, `sa_model="ACE"`, `surface_area_penalty="5.4*calories/mole/angstrom**2"`, `solvent_radius="1.4*angstrom"` | `smirks`, `radius`, `scale` | `id`, `parent_id` | +| GBSA section tag version | Required parameter handlers | Optional parameter handlers | Tag attributes and default values | Required parameter attributes | Optional parameter attributes | +|--|--|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|-------------------------------| +| 0.3 | | | `gb_model="OBC1"`, `solvent_dielectric="78.5"`, `solute_dielectric="1"`, `sa_model="ACE"`, `surface_area_penalty="5.4*calories/mole/angstrom**2"`, `solvent_radius="1.4*angstrom"` | `smirks`, `radius`, `scale` | `id`, `parent_id` | ### `` @@ -650,9 +653,10 @@ Typical molecular simulation practice is to constrain all bonds to hydrogen to t ``` -| Constraint section tag version | Required tag attributes and default values | Required parameter attributes | Optional parameter attributes | -|---------------------------------|--------------------------------------------|-------------------------------|-------------------------------| -| 0.3 | | `smirks` | `distance` | +| Constraint section tag version | Required parameter handlers | Optional parameter handlers | Required tag attributes and default values | Required parameter attributes | Optional parameter attributes | +|--|--|---------------------------------|--------------------------------------------|-------------------------------|-------------------------------| +| 0.3 | | | | `smirks` | `distance` | +| 0.4 | | `` | | `smirks` | `distance` | ## Advanced features @@ -703,9 +707,9 @@ In the SMIRNOFF format, these are encoded as: ``` -| VirtualSites section tag version | Tag attributes and default values | Required parameter attributes and default values | Optional parameter attributes | -|------------------------------------|--------------------------------------|----------------------------------------------------|-------------------------------| -| 0.3 | `exclusion_policy="parents"` | `smirks`, `type`, `distance`, `charge_increment` (indexed), `inPlaneAngle` IF `type="MonovalentLonePair"`, `outOfPlaneAngle` IF `type="MonovalentLonePair` OR `type="DivalentLonePair"`, `sigma=0.*angstrom`, `epsilon=0.*kilocalories_per_mole`, `name="EP"`, `match="all_permutations"` IF `type=BondCharge` OR `type="MonovalentLonePair` OR `type="DivalentLonePair"`, `match="once"` IF `type="TrivalentLonePair` | N/A | +| VirtualSites section tag version | Required paramter handlers | Optional parameter handlers | Tag attributes and default values | Required parameter attributes and default values | Optional parameter attributes | +|--|--|------------------------------------|--------------------------------------|----------------------------------------------------|-------------------------------| +| 0.3 | | | `exclusion_policy="parents"` | `smirks`, `type`, `distance`, `charge_increment` (indexed), `inPlaneAngle` IF `type="MonovalentLonePair"`, `outOfPlaneAngle` IF `type="MonovalentLonePair` OR `type="DivalentLonePair"`, `sigma=0.*angstrom`, `epsilon=0.*kilocalories_per_mole`, `name="EP"`, `match="all_permutations"` IF `type=BondCharge` OR `type="MonovalentLonePair` OR `type="DivalentLonePair"`, `match="once"` IF `type="TrivalentLonePair` | N/A | ### Aromaticity models