openff.toolkit.topology.MonovalentLonePairVirtualSite
- class openff.toolkit.topology.MonovalentLonePairVirtualSite(atoms, distance, out_of_plane_angle, in_plane_angle, charge_increments=None, epsilon=None, sigma=None, rmin_half=None, name=None, orientations=None)[source]
A particle representing a “Monovalent Lone Pair”-type virtual site, in which the location of the charge is specified by the positions of three atoms. This is originally intended for situations like a carbonyl, and allows placement of a virtual site S at a specified distance d, in_plane_angle, and out_of_plane_angle relative to a central atom and two connected atoms.
Warning
This API is experimental and subject to change.
- __init__(atoms, distance, out_of_plane_angle, in_plane_angle, charge_increments=None, epsilon=None, sigma=None, rmin_half=None, name=None, orientations=None)[source]
Create a bond charge-type virtual site, in which the location of the charge is specified by the position of three atoms.
- Parameters
- atomslist of three openff.toolkit.topology.molecule.Atom objects
The three atoms defining the virtual site’s position
- distance
openmm.unit.Quantity
of dimension [Length] wrapping a scalar - out_of_plane_angle
openmm.unit.Quantity
of dimension [Angle] wrapping - a scalar
- in_plane_angle
openmm.unit.Quantity
of dimension [Angle] wrapping a - scalar
- epsilonfloat
Epsilon term for VdW properties of virtual site. Default is None.
- sigmafloat, default=None
Sigma 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.
- orientationslist of tuples of 3 Atoms or ints
The permutations of the matched atoms that should be used to define the orientation of each virtual site particle
Methods
__init__
(atoms, distance, ...[, ...])Create a bond charge-type virtual site, in which the location of the charge is specified by the position of three atoms.
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)Construct a new MonovalentLonePairVirtualSite from an serialized dictionary 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 MonovalentLonePairVirtualSite.
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.
Return a MessagePack representation.
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 on whose position this VirtualSite depends.
Charges taken from this VirtualSite's atoms and given to the VirtualSite
The distance parameter of the virtual site
The VdW epsilon term of this VirtualSite
The in_plane_angle parameter of the virtual site
The displacements of the virtual site relative to the local frame.
Returns the local frame weights used to calculate the particle positions.
The
Molecule
this particle is part of.Returns the index of this particle in its molecule
The index of this VirtualSite within the list of virtual sites within
Molecule
Note that this can be different fromparticle_index
.The number of particles that the virtual site represents
The name of this VirtualSite
The orientations used by the virtual site particles.
The out_of_plane_angle parameter of the virtual site
Particles owned by this VirtualSite
The VdW rmin_half term of this VirtualSite
The VdW sigma term of this VirtualSite
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]
Construct a new MonovalentLonePairVirtualSite from an serialized dictionary representation.
- Parameters
- vsite_dictdict
The VirtualSite to deserialize.
- Returns
- The newly created MonovalentLonePairVirtualSite
- property local_frame_weights
Returns the local frame weights used to calculate the particle positions. See
VirtualSite.local_frame_weights
for a general description.- 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 MonovalentLonePairVirtualSite.
- Parameters
- atomsiterable of int
The indices of the atoms involved in this virtual site.
- Returns
openmm.LocalCoordinatesSite
- 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.
- atom_positions
- 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_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.
- 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
- index_of_orientation(virtual_particle)
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 molecule_virtual_site_index
The index of this VirtualSite within the list of virtual sites within
Molecule
Note that this can be different fromparticle_index
.
- 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
anddistance
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 asymmetric
kwarg, which is the equivalent to the XMLmatch
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, settingsymmetric=True
(the default) should automatically produce both particles.- Returns
- List of tuples of ints specifying the ordering of the parent atoms.
- 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