Merge pull request #1078 from openforcefield/fix-1074

Export positions with virtual sites by default

docs/using/edges.md

@@ -9,7 +9,7 @@ surprising inconsistencies in some API points between different OpenFF tools.
 
 Currently, the `Interchange.topology` attribute is defined by the OpenFF Toolkit's `Topology` object, which is feature-rich in cheminformatics functionality but not designed for MM interoperability. Most importantly, that representation does not include virtual sites (because molecules do not have virtual sites/dummy atoms). As a result, functionality involving virtual sites must go through `Interchange` API points instead of `Interchange.topology`.
 
-For example, `Interchange.topology.get_positions()` will never include positions of virtual sites. To get the positions of a system with virtual sites included, use `Interchange.get_positions(include_virtual_sites=True)`. The default behavior of `Interchange.positions` is also to return positions without virtual sites.
+For example, `Interchange.topology.get_positions()` will never include positions of virtual sites. To get the positions of a system with virtual sites included, use `Interchange.get_positions()`. The default behavior of `Interchange.positions` is also to return positions without virtual sites, but this may change in the future.
 
 ## Quirks of `from_openmm`
 

openff/interchange/components/interchange.py

@@ -288,13 +288,13 @@ def minimize(
         else:
             raise NotImplementedError(f"Engine {engine} is not implemented.")
 
-    def get_positions(self, include_virtual_sites: bool = False) -> Quantity:
+    def get_positions(self, include_virtual_sites: bool = True) -> Quantity:
         """
         Get the positions associated with this Interchange.
 
         Parameters
         ----------
-        include_virtual_sites : bool, default=False
+        include_virtual_sites : bool, default=True
             Include virtual sites in the returned positions.
 
         Returns

openff/interchange/interop/common.py

@@ -14,9 +14,9 @@
 
 def _to_positions(
     interchange: "Interchange",
-    include_virtual_sites: bool = False,
+    include_virtual_sites: bool = True,
 ) -> Quantity:
-    """Generate an array of positions of all particles, optionally including virtual sites."""
+    """Generate an array of positions of all particles, optionally excluding virtual sites."""
     if interchange.positions is None:
         raise MissingPositionsError(
             f"Positions are required, found {interchange.positions=}.",

openff/interchange/interop/openmm/_positions.py

@@ -14,7 +14,7 @@
 
 def to_openmm_positions(
     interchange: "Interchange",
-    include_virtual_sites: bool = False,
+    include_virtual_sites: bool = True,
 ) -> "openmm.unit.Quantity":
-    """Generate an array of positions of all particles, optionally including virtual sites."""
+    """Generate an array of positions of all particles, optionally excluding virtual sites."""
     return _to_positions(interchange, include_virtual_sites).to_openmm()