Document how to opt in to pseudo-vaccum approximation (#1362)

* DOC: Document how to opt in to pseudo-vaccum approximation

* FIX: Update exception name, add test

* DOC: Add section header

* LINT: Disable `markdownlint` where Sphinx needs non-blank lines

* Update docs/using/edges.md

Co-authored-by: Josh A. Mitchell <yoshanuikabundi@gmail.com>

* DOC: Add note on vdW cut-off in vacuum

---------

Co-authored-by: Josh A. Mitchell <yoshanuikabundi@gmail.com>

Author: mattwthompson

docs/using/edges.md

@@ -1,5 +1,39 @@
 # Sharp edges
 
+(no-cutoff-support)=
+## Some MM engines do not support "no-cutoff" non-bonded methods <!-- markdownlint-disable-line -->
+
+SMIRNOFF force fields support a non-bonded treatment in which, for non-periodic systems, the vdW interactions are not truncated. OpenFF force fields commonly use this option (`nonperiodic_method="no-cutoff"`).
+
+OpenMM supports this with its `NoCutoff` method in `openmm.NonbondedForce` and similar forces. There is, however, no clear analog in GROMACS (with versions after 2020) or Amber. A common approach is to use the "pseudo-vacuum" approximation in which a very large box is used, i.e. 10 nm cubic box lengths for a system of a single small molecule.
+
+This approach is an approximation and therefore must be opted into by defining a periodic box, either on the input topology:
+
+```python
+from openff.toolkit import Quantity, ForceField, Topology
+
+# do normal topology preparation ...
+my_topology = Topology.from_pdb("my_system.pdb")
+
+# ... and then set box vectors before `Interchange` creation
+my_topology.box_vectors = Quantity([10, 10, 10], "nanometer")
+
+my_interchange = ForceField("openff-2.0.0.offxml").create_interchange(my_topology)
+```
+
+or the created `Interchange` object:
+
+```python
+# do normal `Interchange` preparation ...
+my_topology = Topology.from_pdb("my_system.pdb")
+my_interchange = ForceField("openff-2.0.0.offxml").create_interchange(my_topology)
+
+# ... and then set the box after creating an `Interchange` object:
+my_interchange.box = Quantity([10, 10, 10], "nanometer")
+```
+
+You may also wish to make the vdW cut-off distance longer. This is typically accessible at `my_interchange['vdW'].cutoff`.
+
 ## Quirks of charge assignment
 
 ### Charge assignment hierarchy

openff/interchange/_tests/test_issues.py

@@ -8,9 +8,10 @@
 from openff.utilities import get_data_file_path, has_executable, skip_if_missing
 
 from openff.interchange import Interchange
-from openff.interchange._tests import MoleculeWithConformer, shuffle_topology
+from openff.interchange._tests import MoleculeWithConformer, needs_gmx, shuffle_topology
 from openff.interchange.components._packmol import pack_box
 from openff.interchange.drivers import get_openmm_energies
+from openff.interchange.exceptions import NonperiodicNoCutoffNotSupportedError
 
 
 def test_issue_723():
@@ -167,3 +168,27 @@ def test_issue_1337(water):
     # just make sure this doesn't crash (original issue)
     # more extensive tests in openff/interchange/_tests/unit_tests/interop/openmm/test_constraints.py
     ff14sb_tip3p.create_interchange(water.to_topology())
+
+
+@needs_gmx
+def test_issue_1361_gromacs(caffeine, sage, tmp_path):
+    """Test that the 'how to opt in to pseudo-vacuum' message is communicated."""
+    interchange = sage.create_interchange(caffeine.to_topology())
+
+    with pytest.raises(
+        NonperiodicNoCutoffNotSupportedError,
+        match=r"GROMACS versions 2020 and newer do not support systems without periodicity",
+    ):
+        interchange.to_gromacs(prefix="foo")
+
+
+@pytest.mark.skipif(not has_executable("sander"), reason="sander not installed")
+def test_issue_1361_amber(caffeine, sage, tmp_path):
+    """Test that the 'how to opt in to pseudo-vacuum' message is communicated."""
+    interchange = sage.create_interchange(caffeine.to_topology())
+
+    with pytest.raises(
+        NonperiodicNoCutoffNotSupportedError,
+        match=r"vdW method no-cutoff not supported",
+    ):
+        interchange.to_amber(prefix="bar")

openff/interchange/components/mdconfig.py

@@ -11,6 +11,7 @@
 from openff.interchange._annotations import _DistanceQuantity
 from openff.interchange.constants import _PME
 from openff.interchange.exceptions import (
+    NonperiodicNoCutoffNotSupportedError,
     UnsupportedCutoffMethodError,
     UnsupportedExportError,
 )
@@ -458,7 +459,7 @@ def write_sander_input_file(
                 vdw_cutoff = round(self.vdw_cutoff.m_as("angstrom"), 4)
                 sander.write(f"cut={vdw_cutoff},\n")
             else:
-                raise UnsupportedExportError(
+                raise NonperiodicNoCutoffNotSupportedError(
                     f"vdW method {self.vdw_method} not supported",
                 )
 

openff/interchange/exceptions.py

@@ -104,6 +104,18 @@ class UnsupportedExportError(InterchangeException):
     """
 
 
+class NonperiodicNoCutoffNotSupportedError(UnsupportedExportError):
+    """
+    Exception for when an engine does not support "no-cutoff" non-bonded methods in non-periodic system.
+    """
+
+    def __init__(self, message):
+        super().__init__(
+            message
+            + "\nFor more see: https://docs.openforcefield.org/projects/interchange/en/stable/using/edges.html#no-cutoff-support",
+        )
+
+
 class UnsupportedCombinationError(InterchangeException):
     """General exception for something going wrong in Interchange object combination."""
 

openff/interchange/interop/gromacs/export/_export.py

@@ -5,7 +5,7 @@
 import numpy
 from openff.toolkit import Quantity
 
-from openff.interchange.exceptions import MissingPositionsError, UnsupportedExportError
+from openff.interchange.exceptions import MissingPositionsError, NonperiodicNoCutoffNotSupportedError
 from openff.interchange.interop.gromacs.models.models import (
     GROMACSSystem,
     GROMACSVirtualSite2,
@@ -487,7 +487,7 @@ def _write_gro(self, gro, decimal: int):
                     count += 1
 
         if self.system.box is None:
-            raise UnsupportedExportError(
+            raise NonperiodicNoCutoffNotSupportedError(
                 "GROMACS versions 2020 and newer do not support systems without periodicity/box vectors.",
             )
         else: