From 4037e9dbf001d1e548c68e2bcd5a7dadd436e871 Mon Sep 17 00:00:00 2001 From: "Matthew W. Thompson" Date: Mon, 7 Oct 2024 12:26:46 -0500 Subject: [PATCH] DOC: Document topology/positions quirk --- docs/using/edges.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/using/edges.md b/docs/using/edges.md index 06211d4a..33eeeb69 100644 --- a/docs/using/edges.md +++ b/docs/using/edges.md @@ -1,5 +1,16 @@ # Sharp edges +## Quirks of core OpenFF objects + +Future refactors may remove the side effects of these quirks, but currently there are some +surprising inconsistencies in some API points between different OpenFF tools. + +### Contents of `Interchange.topology` and `Interchange` may not always be in sync + +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. + ## Quirks of `from_openmm` ### Modified masses are ignored