diff --git a/docs/using/collections.md b/docs/using/collections.md index 8bc142329..229e6752b 100644 --- a/docs/using/collections.md +++ b/docs/using/collections.md @@ -91,13 +91,23 @@ SMIRNOFFImproperTorsionCollection(type='ImproperTorsions', ``` +We can also access a collection by indexing directly into the Interchange itself: + +```pycon +>>> interchange['ImproperTorsions'] # doctest: +NORMALIZE_WHITESPACE,+ELLIPSIS +SMIRNOFFImproperTorsionCollection(type='ImproperTorsions', + expression='k*(1+cos(periodicity*theta-phase))', + key_map={}, + potentials={}) +``` + In the bond collection for example, each pair of bonded atoms maps to one of two potential keys, one for the carbon-carbon bond, and the other for the carbon-hydrogen bonds. It's clear from the SMIRKS codes that atoms 0 and 1 are the carbon atoms, and atoms 2 through 7 are the hydrogens: ```pycon ->>> interchange.collections['Bonds'].key_map # doctest: +NORMALIZE_WHITESPACE,+ELLIPSIS +>>> interchange['Bonds'].key_map # doctest: +NORMALIZE_WHITESPACE,+ELLIPSIS {TopologyKey(atom_indices=(0, 1), ...): PotentialKey(id='[#6X4:1]-[#6X4:2]', ...), TopologyKey(atom_indices=(0, 2), ...): PotentialKey(id='[#6X4:1]-[#1:2]', ...), TopologyKey(atom_indices=(0, 3), ...): PotentialKey(id='[#6X4:1]-[#1:2]', ...), @@ -117,7 +127,7 @@ The bond collection also maps the two potential keys to the appropriate `Potenti Here we can read off the force constant and length: ```pycon ->>> interchange.collections['Bonds'].potentials # doctest: +NORMALIZE_WHITESPACE,+ELLIPSIS +>>> interchange['Bonds'].potentials # doctest: +NORMALIZE_WHITESPACE,+ELLIPSIS {PotentialKey(id='[#6X4:1]-[#6X4:2]', ...): Potential(parameters={'k': , 'length': }, ...), @@ -127,16 +137,21 @@ Here we can read off the force constant and length: ``` -We can even modify a value here, export the new interchange, and see that all of -the bonds have been updated: +Any `TopologyKey` that only specifies atom indices can be accessed by indexing directly into the `Collection` with those atom indices: + +```pycon +>>> interchange['Bonds'][0,1] # doctest: +NORMALIZE_WHITESPACE,+ELLIPSIS +Potential(parameters={'k': , 'length': }, map_key=None) + +``` + +We can even modify a value here, export the new interchange, and see that all of the bonds have been updated: ```pycon >>> from openff.interchange.models import TopologyKey >>> from openff.units import unit >>> # Get the potential from the first C-H bond ->>> top_key = TopologyKey(atom_indices=(0, 2)) ->>> pot_key = interchange.collections['Bonds'].key_map[top_key] ->>> potential = interchange.collections['Bonds'].potentials[pot_key] +>>> potential = interchange['Bonds'][0, 2] >>> # Modify the potential >>> potential.parameters['length'] = 3.1415926 * unit.nanometer >>> # Write out the modified interchange to a GROMACS .top file diff --git a/openff/interchange/components/interchange.py b/openff/interchange/components/interchange.py index 75d070f78..ef13bd5cc 100644 --- a/openff/interchange/components/interchange.py +++ b/openff/interchange/components/interchange.py @@ -56,6 +56,21 @@ class Interchange(_BaseModel): .. warning :: This object is in an early and experimental state and unsuitable for production. .. warning :: This API is experimental and subject to change. + + Examples + -------- + Create an ``Interchange`` from an OpenFF ``ForceField`` and ``Molecule`` + + >>> from openff.toolkit import ForceField, Molecule + >>> sage = ForceField("openff-2.2.0.offxml") + >>> top = Molecule.from_smiles("CCC").to_topology() + >>> interchange = sage.create_interchange(top) + + Get the parameters for the bond between atoms 0 and 1 + + >>> interchange["Bonds"][0, 1] + Potential(...) + """ collections: _AnnotatedCollections = Field(dict())