VirtualSiteHandler

class openff.toolkit.typing.engines.smirnoff.parameters.VirtualSiteHandler(**kwargs)[source]

Handle SMIRNOFF <VirtualSites> tags TODO: 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 – 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 – 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.

attribute_is_cosmetic(attr_name)

Determine whether an attribute of this object is cosmetic.

check_handler_compatibility(other_handler)

Checks if a set of kwargs used to create a ParameterHandler are compatible with this ParameterHandler.

create_force(*args, **kwarsg)

Deprecated since version 0.11.0.

delete_cosmetic_attribute(attr_name)

Delete a cosmetic attribute from this object.

find_matches(entity[, unique])

Find the elements of the topology/molecule matched by a parameter type.

get_parameter(parameter_attrs)

Return the parameters in this ParameterHandler that match the parameter_attrs argument.

to_dict([discard_cosmetic_attributes])

Convert this ParameterHandler to a dict, compliant with the SMIRNOFF data spec.

Attributes

TAGNAME

The name of this ParameterHandler corresponding to the SMIRNOFF tag name

exclusion_policy

known_kwargs

List of kwargs that can be parsed by the function.

parameters

The ParameterList that holds this ParameterHandler's parameter objects

version

class VirtualSiteType(**kwargs)[source]

Store virtual site parameters (geometry and electrostatics) and vdW interactions.

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 OpenFF 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).

Parameters:
  • attr_name – Name of the attribute to define for this object.

  • attr_value – The value of the attribute to define for this object.

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 – The attribute name to check

Returns:

is_cosmetic – 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 – Name of the cosmetic attribute to delete.

property parent_index: int

Returns the index of the atom matched by the SMIRKS pattern that should be considered the ‘parent’ to the virtual site. A value of 0 corresponds to the atom matched by the :1 selector in the SMIRKS pattern, a value 2 the atom matched by :2 and so on.

to_dict(discard_cosmetic_attributes=False, duplicate_attributes=None)

Convert this object to dict format.

The returning dictionary contains all the ParameterAttribute and IndexedParameterAttribute as well as cosmetic attributes if discard_cosmetic_attributes is False.

Parameters:
  • discard_cosmetic_attributes – Whether to discard non-spec attributes of this object

  • duplicate_attributes – A list of names of attributes that redundantly decsribe data and should be discarded during serializaiton

Returns:

smirnoff_dict – The SMIRNOFF-compliant dict representation of this object.

classmethod type_to_parent_index(type_: Literal['BondCharge', 'MonovalentLonePair', 'DivalentLonePair', 'TrivalentLonePair']) int

Returns the index of the atom matched by the SMIRKS pattern that should be considered the ‘parent’ to a given type of virtual site. A value of 0 corresponds to the atom matched by the :1 selector in the SMIRKS pattern, a value 2 the atom matched by :2 and so on.

property TAGNAME

The name of this ParameterHandler corresponding to the SMIRNOFF tag name

Returns:

handler_name – 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 OpenFF 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).

Parameters:
  • attr_name – Name of the attribute to define for this object.

  • attr_value – The value of the attribute to define for this object.

add_parameter(parameter_kwargs: dict | None = None, parameter: ParameterType | None = None, after: str | None = None, before: str | None = None, allow_duplicate_smirks: bool = False)

Add a parameter to the force field, ensuring all parameters are valid.

Parameters:
  • parameter_kwargs – The kwargs to pass to the ParameterHandler.INFOTYPE (a ParameterType) constructor

  • parameter – A ParameterType to add to the ParameterHandler

  • after – The SMIRKS pattern (if str) or index (if int) of the parameter directly before where the new parameter will be added

  • before – The SMIRKS pattern (if str) or index (if int) of the parameter directly after where the new parameter will be added

  • allow_duplicate_smirks – If False, a DuplicateParameterError will be raised if the parameter being added has a SMIRKS that already appears in another parameter owned by this ParameterHandler.

  • behavior (Note the following) –

    • Either parameter_kwargs or parameter must be specified.

    • When before and after are both None, the new parameter will be appended to the END of the parameter list.

    • When before and after are both specified, the new parameter will be added immediately after the parameter matching the after pattern or index.

    • The order of parameters in a parameter list can have significant impacts on parameter assignment. For details, see the SMIRNOFF specification: https://openforcefield.github.io/standards/standards/smirnoff/#smirnoff-parameter-specification-is-hierarchical

Examples

Add a ParameterType to an existing ParameterList at a specified position.

Given an existing parameter handler and a new parameter to add to it:

>>> from openff.toolkit import unit
>>> bh = BondHandler(skip_version_check=True)
>>> length = 1.5 * unit.angstrom
>>> k = 100 * unit.kilocalorie / unit.mole / unit.angstrom ** 2
>>> bh.add_parameter({'smirks': '[*:1]-[*:2]', 'length': length, 'k': k, 'id': 'b1'})
>>> bh.add_parameter({'smirks': '[*:1]=[*:2]', 'length': length, 'k': k, 'id': 'b2'})
>>> bh.add_parameter({'smirks': '[*:1]#[*:2]', 'length': length, 'k': k, 'id': 'b3'})
>>> [p.id for p in bh.parameters]
['b1', 'b2', 'b3']
>>> param = {'smirks': '[#1:1]-[#6:2]', 'length': length, 'k': k, 'id': 'b4'}

Add a new parameter immediately after the parameter with the smirks ‘[:1]=[:2]’

>>> bh.add_parameter(param, after='[*:1]=[*:2]')
>>> [p.id for p in bh.parameters]
['b1', 'b2', 'b4', 'b3']
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 – The attribute name to check

Returns:

is_cosmetic – Returns True if the attribute is defined and is cosmetic. Returns False otherwise.

check_handler_compatibility(other_handler: VirtualSiteHandler)[source]

Checks if a set of kwargs used to create a ParameterHandler are compatible with this ParameterHandler. This is called if a second handler is attempted to be initialized for the same tag.

Parameters:

handler_kwargs – The kwargs that would be used to construct

Raises:

IncompatibleParameterError if handler_kwargs are incompatible with existing parameters.

create_force(*args, **kwarsg)

Deprecated since version 0.11.0: This method was deprecated in v0.11.0, no longer has any functionality, and will soon be removed. Use the OpenFF Interchange package instead.

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 – Name of the cosmetic attribute to delete.

find_matches(entity: Topology, unique: bool = False) ValenceDict

Find the elements of the topology/molecule matched by a parameter type.

Parameters:
  • entity – Topology to search.

  • unique – If False, SMARTS matching will enumerate every valid permutation of matching atoms. If True, only one order of each unique match will be returned.

Returns:

matchesmatches[atom_indices] is the ParameterType object matching the tuple of atom indices in entity.

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 – The attrs mapped to desired values (for example {“smirks”: “[:1]~[#16:2]=,:[#6:3]~[:4]”, “id”: “t105”} )

Returns:

params – A list of matching ParameterType objects

Examples

Create a parameter handler and populate it with some data.

>>> from openff.toolkit import unit
>>> handler = BondHandler(skip_version_check=True)
>>> handler.add_parameter(
...     {
...         'smirks': '[*:1]-[*:2]',
...         'length': 1*unit.angstrom,
...         'k': 10*unit.kilocalorie / unit.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 angstrom  k: 10.0 kilocalorie / angstrom ** 2 / mole  >]
property known_kwargs

List of kwargs that can be parsed by the function.

property parameters

The ParameterList that holds this ParameterHandler’s parameter objects

to_dict(discard_cosmetic_attributes: bool = False) dict

Convert this ParameterHandler to a dict, compliant with the SMIRNOFF data spec.

Parameters:

discard_cosmetic_attributes – Whether to discard non-spec parameter and header attributes in this ParameterHandler.

Returns:

smirnoff_data – SMIRNOFF-spec compliant representation of this ParameterHandler and its internal ParameterList.