openff.toolkit.topology.BondChargeVirtualSite

class openff.toolkit.topology.BondChargeVirtualSite(distance: Quantity, name: str, orientations: List[Tuple[int, ...]])[source]

A particle representing a “Bond Charge”-type virtual site, in which the location of the charge is specified by the positions of two atoms. This supports placement of a virtual site S along a vector between two specified atoms, e.g. to allow for a sigma hole for halogens or similar contexts. With positive values of the distance, the virtual site lies outside the first indexed atom.

Warning

This API is experimental and subject to change.

TODO: One of the examples in the SMIRNOFF spec has a BondCharge defined with

three atoms – How does that work?

__init__(distance: Quantity, name: str, orientations: List[Tuple[int, ...]])[source]
Parameters
  • distance – A quantity with dimension [Length] wrapping a scalar

  • name – The name of this virtual site.

  • orientations – The indices of the atoms used to define the frame of the virtual site.

Methods

__init__(distance, name, orientations)

param distance

A quantity with dimension [Length] wrapping a scalar

compute_positions_from_atom_positions(...)

Compute the positions of the virtual site particles given a set of coordinates.

compute_positions_from_conformer(conformer_idx)

Compute the position of the virtual site particles given an existing conformer owned by the parent molecule.

from_bson(serialized)

Instantiate an object from a BSON serialized representation.

from_dict(vsite_dict)

Create a virtual site from a dict representation.

from_json(serialized)

Instantiate an object from a JSON serialized representation.

from_messagepack(serialized)

Instantiate an object from a MessagePack serialized representation.

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_openmm_virtual_site(atoms)

Returns the OpenMM virtual site corresponding to this BondChargeVirtualSite.

index_of_orientation(virtual_particle)

Return the orientation used by the given virtual particle.

to_bson()

Return a BSON serialized representation.

to_dict()

Return a dict representation of the virtual site.

to_json([indent])

Return a JSON serialized representation.

to_messagepack()

Return a MessagePack representation.

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

atoms

Atoms on whose position this VirtualSite depends.

distance

The distance parameter of the virtual site

local_frame_position

The displacements of the virtual site relative to the local frame.

local_frame_weights

Returns the local frame weights used to calculate the particle positions.

molecule

The Molecule this particle is part of.

molecule_particle_index

Returns the index of this particle in its molecule

molecule_virtual_site_index

The index of this VirtualSite within the list of virtual sites within Molecule Note that this can be different from particle_index.

n_particles

The number of particles that the virtual site represents

name

The name of this VirtualSite

orientations

The orientations used by the virtual site particles.

particles

Particles owned by this VirtualSite

type

The type of this VirtualSite (returns the class name as string)

to_dict()[source]

Return a dict representation of the virtual site.

classmethod from_dict(vsite_dict)[source]

Create a virtual site from a dict representation.

property distance: openmm.unit.quantity.Quantity

The distance parameter of the virtual site

property local_frame_weights

Returns the local frame weights used to calculate the particle positions. See VirtualSite.local_frame_weights for a general description.

Bond charge virtual sites are defined by the axis defined by the two atoms that define the bond. Since the virtual site position is defined solely by this axis, the other y-axis is defined but not used.

Returns

Tuple of list of weights used to define the origin, x-axis, and y-axis.

property local_frame_position

The displacements of the virtual site relative to the local frame. See VirtualSite.local_frame_position for a general description.

Returns

  • openmm.unit.Quantity of dimension [Length] wrapping a list of

  • displacements in the local frame for the x, y, and z directions.

get_openmm_virtual_site(atoms)[source]

Returns the OpenMM virtual site corresponding to this BondChargeVirtualSite.

Parameters

atoms (iterable of int) – The indices of the atoms involved in this virtual site.

Returns

openmm.LocalCoordinatesSite

property atoms

Atoms on whose position this VirtualSite depends.

compute_positions_from_atom_positions(atom_positions)

Compute the positions of the virtual site particles given a set of coordinates.

Parameters
  • atom_positions (openmm.unit.Quantity of dimension [Length] wrapping a) –

  • numpy.ndarray – The positions of all atoms in the molecule. The array is the size (N, 3) where N is the number of atoms in the molecule.

Returns

  • openmm.unit.Quantity of dimension [Length] in unit Angstroms wrapping a

  • numpy.ndarray – The positions of the virtual particles belonging to this virtual site. The array is the size (M, 3) where M is the number of virtual particles belonging to this virtual site.

compute_positions_from_conformer(conformer_idx)

Compute the position of the virtual site particles given an existing conformer owned by the parent molecule.

Parameters

conformer_idx (int) – The index of the conformer in the owning molecule.

Returns

  • openmm.unit.Quantity of dimension [Length] in unit Angstroms wrapping a

  • numpy.ndarray – The positions of the virtual particles belonging to this virtual site. The array is the size (M, 3) where M is the number of virtual particles belonging to this virtual site.

classmethod from_bson(serialized)

Instantiate an object from a BSON serialized representation.

Specification: http://bsonspec.org/

Parameters

serialized (bytes) – A BSON serialized representation of the object

Returns

instance (cls) – An instantiated object

classmethod from_json(serialized)

Instantiate an object from a JSON serialized representation.

Specification: https://www.json.org/

Parameters

serialized (str) – A JSON serialized representation of the object

Returns

instance (cls) – An instantiated object

classmethod from_messagepack(serialized)

Instantiate an object from a MessagePack serialized representation.

Specification: https://msgpack.org/index.html

Parameters

serialized (bytes) – A MessagePack-encoded bytes serialized representation

Returns

instance (cls) – Instantiated object.

classmethod from_pickle(serialized)

Instantiate an object from a pickle serialized representation.

Warning

This is not recommended for safe, stable storage since the pickle specification may change between Python versions.

Parameters

serialized (str) – A pickled representation of the object

Returns

instance (cls) – An instantiated object

classmethod from_toml(serialized)

Instantiate an object from a TOML serialized representation.

Specification: https://github.com/toml-lang/toml

Parameters

serlialized (str) – A TOML serialized representation of the object

Returns

instance (cls) – An instantiated object

classmethod from_xml(serialized)

Instantiate an object from an XML serialized representation.

Specification: https://www.w3.org/XML/

Parameters

serialized (bytes) – An XML serialized representation

Returns

instance (cls) – Instantiated object.

classmethod from_yaml(serialized)

Instantiate from a YAML serialized representation.

Specification: http://yaml.org/

Parameters

serialized (str) – A YAML serialized representation of the object

Returns

instance (cls) – Instantiated object

index_of_orientation(virtual_particle)

Return the orientation used by the given virtual particle.

Parameters

virtual_particle (VirtualParticle) – The virtual particle contained in this virual site

Returns

A tuple of atom indices

property molecule: Optional[openff.toolkit.topology.molecule.Molecule]

The Molecule this particle is part of.

property molecule_particle_index

Returns the index of this particle in its molecule

property molecule_virtual_site_index: int

The index of this VirtualSite within the list of virtual sites within Molecule Note that this can be different from particle_index.

property n_particles: int

The number of particles that the virtual site represents

property name: str

The name of this VirtualSite

property orientations: List[Tuple[int, ...]]

The orientations used by the virtual site particles.

Orientations are an implementation to allow generation and coupling of multiple particles using the same physical definition. We can do this by allowing each particle to use a specific ordering of bases when calculating the positions. This is similar to improper torsion angles: the angle you find depends on the atom ordering used in the calculation.

Before the positions are constructed, the parent atoms are reordered according to the particle’s orientation. Each virtual particle has exactly one orientation. Since the frame of the virtual site is defined by a static list of weights and masks, we are able to influence how the local frame is constructed by crafting specific ordering the parent atoms.

As a concrete example, we could define a TIP5 water by using one virtual site, and the particles have orientations (0, 1, 2) and (2, 1, 0). This means that, given that we are using a right-handed coordinate system, the z-axis will point in opposite directions for each particle. Using the same out_of_plane_angle and distance will therefore result in two unique particle positions.

Using the toolkit API allows arbitrary selection of orientations. The SMIRNOFF specification, via the offxml file format, the orientations are controlled bondtype the “match” attribute. In this case, only the keywords “once” and “all_permuations” are allowed, meaning only the first orientation or all possible orientations are generated.

The virtual site adders via Molecule simplify this by optionally using a symmetric kwarg, which is the equivalent to the XML match keyword described above. However, the symmetric kwarg is not available for sites which symmetry is not possible, e.g. TrivalentLonePairVirtualSite, provided a layer of sanity checking. For the TIP5 example above, setting symmetric=True (the default) should automatically produce both particles.

Returns

List of tuples of ints specifying the ordering of the parent atoms.

property particles: Generator[openff.toolkit.topology.molecule.VirtualParticle, None, None]

Particles owned by this VirtualSite

to_bson()

Return a BSON serialized representation.

Specification: http://bsonspec.org/

Returns

serialized (bytes) – A BSON serialized representation of the objecft

to_json(indent=None)

Return a JSON serialized representation.

Specification: https://www.json.org/

Parameters

indent (int, optional, default=None) – If not None, will pretty-print with specified number of spaces for indentation

Returns

serialized (str) – A JSON serialized representation of the object

to_messagepack()

Return a MessagePack representation.

Specification: https://msgpack.org/index.html

Returns

serialized (bytes) – A MessagePack-encoded bytes serialized representation of the object

to_pickle()

Return a pickle serialized representation.

Warning

This is not recommended for safe, stable storage since the pickle specification may change between Python versions.

Returns

serialized (str) – A pickled representation of the object

to_toml()

Return a TOML serialized representation.

Specification: https://github.com/toml-lang/toml

Returns

serialized (str) – A TOML serialized representation of the object

to_xml(indent=2)

Return an XML representation.

Specification: https://www.w3.org/XML/

Parameters

indent (int, optional, default=2) – If not None, will pretty-print with specified number of spaces for indentation

Returns

serialized (bytes) – A MessagePack-encoded bytes serialized representation.

to_yaml()

Return a YAML serialized representation.

Specification: http://yaml.org/

Returns

serialized (str) – A YAML serialized representation of the object

property type: str

The type of this VirtualSite (returns the class name as string)