openff.toolkit.topology.Topology

class openff.toolkit.topology.Topology(other=None)[source]

A Topology is a chemical representation of a system containing one or more molecules appearing in a specified order.

As of the 0.7.0 release, the Topology particle indexing system puts all atoms before all virtualsites. This ensures that atoms keep the same Topology particle index value, even if the Topology is modified during system creation by the addition of virtual sites.

Warning

This API is experimental and subject to change.

Examples

Import some utilities

>>> from openmm import app
>>> from openff.toolkit.tests.utils import get_data_file_path, get_packmol_pdb_file_path
>>> pdb_filepath = get_packmol_pdb_file_path('cyclohexane_ethanol_0.4_0.6')
>>> monomer_names = ('cyclohexane', 'ethanol')

Create a Topology object from a PDB file and sdf files defining the molecular contents

>>> from openff.toolkit.topology import Molecule, Topology
>>> pdbfile = app.PDBFile(pdb_filepath)
>>> sdf_filepaths = [get_data_file_path(f'systems/monomers/{name}.sdf') for name in monomer_names]
>>> unique_molecules = [Molecule.from_file(sdf_filepath) for sdf_filepath in sdf_filepaths]
>>> topology = Topology.from_openmm(pdbfile.topology, unique_molecules=unique_molecules)

Create a Topology object from a PDB file and IUPAC names of the molecular contents

>>> pdbfile = app.PDBFile(pdb_filepath)
>>> unique_molecules = [Molecule.from_iupac(name) for name in monomer_names]
>>> topology = Topology.from_openmm(pdbfile.topology, unique_molecules=unique_molecules)

Create an empty Topology object and add a few copies of a single benzene molecule

>>> topology = Topology()
>>> molecule = Molecule.from_iupac('benzene')
>>> molecule_topology_indices = [topology.add_molecule(molecule) for index in range(10)]

__init__(other=None)[source]

Create a new Topology.

Parameters

otheroptional, default=None: If specified, attempt to construct a copy of the Topology from the specified object. This might be a Topology object, or a file that can be used to construct a Topology object or serialized Topology object.

Methods

`__init__`([other])	Create a new Topology.
`add_constraint`(iatom, jatom[, distance])	Mark a pair of atoms as constrained.
`add_molecule`(molecule[, ...])	Add a Molecule to the Topology.
`add_particle`(particle)	Add a Particle to the Topology.
`assert_bonded`(atom1, atom2)	Raise an exception if the specified atoms are not bonded in the topology.
`atom`(atom_topology_index)	Get the TopologyAtom at a given Topology atom index.
`bond`(bond_topology_index)	Get the TopologyBond at a given Topology bond index.
`chemical_environment_matches`(query[, ...])	Retrieve all matches for a given chemical environment query.
`from_bson`(serialized)	Instantiate an object from a BSON serialized representation.
`from_dict`(d)	Static constructor from dictionary representation.
`from_json`(serialized)	Instantiate an object from a JSON serialized representation.
`from_mdtraj`(mdtraj_topology[, unique_molecules])	Construct an OpenFF Topology object from an MDTraj Topology object.
`from_messagepack`(serialized)	Instantiate an object from a MessagePack serialized representation.
`from_molecules`(molecules)	Create a new Topology object containing one copy of each of the specified molecule(s).
`from_openmm`(openmm_topology[, unique_molecules])	Construct an OpenFF Topology object from an OpenMM Topology object.
`from_pickle`(serialized)	Instantiate an object from a pickle serialized representation.
`from_toml`(serialized)	Instantiate an object from a TOML serialized representation.
`from_xml`(serialized)	Instantiate an object from an XML serialized representation.
`from_yaml`(serialized)	Instantiate from a YAML serialized representation.
`get_bond_between`(i, j)	Returns the bond between two atoms
`is_bonded`(i, j)	Returns True if the two atoms are bonded
`is_constrained`(iatom, jatom)	Check if a pair of atoms are marked as constrained.
`nth_degree_neighbors`(n_degrees)	Return canonicalized pairs of atoms whose shortest separation is exactly n bonds. Only pairs with increasing atom indices are returned. Parameters ---------- n: int The number of bonds separating atoms in each pair Returns ------- neighbors: iterator of tuple of TopologyAtom Tuples (len 2) of atom that are separated by `n` bonds. Notes ----- The criteria used here relies on minimum distances; when there are multiple valid paths between atoms, such as atoms in rings, the shortest path is considered. For example, two atoms in "meta" positions with respect to each other in a benzene are separated by two paths, one length 2 bonds and the other length 4 bonds. This function would consider them to be 2 apart and would not include them if `n=4` was passed.
`to_bson`()	Return a BSON serialized representation.
`to_dict`()	Convert to dictionary representation.
`to_file`(filename, positions[, file_format, ...])	Save coordinates and topology to a PDB file.
`to_json`([indent])	Return a JSON serialized representation.
`to_messagepack`()	Return a MessagePack representation.
`to_openmm`([ensure_unique_atom_names])	Create an OpenMM Topology object.
`to_pickle`()	Return a pickle serialized representation.
`to_toml`()	Return a TOML serialized representation.
`to_xml`([indent])	Return an XML representation.
`to_yaml`()	Return a YAML serialized representation.
`virtual_site`(vsite_topology_index)	Get the TopologyAtom at a given Topology atom index.

Attributes

`amber_impropers`	Iterate over improper torsions in the molecule, but only those with trivalent centers, reporting the central atom first in each improper.
`angles`	Iterable of Tuple[TopologyAtom]: iterator over the angles in this Topology.
`aromaticity_model`	Get the aromaticity model applied to all molecules in the topology.
`box_vectors`	Return the box vectors of the topology, if specified
`charge_model`	Get the partial charge model applied to all molecules in the topology.
`constrained_atom_pairs`	Returns the constrained atom pairs of the Topology
`fractional_bond_order_model`	Get the fractional bond order model for the Topology.
`impropers`	Iterable of Tuple[TopologyAtom]: iterator over the possible improper torsions in this Topology.
`is_periodic`	Return whether or not this Topology is intended to be described with periodic boundary conditions.
`n_angles`	int: number of angles in this Topology.
`n_impropers`	int: number of possible improper torsions in this Topology.
`n_propers`	int: number of proper torsions in this Topology.
`n_reference_molecules`	Returns the number of reference (unique) molecules in in this Topology.
`n_topology_atoms`	Returns the number of topology atoms in in this Topology.
`n_topology_bonds`	Returns the number of TopologyBonds in in this Topology.
`n_topology_molecules`	Returns the number of topology molecules in in this Topology.
`n_topology_particles`	Returns the number of topology particles (TopologyAtoms and TopologyVirtualSites) in in this Topology.
`n_topology_virtual_sites`	Returns the number of TopologyVirtualSites in in this Topology.
`propers`	Iterable of Tuple[TopologyAtom]: iterator over the proper torsions in this Topology.
`reference_molecules`	Get an iterator of reference molecules in this Topology.
`smirnoff_impropers`	Iterate over improper torsions in the molecule, but only those with trivalent centers, reporting the central atom second in each improper.
`topology_atoms`	Returns an iterator over the atoms in this Topology.
`topology_bonds`	Returns an iterator over the bonds in this Topology
`topology_molecules`	Returns an iterator over all the TopologyMolecules in this Topology
`topology_particles`	Returns an iterator over the particles (TopologyAtoms and TopologyVirtualSites) in this Topology.
`topology_virtual_sites`	Get an iterator over the virtual sites in this Topology

property reference_molecules

Get an iterator of reference molecules in this Topology.

Returns

iterable of openff.toolkit.topology.Molecule

classmethod from_molecules(molecules)[source]

Create a new Topology object containing one copy of each of the specified molecule(s).

Parameters

moleculesMolecule or iterable of Molecules: One or more molecules to be added to the Topology

Returns

topologyTopology: The Topology created from the specified molecule(s)

assert_bonded(atom1, atom2)[source]

Raise an exception if the specified atoms are not bonded in the topology.

Parameters

atom1, atom2openff.toolkit.topology.Atom or int: The atoms or atom topology indices to check to ensure they are bonded

property aromaticity_model

Get the aromaticity model applied to all molecules in the topology.

Returns

aromaticity_modelstr: Aromaticity model in use.

property box_vectors

Return the box vectors of the topology, if specified

Returns

box_vectorsopenmm.unit.Quantity wrapped numpy array of shape (3, 3): The unit-wrapped box vectors of this topology

property is_periodic: Return whether or not this Topology is intended to be described with periodic boundary conditions.

property charge_model

Get the partial charge model applied to all molecules in the topology.

Returns

charge_modelstr: Charge model used for all molecules in the Topology.

property constrained_atom_pairs

Returns the constrained atom pairs of the Topology

Returns

constrained_atom_pairsdict: dictionary of the form d[(atom1_topology_index, atom2_topology_index)] = distance (float)

property fractional_bond_order_model

Get the fractional bond order model for the Topology.

Returns

fractional_bond_order_modelstr: Fractional bond order model in use.

property n_reference_molecules

Returns the number of reference (unique) molecules in in this Topology.

Returns

n_reference_moleculesint

property n_topology_molecules

Returns the number of topology molecules in in this Topology.

Returns

n_topology_moleculesint

property topology_molecules

Returns an iterator over all the TopologyMolecules in this Topology

Returns

topology_moleculesIterable of TopologyMolecule

property n_topology_atoms

Returns the number of topology atoms in in this Topology.

Returns

n_topology_atomsint

property topology_atoms

Returns an iterator over the atoms in this Topology. These will be in ascending order of topology index (Note that this is not necessarily the same as the reference molecule index)

Returns

topology_atomsIterable of TopologyAtom

property n_topology_bonds

Returns the number of TopologyBonds in in this Topology.

Returns

n_bondsint

property topology_bonds

Returns an iterator over the bonds in this Topology

Returns

topology_bondsIterable of TopologyBond

property n_topology_particles

Returns the number of topology particles (TopologyAtoms and TopologyVirtualSites) in in this Topology.

Returns

n_topology_particlesint

property topology_particles

Returns an iterator over the particles (TopologyAtoms and TopologyVirtualSites) in this Topology. The TopologyAtoms will be in order of ascending Topology index (Note that this may differ from the order of atoms in the reference molecule index).

Returns

topology_particlesIterable of TopologyAtom and TopologyVirtualSite

property n_topology_virtual_sites

Returns the number of TopologyVirtualSites in in this Topology.

Returns

n_virtual_sitesiterable of TopologyVirtualSites

property topology_virtual_sites

Get an iterator over the virtual sites in this Topology

Returns

topology_virtual_sitesIterable of TopologyVirtualSite

property n_angles: int: number of angles in this Topology.

property angles: Iterable of Tuple[TopologyAtom]: iterator over the angles in this Topology.

property n_propers: int: number of proper torsions in this Topology.

property propers: Iterable of Tuple[TopologyAtom]: iterator over the proper torsions in this Topology.

property n_impropers: int: number of possible improper torsions in this Topology.

property impropers: Iterable of Tuple[TopologyAtom]: iterator over the possible improper torsions in this Topology.

property smirnoff_impropers

Iterate over improper torsions in the molecule, but only those with trivalent centers, reporting the central atom second in each improper.

Note that it’s possible that a trivalent center will not have an improper assigned. This will depend on the force field that is used.

Also note that this will return 6 possible atom orderings around each improper center. In current SMIRNOFF parameterization, three of these six orderings will be used for the actual assignment of the improper term and measurement of the angles. These three orderings capture the three unique angles that could be calculated around the improper center, therefore the sum of these three terms will always return a consistent energy.

For more details on the use of three-fold (‘trefoil’) impropers, see https://open-forcefield-toolkit.readthedocs.io/en/latest/smirnoff.html#impropertorsions

Returns

impropersset of tuple: An iterator of tuples, each containing the indices of atoms making up a possible improper torsion. The central atom is listed second in each tuple.