openff.toolkit.typing.engines.smirnoff.parameters.ElectrostaticsHandler

class openff.toolkit.typing.engines.smirnoff.parameters.ElectrostaticsHandler(allow_cosmetic_attributes=False, skip_version_check=False, **kwargs)[source]

Handles SMIRNOFF <Electrostatics> tags.

Warning

This API is experimental and subject to change.

__init__(allow_cosmetic_attributes=False, skip_version_check=False, **kwargs)

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__([allow_cosmetic_attributes, ...])

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_charge_from_molecules(molecule, ...)

Given an input molecule, checks against a list of molecules for an isomorphic match.

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)

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.

mark_charges_assigned(ref_mol, topology)

Record that charges have been assigned for a reference molecule.

postprocess_system(system, topology, **kwargs)

Allow the force to perform a a final post-processing pass on the OpenMM System following parameter assignment, if needed.

to_dict([discard_cosmetic_attributes])

Convert this ParameterHandler to an OrderedDict, compliant with the SMIRNOFF data spec.

Attributes

TAGNAME

The name of this ParameterHandler corresponding to the SMIRNOFF tag name

cutoff

known_kwargs

List of kwargs that can be parsed by the function.

method

parameters

The ParameterList that holds this ParameterHandler's parameter objects

scale12

scale13

scale14

scale15

switch_width

version

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.

assign_charge_from_molecules(molecule, charge_mols)[source]

Given an input molecule, checks against a list of molecules for an isomorphic match. If found, assigns partial charges from the match to the input molecule.

Parameters
  • molecule (an openff.toolkit.topology.FrozenMolecule) – The molecule to have partial charges assigned if a match is found.

  • charge_mols (list of [openff.toolkit.topology.FrozenMolecule]) – A list of molecules with charges already assigned.

Returns

match_found (bool) – Whether a match was found. If True, the input molecule will have been modified in-place.

postprocess_system(system, topology, **kwargs)[source]

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.

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

Parameters
  • attr_name (str) – Name of the attribute to define for this object.

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

add_parameter(parameter_kwargs=None, parameter=None, after=None, before=None)

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

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

  • parameter (ParameterType, optional) – 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

  • 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](https://openforcefield.github.io/standards/standards/smirnoff/#smirnoff-parameter-specification-is-hierarchical) specification.

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 openmm import unit
>>> bh = BondHandler(skip_version_check=True)
>>> length = 1.5 * unit.angstrom
>>> k = 100 * unit.kilocalorie_per_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']
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
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.

find_matches(entity, unique=False)

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

Parameters
  • entity (openff.toolkit.topology.Topology) – Topology to search.

  • unique (bool, default=False) – 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

matches (ValenceDict[Tuple[int], ParameterHandler._Match]) – matches[particle_indices] is the ParameterType object matching the tuple of particle 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 (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)  >]
property known_kwargs

List of kwargs that can be parsed by the function.

mark_charges_assigned(ref_mol, topology)

Record that charges have been assigned for a reference molecule.

Parameters
property parameters

The ParameterList that holds this ParameterHandler’s parameter objects

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.