From 3cd017e863cc98ca786f51cdf27bf0770ec22cb1 Mon Sep 17 00:00:00 2001 From: "Matthew W. Thompson" Date: Fri, 12 Jul 2024 15:45:48 -0500 Subject: [PATCH 1/5] DOC: Document that HMR is ignored in `from_openmm` --- docs/index.md | 1 + docs/using/edges.md | 13 +++++++++++++ 2 files changed, 14 insertions(+) create mode 100644 docs/using/edges.md diff --git a/docs/index.md b/docs/index.md index 1178828ca..15bc0ffb4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,6 +29,7 @@ using/collections.md using/migrating.md using/plugins.md using/status.md +using/edges.md using/experimental.md ``` diff --git a/docs/using/edges.md b/docs/using/edges.md new file mode 100644 index 000000000..9d7b1b9ad --- /dev/null +++ b/docs/using/edges.md @@ -0,0 +1,13 @@ +# Sharp edges + +## Quirks of `from_openmm` + +### Modified masses are ignored + +The OpenFF toolkit does not support isotopes or modifiying masses from the values defined in the periodic table. In the `Topology` and `Molecule` classes, particles masses are defined only by their atomic number. When topologies are read from OpenMM, the particle mass is ignored and the atomic number of the element is read. + +As a consequence, systems with hydrogen mass repartitioning (HMR) applied have HMR un-done (masses are shifted from hydrogens back to their heavy atoms). To re-apply HMR (shift masses back to hydrogens), use the API at export time, likely with a `hydrogen_mass` argument in an export method. + +For updates, [search "HMR" in the issue tracker](https://github.com/search?q=repo%3Aopenforcefield%2Fopenff-interchange+hmr&type=issues&s=updated&o=desc) or raise a [new issue](https://github.com/openforcefield/openff-interchange/issues/new/choose). + +Keywords: HMR, hydrogen mass repartioning From 45f24cd5711807f7c264b7cbda9dee72f6fe0b92 Mon Sep 17 00:00:00 2001 From: "Matthew W. Thompson" Date: Fri, 12 Jul 2024 16:12:52 -0500 Subject: [PATCH 2/5] DOC: Document GROMACS requires 1-indexed residues --- docs/using/edges.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/using/edges.md b/docs/using/edges.md index 9d7b1b9ad..dd2d44145 100644 --- a/docs/using/edges.md +++ b/docs/using/edges.md @@ -11,3 +11,13 @@ As a consequence, systems with hydrogen mass repartitioning (HMR) applied have H For updates, [search "HMR" in the issue tracker](https://github.com/search?q=repo%3Aopenforcefield%2Fopenff-interchange+hmr&type=issues&s=updated&o=desc) or raise a [new issue](https://github.com/openforcefield/openff-interchange/issues/new/choose). Keywords: HMR, hydrogen mass repartioning + +## Quirks with GROMACS + +### Residue indices must be begin at 1 + +Whether by informal convention or official standard, residue numbers in GROMACS files being at 1. Other tools may start the residue numbers at 0. If a topology contains residue numbers below 1, exporting to GROMACS will trigger an error (though not necessarily while exporting to other formats). A workaround for 0-indexed residue numbers is to simply increment all residue numbers by 1. + +For more, see [issue #1007](https://github.com/openforcefield/openff-interchange/issues/1007) + +Keywords: GROMACS, residue number, resnum, residue index From 2b301854dea377cd911534f764723f635aec5cbb Mon Sep 17 00:00:00 2001 From: "Matthew W. Thompson" Date: Tue, 16 Jul 2024 14:38:41 -0500 Subject: [PATCH 3/5] DOC: Document missing force constants in `from_openmm` --- docs/using/edges.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/using/edges.md b/docs/using/edges.md index dd2d44145..109ccfe51 100644 --- a/docs/using/edges.md +++ b/docs/using/edges.md @@ -10,13 +10,23 @@ As a consequence, systems with hydrogen mass repartitioning (HMR) applied have H For updates, [search "HMR" in the issue tracker](https://github.com/search?q=repo%3Aopenforcefield%2Fopenff-interchange+hmr&type=issues&s=updated&o=desc) or raise a [new issue](https://github.com/openforcefield/openff-interchange/issues/new/choose). -Keywords: HMR, hydrogen mass repartioning +Keywords: OpenMM, HMR, hydrogen mass repartioning + +### Force constants of constrained bonds may be lost in conversions + +Commonly, OpenMM systems prepared by other tools constrain bonds (i.e. bonds between hydrogen and heavy atoms) and/or use rigid waters. These (topological) bonds lack force constants, which may be required by other engines. + +For example, consider an OpenMM system prepared with `createSystem(..., constraints=HBonds, rigidWaters=True)` and then imported with `Interchange.from_openmm`. The constrained bonds (including all bonds in waters) don't contain physics parameter (force constant `k` and equilibrium bond length). (There parameters are allowed to exist in a `HarmonicBondForce`, and sometimes they do, but there's also no reason for them to exist when running OpenMM simulations with these constraints, so they're usually dropped.) When export this system to GROMACS or another engine that needs these parameters, the export will either crash due to missing parameters or silently write a file with some missing or blank parameters. + +For more, see [issue #1005](https://github.com/openforcefield/openff-interchange/issues/1005#issue-2405679510). + +Keywords: OpenMM, GROMACS, constraints, bond constraints, rigid water ## Quirks with GROMACS ### Residue indices must be begin at 1 -Whether by informal convention or official standard, residue numbers in GROMACS files being at 1. Other tools may start the residue numbers at 0. If a topology contains residue numbers below 1, exporting to GROMACS will trigger an error (though not necessarily while exporting to other formats). A workaround for 0-indexed residue numbers is to simply increment all residue numbers by 1. +Whether by informal convention or official standard, residue numbers in GROMACS files begin at 1. Other tools may start the residue numbers at 0. If a topology contains residue numbers below 1, exporting to GROMACS will trigger an error (though not necessarily while exporting to other formats). A workaround for 0-indexed residue numbers is to simply increment all residue numbers by 1. For more, see [issue #1007](https://github.com/openforcefield/openff-interchange/issues/1007) From 1c6529f1cf96537771d0405aa1934612a972ef4a Mon Sep 17 00:00:00 2001 From: "Matthew W. Thompson" Date: Tue, 16 Jul 2024 14:45:56 -0500 Subject: [PATCH 4/5] DOC: Reference user guide in `from_openmm` docstring --- docs/using/edges.md | 6 +++--- openff/interchange/components/interchange.py | 8 ++++++++ 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/using/edges.md b/docs/using/edges.md index 109ccfe51..f0cebf3ca 100644 --- a/docs/using/edges.md +++ b/docs/using/edges.md @@ -4,9 +4,9 @@ ### Modified masses are ignored -The OpenFF toolkit does not support isotopes or modifiying masses from the values defined in the periodic table. In the `Topology` and `Molecule` classes, particles masses are defined only by their atomic number. When topologies are read from OpenMM, the particle mass is ignored and the atomic number of the element is read. +The OpenFF Toolkit does not support isotopes or modifiying masses from the values defined in the periodic table. In the `Topology` and `Molecule` classes, particles masses are defined only by their atomic number. When topologies are read from OpenMM, the particle mass is ignored and the atomic number of the element is read and used to define the atomic properties. -As a consequence, systems with hydrogen mass repartitioning (HMR) applied have HMR un-done (masses are shifted from hydrogens back to their heavy atoms). To re-apply HMR (shift masses back to hydrogens), use the API at export time, likely with a `hydrogen_mass` argument in an export method. +As a consequence, systems with hydrogen mass repartitioning (HMR) applied have HMR "un-done" (masses are effectively shifted from hydrogens back to their heavy atoms). To re-apply HMR (shift masses back to hydrogens), use the API at export time, likely with a `hydrogen_mass` argument in an export method. For updates, [search "HMR" in the issue tracker](https://github.com/search?q=repo%3Aopenforcefield%2Fopenff-interchange+hmr&type=issues&s=updated&o=desc) or raise a [new issue](https://github.com/openforcefield/openff-interchange/issues/new/choose). @@ -16,7 +16,7 @@ Keywords: OpenMM, HMR, hydrogen mass repartioning Commonly, OpenMM systems prepared by other tools constrain bonds (i.e. bonds between hydrogen and heavy atoms) and/or use rigid waters. These (topological) bonds lack force constants, which may be required by other engines. -For example, consider an OpenMM system prepared with `createSystem(..., constraints=HBonds, rigidWaters=True)` and then imported with `Interchange.from_openmm`. The constrained bonds (including all bonds in waters) don't contain physics parameter (force constant `k` and equilibrium bond length). (There parameters are allowed to exist in a `HarmonicBondForce`, and sometimes they do, but there's also no reason for them to exist when running OpenMM simulations with these constraints, so they're usually dropped.) When export this system to GROMACS or another engine that needs these parameters, the export will either crash due to missing parameters or silently write a file with some missing or blank parameters. +For example, consider an OpenMM system prepared, from the OpenMM API, with `ForceField.createSystem(..., constraints=HBonds, rigidWaters=True)` and then imported with `Interchange.from_openmm`. The constrained bonds (including all bonds in waters) don't contain physics parameters (force constant `k` and equilibrium bond length). (These parameters are allowed to exist in a `HarmonicBondForce`, and sometimes they do, but there's also no reason for them to be defined when running OpenMM simulations with these constraints, so they're usually dropped.) When exporting this system to GROMACS or another engine that needs these parameters, the export will either crash due to missing parameters or silently write a file with some missing or blank parameters. For more, see [issue #1005](https://github.com/openforcefield/openff-interchange/issues/1005#issue-2405679510). diff --git a/openff/interchange/components/interchange.py b/openff/interchange/components/interchange.py index 75d070f78..c5fd7a727 100644 --- a/openff/interchange/components/interchange.py +++ b/openff/interchange/components/interchange.py @@ -414,6 +414,14 @@ def to_openmm_system( system : openmm.System The OpenMM System object. + Notes + ----- + There are some sharp edges and quirks when using this method. Be aware of some documented + issues in the "Sharp edges" section of the user guide. If you encounter surprising + behavior that is not documented, please raise an issue. + + https://docs.openforcefield.org/projects/interchange/en/stable/using/edges.html + """ from openff.interchange.interop.openmm import ( to_openmm_system as _to_openmm_system, From a3d93b4720cf2256c6675ab9f01566eb453d20d5 Mon Sep 17 00:00:00 2001 From: Matt Thompson Date: Wed, 17 Jul 2024 08:25:55 -0500 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Josh A. Mitchell --- docs/using/edges.md | 10 +++++----- openff/interchange/components/interchange.py | 4 +--- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/using/edges.md b/docs/using/edges.md index f0cebf3ca..06211d4a9 100644 --- a/docs/using/edges.md +++ b/docs/using/edges.md @@ -4,9 +4,9 @@ ### Modified masses are ignored -The OpenFF Toolkit does not support isotopes or modifiying masses from the values defined in the periodic table. In the `Topology` and `Molecule` classes, particles masses are defined only by their atomic number. When topologies are read from OpenMM, the particle mass is ignored and the atomic number of the element is read and used to define the atomic properties. +The OpenFF Toolkit does not support isotopes or atomic masses other than the values defined in the periodic table. In the `Topology` and `Molecule` classes, particles masses are defined only by their atomic number. When topologies are read from OpenMM, the particle mass is ignored and the atomic number of the element is read and used to define the atomic properties. -As a consequence, systems with hydrogen mass repartitioning (HMR) applied have HMR "un-done" (masses are effectively shifted from hydrogens back to their heavy atoms). To re-apply HMR (shift masses back to hydrogens), use the API at export time, likely with a `hydrogen_mass` argument in an export method. +As a consequence, any hydrogen mass repartitioning (HMR) applied to a system is "un-done" upon import --- mass is shifted back from hydrogens to their heavy atoms. To re-apply HMR (shift masses back to hydrogens), use the appropriate API at export time, typically with an export method's `hydrogen_mass` argument. For updates, [search "HMR" in the issue tracker](https://github.com/search?q=repo%3Aopenforcefield%2Fopenff-interchange+hmr&type=issues&s=updated&o=desc) or raise a [new issue](https://github.com/openforcefield/openff-interchange/issues/new/choose). @@ -14,9 +14,9 @@ Keywords: OpenMM, HMR, hydrogen mass repartioning ### Force constants of constrained bonds may be lost in conversions -Commonly, OpenMM systems prepared by other tools constrain bonds (i.e. bonds between hydrogen and heavy atoms) and/or use rigid waters. These (topological) bonds lack force constants, which may be required by other engines. +Commonly, OpenMM systems prepared by other tools constrain bonds (i.e. bonds between hydrogen and heavy atoms) and/or use rigid water models. These topological bonds lack force constants, which are required by some other engines even though they do not affect the behavior of the simulation. -For example, consider an OpenMM system prepared, from the OpenMM API, with `ForceField.createSystem(..., constraints=HBonds, rigidWaters=True)` and then imported with `Interchange.from_openmm`. The constrained bonds (including all bonds in waters) don't contain physics parameters (force constant `k` and equilibrium bond length). (These parameters are allowed to exist in a `HarmonicBondForce`, and sometimes they do, but there's also no reason for them to be defined when running OpenMM simulations with these constraints, so they're usually dropped.) When exporting this system to GROMACS or another engine that needs these parameters, the export will either crash due to missing parameters or silently write a file with some missing or blank parameters. +For example, consider an OpenMM system prepared, from the OpenMM API, with `ForceField.createSystem(..., constraints=HBonds, rigidWaters=True)` and then imported with `Interchange.from_openmm`. The constrained bonds, including all bonds in waters, don't contain physics parameters (particularly the force constant `k`). These parameters are typically dropped from the corresponding `HarmonicBondForce` when running OpenMM simulations with these sorts of constraints. When exporting this system to GROMACS or another engine that needs these parameters, the export will either crash due to missing parameters or silently write a file with some missing or blank parameters. For more, see [issue #1005](https://github.com/openforcefield/openff-interchange/issues/1005#issue-2405679510). @@ -24,7 +24,7 @@ Keywords: OpenMM, GROMACS, constraints, bond constraints, rigid water ## Quirks with GROMACS -### Residue indices must be begin at 1 +### Residue indices must begin at 1 Whether by informal convention or official standard, residue numbers in GROMACS files begin at 1. Other tools may start the residue numbers at 0. If a topology contains residue numbers below 1, exporting to GROMACS will trigger an error (though not necessarily while exporting to other formats). A workaround for 0-indexed residue numbers is to simply increment all residue numbers by 1. diff --git a/openff/interchange/components/interchange.py b/openff/interchange/components/interchange.py index c5fd7a727..3bce1f217 100644 --- a/openff/interchange/components/interchange.py +++ b/openff/interchange/components/interchange.py @@ -417,11 +417,9 @@ def to_openmm_system( Notes ----- There are some sharp edges and quirks when using this method. Be aware of some documented - issues in the "Sharp edges" section of the user guide. If you encounter surprising + issues in the :doc:`/using/edges` section of the user guide. If you encounter surprising behavior that is not documented, please raise an issue. - https://docs.openforcefield.org/projects/interchange/en/stable/using/edges.html - """ from openff.interchange.interop.openmm import ( to_openmm_system as _to_openmm_system,