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.

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 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: other (optional, 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)
`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.
`atom_index`(atom)	Returns the index of a given atom in this topology
`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.
`copy_initializer`(other)
`from_bson`(serialized)	Instantiate an object from a BSON serialized representation.
`from_dict`(topology_dict)	Create a new Topology from a 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
`hierarchy_iterator`(iter_name)	Get a HierarchyElement iterator from all of the molecules in this topology that provide the appropriately named iterator.
`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.
`molecule`(index)	Returns the molecule with a given index in this Topology.
`molecule_atom_start_index`(molecule)	Returns the index of a molecule's first atom in this topology
`molecule_index`(molecule)	Returns the index of a given molecule in this topology
`nth_degree_neighbors`(n_degrees)	Return canonicalized pairs of atoms whose shortest separation is exactly n bonds.
`particle_index`(particle)	DEPRECATED: Use Topology.atom_index instead.
`to_bson`()	Return a BSON serialized representation.
`to_dict`()
`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.

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`	iterator over the angles in this Topology.
`aromaticity_model`	Get the aromaticity model applied to all molecules in the topology.
`atoms`	Returns an iterator over the atoms in this Topology.
`bonds`	Returns an iterator over the bonds in this Topology
`box_vectors`	Return the box vectors of the topology, if specified
`constrained_atom_pairs`	Returns the constrained atom pairs of the Topology
`identical_molecule_groups`	Returns groups of chemically identical molecules, identified by index and atom map.
`impropers`	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.
`molecules`	Returns an iterator over all the Molecules in this Topology
`n_angles`	number of angles in this Topology.
`n_atoms`	Returns the number of atoms in in this Topology.
`n_bonds`	Returns the number of Bonds in in this Topology.
`n_impropers`	number of possible improper torsions in this Topology.
`n_molecules`	Returns the number of molecules in this Topology
`n_particles`	Use Topology.n_atoms instead.
`n_propers`	number of proper torsions in this Topology.
`n_reference_molecules`	Use Topology.n_molecules instead.
`n_topology_atoms`	Use Topology.n_atoms instead.
`n_topology_bonds`	Use Topology.n_bonds instead.
`n_topology_molecules`	Use Topology.n_molecules instead.
`n_topology_particles`	Use Topology.n_particles instead.
`particles`	Use Topology.molecules instead.
`propers`	iterator over the proper torsions in this Topology.
`reference_molecules`	Get a list 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`	Use Topology.atoms instead.
`topology_bonds`	Use Topology.bonds instead.
`topology_molecules`	Use Topology.molecules instead.
`topology_particles`	Use Topology.particles instead.

property reference_molecules: List[Molecule]

Get a list of reference molecules in this Topology.

Returns: iterable of openff.toolkit.topology.Molecule

classmethod from_molecules(molecules: Union[Molecule, List[Molecule]])[source]

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

Parameters: molecules (Molecule or iterable of Molecules) – One or more molecules to be added to the Topology
Returns: topology (Topology) – 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 (Atom or int) – The atoms or atom topology indices to check to ensure they are bonded
atom2 (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_model (str) – Aromaticity model in use.

property box_vectors

Return the box vectors of the topology, if specified

Returns: box_vectors (unit-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 constrained_atom_pairs: Dict[Tuple[int], Union[openff.units.units.Quantity, bool]]

Returns the constrained atom pairs of the Topology

Returns: constrained_atom_pairs (dict of Tuple[int]: Union[unit.Quantity, bool]) – dictionary of the form {(atom1_topology_index, atom2_topology_index): distance}

property n_molecules

Returns the number of molecules in this Topology

Returns: n_molecules (Iterable of Molecule)

property molecules: Generator[Union[Molecule, openff.toolkit.topology._mm_molecule._SimpleMolecule], None, None]

Returns an iterator over all the Molecules in this Topology

Returns: molecules (Iterable of Molecule)

molecule(index)[source]

Returns the molecule with a given index in this Topology.

Returns: molecule (openff.toolkit.topology.Molecule)

property n_atoms: int

Returns the number of atoms in in this Topology.

Returns: n_atoms (int)

property atoms: Generator[Atom, None, None]

Returns an iterator over the atoms in this Topology. These will be in ascending order of topology index.

Returns: atoms (Generator of TopologyAtom)

atom_index(atom)[source]

Returns the index of a given atom in this topology

Parameters: atom (Atom) –
Returns: index (int) – The index of the given atom in this topology

:raises AtomNotInTopologyError : If the given atom is not in this topology:

molecule_index(molecule)[source]

Returns the index of a given molecule in this topology

Parameters: molecule (FrozenMolecule) –
Returns: index (int) – The index of the given molecule in this topology

:raises MoleculeNotInTopologyError : If the given atom is not in this topology:

molecule_atom_start_index(molecule)[source]

Returns the index of a molecule’s first atom in this topology

Parameters: molecule (FrozenMolecule) –
Returns: index (int)

property n_bonds

Returns the number of Bonds in in this Topology.

Returns: n_bonds (int)

property bonds

Returns an iterator over the bonds in this Topology

Returns: bonds (Iterable of Bond)

property n_angles

number of angles in this Topology.

Type: int

property angles

iterator over the angles in this Topology.

Type: Iterable of Tuple[Atom]

property n_propers

number of proper torsions in this Topology.

Type: int

property propers

iterator over the proper torsions in this Topology.

Type: Iterable of Tuple[TopologyAtom]

property n_impropers

number of possible improper torsions in this Topology.

Type: int

property impropers

iterator over the possible improper torsions in this Topology.

Type: Iterable of Tuple[TopologyAtom]

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://openforcefield.github.io/standards/standards/smirnoff/#impropertorsions

Returns: impropers (set 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.