openff.toolkit.topology.TopologyMolecule
- class openff.toolkit.topology.TopologyMolecule(reference_molecule, topology, local_topology_to_reference_index=None)[source]
TopologyMolecules are built to be an efficient way to store large numbers of copies of the same molecule for parameterization and system preparation.
Warning
This API is experimental and subject to change.
- __init__(reference_molecule, topology, local_topology_to_reference_index=None)[source]
Create a new TopologyMolecule.
- Parameters
- reference_moleculean openff.toolkit.topology.molecule.Molecule
The reference molecule, with details like formal charges, partial charges, bond orders, partial bond orders, and atomic symbols.
- topologyan openff.toolkit.topology.Topology
The topology that this TopologyMolecule belongs to
- local_topology_to_reference_indexdict, optional, default=None
Dictionary of {TopologyMolecule_atom_index : Molecule_atom_index} for the TopologyMolecule that will be built
Methods
__init__
(reference_molecule, topology[, ...])Create a new TopologyMolecule.
atom
(index)Get the TopologyAtom with a given topology atom index in this TopologyMolecule.
bond
(index)Get the TopologyBond with a given reference molecule index in this TopologyMolecule
from_dict
(d)Static constructor from dictionary representation.
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 ifn=4
was passed.particle
(index)Get the TopologyParticle with a given reference molecule index in this TopologyMolecule
to_dict
()Convert to dictionary representation.
virtual_site
(index)Get the TopologyVirtualSite with a given reference molecule index in this TopologyMolecule
Attributes
Iterate over improper torsions in the molecule, but only those with trivalent centers, reporting the central atom first in each improper.
Iterable of Tuple[TopologyAtom]: iterator over the angles in this TopologyMolecule.
Get the topology index of the first atom in this TopologyMolecule
Return an iterator of all the TopologyAtoms in this TopologyMolecule
Get the topology index of the first bond in this TopologyMolecule
Return an iterator of all the TopologyBonds in this TopologyMolecule
Iterable of Tuple[TopologyAtom]: iterator over the possible improper torsions in this TopologyMolecule.
int: number of angles in this TopologyMolecule.
The number of atoms in this topology.
Get the number of bonds in this TopologyMolecule
int: number of possible improper torsions in this TopologyMolecule.
Get the number of particles in this TopologyMolecule
int: number of proper torsions in this TopologyMolecule.
Get the number of virtual sites in this TopologyMolecule
Return an iterator of all the TopologyParticles in this TopologyMolecules
Iterable of Tuple[TopologyAtom]: iterator over the proper torsions in this TopologyMolecule.
Get the reference molecule for this TopologyMolecule
Note that it's possible that a trivalent center will not have an improper assigned.
Get the topology that this TopologyMolecule belongs to
Get the topology index of the first virtual particle in this TopologyMolecule
Get the topology index of the first virtual site in this TopologyMolecule
Return an iterator of all the TopologyVirtualSites in this TopologyMolecules
- property topology
Get the topology that this TopologyMolecule belongs to
- Returns
- an openff.toolkit.topology.Topology
- property reference_molecule
Get the reference molecule for this TopologyMolecule
- Returns
- an openff.toolkit.topology.molecule.Molecule
- atom(index)[source]
Get the TopologyAtom with a given topology atom index in this TopologyMolecule.
- Parameters
- indexint
Index of the TopologyAtom within this TopologyMolecule to retrieve
- Returns
- an openff.toolkit.topology.TopologyAtom
- property atoms
Return an iterator of all the TopologyAtoms in this TopologyMolecule
- Returns
- an iterator of openff.toolkit.topology.TopologyAtoms
- property atom_start_topology_index
Get the topology index of the first atom in this TopologyMolecule
- property virtual_particle_start_topology_index
Get the topology index of the first virtual particle in this TopologyMolecule
- bond(index)[source]
Get the TopologyBond with a given reference molecule index in this TopologyMolecule
- Parameters
- indexint
Index of the TopologyBond within this TopologyMolecule to retrieve
- Returns
- an openff.toolkit.topology.TopologyBond
- property bonds
Return an iterator of all the TopologyBonds in this TopologyMolecule
- Returns
- an iterator of openff.toolkit.topology.TopologyBonds
- property bond_start_topology_index
Get the topology index of the first bond in this TopologyMolecule
- particle(index)[source]
Get the TopologyParticle with a given reference molecule index in this TopologyMolecule
- Parameters
- indexint
Index of the TopologyParticle within this TopologyMolecule to retrieve
- Returns
- an openff.toolkit.topology.TopologyParticle
- property particles
Return an iterator of all the TopologyParticles in this TopologyMolecules
- Returns
- an iterator of openff.toolkit.topology.TopologyParticle
- property n_particles
Get the number of particles in this TopologyMolecule
- Returns
- intThe number of particles
- virtual_site(index)[source]
Get the TopologyVirtualSite with a given reference molecule index in this TopologyMolecule
- Parameters
- indexint
Index of the TopologyVirtualSite within this TopologyMolecule to retrieve
- Returns
- an openff.toolkit.topology.TopologyVirtualSite
- property virtual_sites
Return an iterator of all the TopologyVirtualSites in this TopologyMolecules
- Returns
- an iterator of openff.toolkit.topology.TopologyVirtualSite
- property propers
Iterable of Tuple[TopologyAtom]: iterator over the proper torsions in this TopologyMolecule.
- property impropers
Iterable of Tuple[TopologyAtom]: iterator over the possible improper torsions in this TopologyMolecule.
- property smirnoff_impropers
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
- 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.
- property amber_impropers
Iterate over improper torsions in the molecule, but only those with trivalent centers, reporting the central atom first 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 AMBER parameterization, one of these six orderings will be used for the actual assignment of the improper term and measurement of the angle. This method does not encode the logic to determine which of the six orderings AMBER would use.
- 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 first in each tuple.
- nth_degree_neighbors(n_degrees: int)[source]
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
- neighbors: iterator of tuple of TopologyAtom
Tuples (len 2) of atom that are separated by
n
bonds.
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.
- property virtual_site_start_topology_index
Get the topology index of the first virtual site in this TopologyMolecule
- to_dict()[source]
Convert to dictionary representation.
- classmethod from_dict(d)[source]
Static constructor from dictionary representation.