OpenFF Toolkit 0.10.6+0.g37d6806b.dirty documentation

openff.toolkit.topology.TopologyMolecule

class openff.toolkit.topology.TopologyMolecule(reference_molecule, topology, local_topology_to_reference_index=None)

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)

Create a new TopologyMolecule.

Parameters

• reference_molecule (an openff.toolkit.topology.molecule.Molecule) – The reference molecule, with details like formal charges, partial charges, bond orders, partial bond orders, and atomic symbols.

• topology (an openff.toolkit.topology.Topology) – The topology that this TopologyMolecule belongs to

• local_topology_to_reference_index (dict, 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.
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

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 TopologyMolecule.
atom_start_topology_index	Get the topology index of the first atom in this TopologyMolecule
atoms	Return an iterator of all the TopologyAtoms in this TopologyMolecule
bond_start_topology_index	Get the topology index of the first bond in this TopologyMolecule
bonds	Return an iterator of all the TopologyBonds in this TopologyMolecule
impropers	iterator over the possible improper torsions in this TopologyMolecule.
n_angles	number of angles in this TopologyMolecule.
n_atoms	The number of atoms in this topology.
n_bonds	Get the number of bonds in this TopologyMolecule
n_impropers	number of possible improper torsions in this TopologyMolecule.
n_particles	Get the number of particles in this TopologyMolecule
n_propers	number of proper torsions in this TopologyMolecule.
n_virtual_sites	Get the number of virtual sites in this TopologyMolecule
particles	Return an iterator of all the TopologyParticles in this TopologyMolecules
propers	iterator over the proper torsions in this TopologyMolecule.
reference_molecule	Get the reference molecule for this TopologyMolecule
smirnoff_impropers	Note that it's possible that a trivalent center will not have an improper assigned.
topology	Get the topology that this TopologyMolecule belongs to
virtual_particle_start_topology_index	Get the topology index of the first virtual particle in this TopologyMolecule
virtual_site_start_topology_index	Get the topology index of the first virtual site in this TopologyMolecule
virtual_sites	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

property n_atoms

The number of atoms in this topology.

Returns

int

atom(index)

Get the TopologyAtom with a given topology atom index in this TopologyMolecule.

Parameters

index (int) – 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)

Get the TopologyBond with a given reference molecule index in this TopologyMolecule

Parameters

index (int) – 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 n_bonds

Get the number of bonds in this TopologyMolecule

Returns

int (number of bonds)

property bond_start_topology_index

Get the topology index of the first bond in this TopologyMolecule

particle(index)

Get the TopologyParticle with a given reference molecule index in this TopologyMolecule

Parameters

index (int) – 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

int (The number of particles)

virtual_site(index)

Get the TopologyVirtualSite with a given reference molecule index in this TopologyMolecule

Parameters

index (int) – 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 n_virtual_sites

Get the number of virtual sites in this TopologyMolecule

Returns

int

property angles

iterator over the angles in this TopologyMolecule.

Type

Iterable of Tuple[TopologyAtom]

property n_angles

number of angles in this TopologyMolecule.

Type

int

property propers

iterator over the proper torsions in this TopologyMolecule.

Type

Iterable of Tuple[TopologyAtom]

property n_propers

number of proper torsions in this TopologyMolecule.

Type

int

property impropers

iterator over the possible improper torsions in this TopologyMolecule.

Type

Iterable of Tuple[TopologyAtom]

property n_impropers

number of possible improper torsions in this TopologyMolecule.

Type

int

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

• 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.

• .. todo:: –

  • Offer a way to do the keytransform and get the final 3 orderings in this method? How can we keep this logic synced up with the parameterization machinery?

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

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 first in each tuple.

nth_degree_neighbors(n_degrees: int)

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.

property virtual_site_start_topology_index

Get the topology index of the first virtual site in this TopologyMolecule

to_dict()

Convert to dictionary representation.

classmethod from_dict(d)

Static constructor from dictionary representation.