openff.toolkit.topology.VirtualSite

class openff.toolkit.topology.VirtualSite(atoms, charge_increments=None, epsilon=None, sigma=None, rmin_half=None, name=None, orientations=None)[source]

A container representing one or more virtual particles whose positions are defined in terms of Atom positions. This container enables the coupling of particles that are symmetric about some axis/plane of the underlying atoms. For example, a single virtual site can represent two lone pairs of a water molecule, where the angle and distance parameters are expected to stay coupled, and are reflections across the plane of symmetry.

Note that chemical atoms are represented by the Atom.

Warning

This API is experimental and subject to change.

__init__(atoms, charge_increments=None, epsilon=None, sigma=None, rmin_half=None, name=None, orientations=None)[source]

Base class for VirtualSites

Parameters
atomslist of Atom of shape [N]

atoms[index] is the corresponding Atom

charge_incrementslist of floats of shape [N], optional, default=None

The amount of charge to remove from the VirtualSite’s atoms and put in the VirtualSite. Indexing in this list should match the ordering in the atoms list. Default is None.

sigmafloat, default=None

Sigma term for VdW properties of virtual site. Default is None.

epsilonfloat

Epsilon term for VdW properties of virtual site. Default is None.

rmin_halffloat

Rmin_half term for VdW properties of virtual site. Default is None.

namestring or None, default=None

The name of this virtual site. Default is None.

virtual_site_typestr

Virtual site type.

namestr or None, default=None

The name of this virtual site. Default is None

orientationlist of int tuples or None, default=None

The ordering of the atoms used to define the frame of the virtual site.

Methods

__init__(atoms[, charge_increments, ...])

Base class for VirtualSites

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.

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.

charge_increments

Charges taken from this VirtualSite's atoms and given to the VirtualSite

epsilon

The VdW epsilon term of this VirtualSite

local_frame_position

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

local_frame_weights

The per-atom weights used to define the virtual site frame.

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

rmin_half

The VdW rmin_half term of this VirtualSite

sigma

The VdW sigma term of 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.

index_of_orientation(virtual_particle)[source]

Return the orientation used by the given virtual particle.

Parameters
virtual_particleVirtualParticle

The virtual particle contained in this virual site

Returns
A tuple of atom indices
property orientations

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

Particles owned by this VirtualSite

property n_particles

The number of particles that the virtual site represents

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

property atoms

Atoms on whose position this VirtualSite depends.

property charge_increments

Charges taken from this VirtualSite’s atoms and given to the VirtualSite

property epsilon

The VdW epsilon term of this VirtualSite

property sigma

The VdW sigma term of this VirtualSite

property rmin_half

The VdW rmin_half term of this VirtualSite

property name

The name of this VirtualSite

property type

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

abstract property local_frame_weights

The per-atom weights used to define the virtual site frame.

The SMIRNOFF virtual sites use the definition of openmm.LocalCoordinatesSite implemented by OpenMM. As such, the weights are used to determine the origin and the x and y axes of the local frame. Since the frame is an orthogonal bases, the z axis is not specified as it is assumed to be the cross of the x and y axes (using a right-handed coordinates).

The weights defined refer to the weights of each atom’s positions. For the origin, the weights must sum to 1. For the x and y axes, the weights much each sum to 0. For example, for a custom bond charge virtual site with two atoms:

  • Origin: [.5, .5] The origin of the frame is always in between atom 1 and atom 2. The calculation is 0.5 * atom1.xyz + 0.5 * atom2.xyz

  • X-Axis: [-1, 1] The x-axis points from atom 1 to atom 2. Positive displacements of this axis are closer to atom 2.

  • Y-Axis: [0, 0] This axis must be defined, so here we set it to the null space. Any displacements along y are sent to 0. Because of this, the z-axis will also be 0.

The displacements along the axes defined here are defined/returned by VirtualSite.local_frame_position.

To implement a new virtual site type (using a LocalCoordinatesSite definition), override this function.

Returns
Tuple of list of weights used to define the origin, x-axis, and y-axis
abstract property local_frame_position

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

The SMIRNOFF virtual sites use the definition of openmm.LocalCoordinatesSite as implemented by OpenMM. As such, the frame positions refer to positions as defined by the frame, or the local axes defined by the owning atoms (see VirtualSite.local_frame_weights).

To implement a new virtual site type (using a LocalCoordinatesSite definition), override this function.

Returns
openmm.unit.Quantity of dimension [Length] wrapping a list of
displacements in the local frame for the x, y, and z directions.
compute_positions_from_conformer(conformer_idx)[source]

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

Parameters
conformer_idxint

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.

compute_positions_from_atom_positions(atom_positions)[source]

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

Parameters
atom_positionsopenmm.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.

classmethod from_bson(serialized)

Instantiate an object from a BSON serialized representation.

Specification: http://bsonspec.org/

Parameters
serializedbytes

A BSON serialized representation of the object

Returns
instancecls

An instantiated object

classmethod from_json(serialized)

Instantiate an object from a JSON serialized representation.

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

Parameters
serializedstr

A JSON serialized representation of the object

Returns
instancecls

An instantiated object

classmethod from_messagepack(serialized)

Instantiate an object from a MessagePack serialized representation.

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

Parameters
serializedbytes

A MessagePack-encoded bytes serialized representation

Returns
instancecls

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
serializedstr

A pickled representation of the object

Returns
instancecls

An instantiated object

classmethod from_toml(serialized)

Instantiate an object from a TOML serialized representation.

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

Parameters
serlializedstr

A TOML serialized representation of the object

Returns
instancecls

An instantiated object

classmethod from_xml(serialized)

Instantiate an object from an XML serialized representation.

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

Parameters
serializedbytes

An XML serialized representation

Returns
instancecls

Instantiated object.

classmethod from_yaml(serialized)

Instantiate from a YAML serialized representation.

Specification: http://yaml.org/

Parameters
serializedstr

A YAML serialized representation of the object

Returns
instancecls

Instantiated object

property molecule

The Molecule this particle is part of.

property molecule_particle_index

Returns the index of this particle in its molecule

to_bson()

Return a BSON serialized representation.

Specification: http://bsonspec.org/

Returns
serializedbytes

A BSON serialized representation of the objecft

to_json(indent=None)

Return a JSON serialized representation.

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

Parameters
indentint, optional, default=None

If not None, will pretty-print with specified number of spaces for indentation

Returns
serializedstr

A JSON serialized representation of the object

to_messagepack()

Return a MessagePack representation.

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

Returns
serializedbytes

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
serializedstr

A pickled representation of the object

to_toml()

Return a TOML serialized representation.

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

Returns
serializedstr

A TOML serialized representation of the object

to_xml(indent=2)

Return an XML representation.

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

Parameters
indentint, optional, default=2

If not None, will pretty-print with specified number of spaces for indentation

Returns
serializedbytes

A MessagePack-encoded bytes serialized representation.

to_yaml()

Return a YAML serialized representation.

Specification: http://yaml.org/

Returns
serializedstr

A YAML serialized representation of the object