openff.toolkit.typing.engines.smirnoff.parameters.VirtualSiteHandler
- class openff.toolkit.typing.engines.smirnoff.parameters.VirtualSiteHandler(**kwargs)[source]
Handle SMIRNOFF
<VirtualSites>
tagsTODO: Add example usage/documentation
Warning
This API is experimental and subject to change.
- __init__(**kwargs)[source]
Initialize a ParameterHandler, optionally with a list of parameters and other kwargs.
- Parameters
allow_cosmetic_attributes (bool, optional. Default = False) – Whether to permit non-spec kwargs. If True, non-spec kwargs will be stored as attributes of this object and can be accessed and modified. Otherwise an exception will be raised if a non-spec kwarg is encountered.
skip_version_check (bool, optional. Default = False) – If False, the SMIRNOFF section version will not be checked, and the ParameterHandler will be initialized with version set to _MAX_SUPPORTED_SECTION_VERSION.
**kwargs (dict) – The dict representation of the SMIRNOFF data source
Methods
__init__
(**kwargs)Initialize a ParameterHandler, optionally with a list of parameters and other kwargs.
add_cosmetic_attribute
(attr_name, attr_value)Add a cosmetic attribute to this object.
add_parameter
([parameter_kwargs, parameter, ...])Add a parameter to the force field, ensuring all parameters are valid.
assign_parameters
(topology, system)Assign parameters for the given Topology to the specified OpenMM
System
object.assign_partial_bond_orders_from_molecules
(...)attribute_is_cosmetic
(attr_name)Determine whether an attribute of this object is cosmetic.
check_charges_assigned
(ref_mol, topology)Check whether charges have been assigned for a reference molecule.
check_handler_compatibility
(other_handler)Checks whether this ParameterHandler encodes compatible physics as another ParameterHandler.
check_partial_bond_orders_from_molecules_duplicates
(pb_mols)create_force
(system, topology, **kwargs)create_openff_virtual_sites
(topology)Modifies the input topology to contain VirtualSites assigned by this handler.
delete_cosmetic_attribute
(attr_name)Delete a cosmetic attribute from this object.
find_matches
(entity[, expand_permutations, ...])Find the virtual sites in the topology/molecule matched by a parameter type.
get_parameter
(parameter_attrs)Return the parameters in this ParameterHandler that match the parameter_attrs argument.
mark_charges_assigned
(ref_mol, topology)Record that charges have been assigned for a reference molecule.
postprocess_system
(topology, system, **kwargs)Allow the force to perform a a final post-processing pass on the OpenMM
System
following parameter assignment, if needed.register_virtual_site_type
(vsite_name, vsite_cls)Register an implemented virtual site type.
to_dict
([discard_cosmetic_attributes])Convert this ParameterHandler to an OrderedDict, compliant with the SMIRNOFF data spec.
Attributes
The name of this ParameterHandler corresponding to the SMIRNOFF tag name
exclusion_policy
List of kwargs that can be parsed by the function.
The ParameterList that holds this ParameterHandler's parameter objects
version
Return the dictionary of registered virtual site types
- add_parameter(parameter_kwargs=None, parameter=None, after=None, before=None)[source]
Add a parameter to the force field, ensuring all parameters are valid. This method differs from other handlers in that it uses a plugin-style enable/disable type system
- Parameters
parameter_kwargs (dict, optional) – The kwargs to pass to the ParameterHandler.INFOTYPE (a ParameterType) constructor
parameter (the new) – A ParameterType to add to the ParameterHandler
after (str or int, optional) – The SMIRKS pattern (if str) or index (if int) of the parameter directly before where the new parameter will be added
before (str, optional) – The SMIRKS pattern (if str) or index (if int) of the parameter directly after where the new parameter will be added
(parameter_kwargs (Note that one of) –
specified (Note that when before and after are both) –
None (Note that when before and after are both) – to the END of the parameter list.
appended (the new parameter will be) – to the END of the parameter list.
specified – will be added immediately after the parameter matching the after pattern or index.
parameter – will be added immediately after the parameter matching the after pattern or index.
- register_virtual_site_type(vsite_name, vsite_cls, replace=False)[source]
Register an implemented virtual site type. Doing this must be done to pass the validation and option checking. To disable a type, register the name with None and replace=True
- Parameters
vsite_name (str) – The name of the type. This name must be what is found in the “type” attribute in the OFFXML format
vsite_cls (Any) – The class to register the name with that implements the type.
- Returns
None
- property virtual_site_types
Return the dictionary of registered virtual site types
- Parameters
None –
- Returns
virtual_site_types (dict) – A list of virtual site types already registered, paired with their class that implements them
- class VirtualSiteType(**kwargs)[source]
A SMIRNOFF virtual site base type
Warning
This API is experimental and subject to change.
- transformed_dict_cls
alias of
ValenceDict
- classmethod vsite_type()[source]
The type of this virtual site as represented in the SMIRNOFF specification
Warning
This API is experimental and subject to change.
- add_cosmetic_attribute(attr_name, attr_value)
Add a cosmetic attribute to this object.
This attribute will not have a functional effect on the object in the Open Force Field Toolkit, but can be written out during output.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- attribute_is_cosmetic(attr_name)
Determine whether an attribute of this object is cosmetic.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – The attribute name to check
- Returns
is_cosmetic (bool) – Returns True if the attribute is defined and is cosmetic. Returns False otherwise.
- delete_cosmetic_attribute(attr_name)
Delete a cosmetic attribute from this object.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – Name of the cosmetic attribute to delete.
- to_dict(discard_cosmetic_attributes=False, duplicate_attributes=None)
Convert this object to dict format.
The returning dictionary contains all the
ParameterAttribute
andIndexedParameterAttribute
as well as cosmetic attributes ifdiscard_cosmetic_attributes
isFalse
.- Parameters
discard_cosmetic_attributes (bool, optional. Default = False) – Whether to discard non-spec attributes of this object
duplicate_attributes (list of string, optional. Default = None) – A list of names of attributes that redundantly decsribe data and should be discarded during serializaiton
- Returns
smirnoff_dict (dict) – The SMIRNOFF-compliant dict representation of this object.
- class VirtualSiteBondChargeType(**kwargs)[source]
A SMIRNOFF virtual site bond charge type
Warning
This API is experimental and subject to change.
- add_virtual_site(molecule, orientations, replace=False)[source]
Add a virtual site to the molecule
- Parameters
molecule (openff.toolkit.topology.molecule.Molecule) – The molecule to add the virtual site to
orientations (List[Tuple[int]]) – A list of orientation tuples which define the permuations used to contruct the geometry of the virtual site particles
replace (bool, default=False) – Replace this virtual site if it already exists in the molecule
- Returns
off_idx (int) – The index of the first particle added due to this virtual site
.. warning :: This API is experimental and subject to change.
- add_cosmetic_attribute(attr_name, attr_value)
Add a cosmetic attribute to this object.
This attribute will not have a functional effect on the object in the Open Force Field Toolkit, but can be written out during output.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- attribute_is_cosmetic(attr_name)
Determine whether an attribute of this object is cosmetic.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – The attribute name to check
- Returns
is_cosmetic (bool) – Returns True if the attribute is defined and is cosmetic. Returns False otherwise.
- delete_cosmetic_attribute(attr_name)
Delete a cosmetic attribute from this object.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – Name of the cosmetic attribute to delete.
- to_dict(discard_cosmetic_attributes=False, duplicate_attributes=None)
Convert this object to dict format.
The returning dictionary contains all the
ParameterAttribute
andIndexedParameterAttribute
as well as cosmetic attributes ifdiscard_cosmetic_attributes
isFalse
.- Parameters
discard_cosmetic_attributes (bool, optional. Default = False) – Whether to discard non-spec attributes of this object
duplicate_attributes (list of string, optional. Default = None) – A list of names of attributes that redundantly decsribe data and should be discarded during serializaiton
- Returns
smirnoff_dict (dict) – The SMIRNOFF-compliant dict representation of this object.
- transformed_dict_cls
alias of
ValenceDict
- class VirtualSiteMonovalentLonePairType(**kwargs)[source]
A SMIRNOFF monovalent lone pair virtual site type
Warning
This API is experimental and subject to change.
- add_virtual_site(molecule, orientations, replace=False)[source]
Add a virtual site to the molecule
- Parameters
molecule (openff.toolkit.topology.molecule.Molecule) – The molecule to add the virtual site to
orientations (List[Tuple[int]]) – A list of orientation tuples which define the permuations used to contruct the geometry of the virtual site particles
replace (bool, default=False) – Replace this virtual site if it already exists in the molecule
- Returns
off_idx (int) – The index of the first particle added due to this virtual site
.. warning :: This API is experimental and subject to change.
- add_cosmetic_attribute(attr_name, attr_value)
Add a cosmetic attribute to this object.
This attribute will not have a functional effect on the object in the Open Force Field Toolkit, but can be written out during output.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- attribute_is_cosmetic(attr_name)
Determine whether an attribute of this object is cosmetic.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – The attribute name to check
- Returns
is_cosmetic (bool) – Returns True if the attribute is defined and is cosmetic. Returns False otherwise.
- delete_cosmetic_attribute(attr_name)
Delete a cosmetic attribute from this object.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – Name of the cosmetic attribute to delete.
- to_dict(discard_cosmetic_attributes=False, duplicate_attributes=None)
Convert this object to dict format.
The returning dictionary contains all the
ParameterAttribute
andIndexedParameterAttribute
as well as cosmetic attributes ifdiscard_cosmetic_attributes
isFalse
.- Parameters
discard_cosmetic_attributes (bool, optional. Default = False) – Whether to discard non-spec attributes of this object
duplicate_attributes (list of string, optional. Default = None) – A list of names of attributes that redundantly decsribe data and should be discarded during serializaiton
- Returns
smirnoff_dict (dict) – The SMIRNOFF-compliant dict representation of this object.
- transformed_dict_cls
alias of
ValenceDict
- class VirtualSiteDivalentLonePairType(**kwargs)[source]
A SMIRNOFF divalent lone pair virtual site type
Warning
This API is experimental and subject to change.
- add_virtual_site(molecule, orientations, replace=False)[source]
Add a virtual site to the molecule
- Parameters
molecule (openff.toolkit.topology.molecule.Molecule) – The molecule to add the virtual site to
orientations (List[Tuple[int]]) – A list of orientation tuples which define the permuations used to contruct the geometry of the virtual site particles
replace (bool, default=False) – Replace this virtual site if it already exists in the molecule
- Returns
off_idx (int) – The index of the first particle added due to this virtual site
.. warning :: This API is experimental and subject to change.
- add_cosmetic_attribute(attr_name, attr_value)
Add a cosmetic attribute to this object.
This attribute will not have a functional effect on the object in the Open Force Field Toolkit, but can be written out during output.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- attribute_is_cosmetic(attr_name)
Determine whether an attribute of this object is cosmetic.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – The attribute name to check
- Returns
is_cosmetic (bool) – Returns True if the attribute is defined and is cosmetic. Returns False otherwise.
- delete_cosmetic_attribute(attr_name)
Delete a cosmetic attribute from this object.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – Name of the cosmetic attribute to delete.
- to_dict(discard_cosmetic_attributes=False, duplicate_attributes=None)
Convert this object to dict format.
The returning dictionary contains all the
ParameterAttribute
andIndexedParameterAttribute
as well as cosmetic attributes ifdiscard_cosmetic_attributes
isFalse
.- Parameters
discard_cosmetic_attributes (bool, optional. Default = False) – Whether to discard non-spec attributes of this object
duplicate_attributes (list of string, optional. Default = None) – A list of names of attributes that redundantly decsribe data and should be discarded during serializaiton
- Returns
smirnoff_dict (dict) – The SMIRNOFF-compliant dict representation of this object.
- transformed_dict_cls
alias of
ValenceDict
- class VirtualSiteTrivalentLonePairType(**kwargs)[source]
A SMIRNOFF trivalent lone pair virtual site type
Warning
This API is experimental and subject to change.
- transformed_dict_cls
alias of
ImproperDict
- add_cosmetic_attribute(attr_name, attr_value)
Add a cosmetic attribute to this object.
This attribute will not have a functional effect on the object in the Open Force Field Toolkit, but can be written out during output.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- attribute_is_cosmetic(attr_name)
Determine whether an attribute of this object is cosmetic.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – The attribute name to check
- Returns
is_cosmetic (bool) – Returns True if the attribute is defined and is cosmetic. Returns False otherwise.
- delete_cosmetic_attribute(attr_name)
Delete a cosmetic attribute from this object.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – Name of the cosmetic attribute to delete.
- to_dict(discard_cosmetic_attributes=False, duplicate_attributes=None)
Convert this object to dict format.
The returning dictionary contains all the
ParameterAttribute
andIndexedParameterAttribute
as well as cosmetic attributes ifdiscard_cosmetic_attributes
isFalse
.- Parameters
discard_cosmetic_attributes (bool, optional. Default = False) – Whether to discard non-spec attributes of this object
duplicate_attributes (list of string, optional. Default = None) – A list of names of attributes that redundantly decsribe data and should be discarded during serializaiton
- Returns
smirnoff_dict (dict) – The SMIRNOFF-compliant dict representation of this object.
- classmethod vsite_type()
The type of this virtual site as represented in the SMIRNOFF specification
Warning
This API is experimental and subject to change.
- add_virtual_site(molecule, orientations, replace=False)[source]
Add a virtual site to the molecule
- Parameters
molecule (openff.toolkit.topology.molecule.Molecule) – The molecule to add the virtual site to
orientations (List[Tuple[int]]) – A list of orientation tuples which define the permuations used to contruct the geometry of the virtual site particles
replace (bool, default=False) – Replace this virtual site if it already exists in the molecule
- Returns
off_idx (int) – The index of the first particle added due to this virtual site
.. warning :: This API is experimental and subject to change.
- property TAGNAME
The name of this ParameterHandler corresponding to the SMIRNOFF tag name
- Returns
handler_name (str) – The name of this parameter handler
- add_cosmetic_attribute(attr_name, attr_value)
Add a cosmetic attribute to this object.
This attribute will not have a functional effect on the object in the Open Force Field Toolkit, but can be written out during output.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- assign_parameters(topology, system)
Assign parameters for the given Topology to the specified OpenMM
System
object.- Parameters
topology (openff.toolkit.topology.Topology) – The Topology for which parameters are to be assigned. Either a new Force will be created or parameters will be appended to an existing Force.
system (openmm.System) – The OpenMM System object to add the Force (or append new parameters) to.
- attribute_is_cosmetic(attr_name)
Determine whether an attribute of this object is cosmetic.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – The attribute name to check
- Returns
is_cosmetic (bool) – Returns True if the attribute is defined and is cosmetic. Returns False otherwise.
- static check_charges_assigned(ref_mol, topology)
Check whether charges have been assigned for a reference molecule.
- Parameters
ref_mol (openff.toolkit.topology.Molecule) – The molecule to check for having charges assigned
topology (openff.toolkit.topology.Topology) – The topology to query for this information
- Returns
charges_assigned (bool) – Whether charges have already been assigned to this molecule
- delete_cosmetic_attribute(attr_name)
Delete a cosmetic attribute from this object.
Warning
The API for modifying cosmetic attributes is experimental and may change in the future (see issue #338).
- Parameters
attr_name (str) – Name of the cosmetic attribute to delete.
- get_parameter(parameter_attrs)
Return the parameters in this ParameterHandler that match the parameter_attrs argument. When multiple attrs are passed, parameters that have any (not all) matching attributes are returned.
- Parameters
parameter_attrs (dict of {attr: value}) – The attrs mapped to desired values (for example {“smirks”: “[:1]~[#16:2]=,:[#6:3]~[:4]”, “id”: “t105”} )
- Returns
params (list of ParameterType objects) – A list of matching ParameterType objects
Examples
Create a parameter handler and populate it with some data.
>>> from openmm import unit >>> handler = BondHandler(skip_version_check=True) >>> handler.add_parameter( ... { ... 'smirks': '[*:1]-[*:2]', ... 'length': 1*unit.angstrom, ... 'k': 10*unit.kilocalorie_per_mole/unit.angstrom**2, ... } ... )
Look up, from this handler, all parameters matching some SMIRKS pattern
>>> handler.get_parameter({'smirks': '[*:1]-[*:2]'}) [<BondType with smirks: [*:1]-[*:2] length: 1 A k: 10 kcal/(A**2 mol) >]
- mark_charges_assigned(ref_mol, topology)
Record that charges have been assigned for a reference molecule.
- Parameters
ref_mol (openff.toolkit.topology.Molecule) – The molecule to mark as having charges assigned
topology (openff.toolkit.topology.Topology) – The topology to record this information on.
- postprocess_system(topology, system, **kwargs)
Allow the force to perform a a final post-processing pass on the OpenMM
System
following parameter assignment, if needed.- Parameters
topology (openff.toolkit.topology.Topology) – The Topology for which parameters are to be assigned. Either a new Force will be created or parameters will be appended to an existing Force.
system (openmm.System) – The OpenMM System object to add the Force (or append new parameters) to.
- to_dict(discard_cosmetic_attributes=False)
Convert this ParameterHandler to an OrderedDict, compliant with the SMIRNOFF data spec.
- Parameters
discard_cosmetic_attributes (bool, optional. Default = False.) – Whether to discard non-spec parameter and header attributes in this ParameterHandler.
- Returns
smirnoff_data (OrderedDict) – SMIRNOFF-spec compliant representation of this ParameterHandler and its internal ParameterList.
- create_force(system, topology, **kwargs)[source]
- check_handler_compatibility(other_handler)[source]
Checks whether this ParameterHandler encodes compatible physics as another ParameterHandler. This is called if a second handler is attempted to be initialized for the same tag.
- Parameters
other_handler (a ParameterHandler object) – The handler to compare to.
- Raises
IncompatibleParameterError if handler_kwargs are incompatible with –
existing parameters. –
- find_matches(entity, expand_permutations=True, unique=False)[source]
Find the virtual sites in the topology/molecule matched by a parameter type.
- Parameters
entity (openff.toolkit.topology.Topology) – Topology to search.
- Returns
matches (Dict[Tuple[int], ParameterHandler._Match]) –
matches[atom_indices]
is theParameterType
object matching the n-tuple of atom indices inentity
.
- create_openff_virtual_sites(topology)[source]
Modifies the input topology to contain VirtualSites assigned by this handler.
- Parameters
topology (openff.toolkit.topology.Topology) – Topology to add virtual sites to.