openforcefield.typing.engines.smirnoff.parameters.ParameterHandler

class openforcefield.typing.engines.smirnoff.parameters.ParameterHandler(allow_cosmetic_attributes=False, skip_version_check=False, **kwargs)[source]

Base class for parameter handlers.

Parameter handlers are configured with some global parameters for a given section. They may also contain a ParameterList populated with ParameterType objects if they are responsible for assigning SMIRKS-based parameters.

Warning

This API is experimental and subject to change.

Attributes
known_kwargs

List of kwargs that can be parsed by the function.

parameters

The ParameterList that holds this ParameterHandler’s parameter objects

version

A descriptor for ParameterType attributes.

The descriptors allows associating to the parameter a default value, which makes the attribute optional, a unit, and a custom converter.

Because we may want to have None as a default value, required attributes have the default set to the special type UNDEFINED.

Converters can be both static or instance functions/methods with respective signatures

converter(value): -> converted_value converter(instance, parameter_attribute, value): -> converted_value

A decorator syntax is available (see example below).

defaultobject, optional

When specified, the descriptor makes this attribute optional by attaching a default value to it.

unitsimtk.unit.Quantity, optional

When specified, only quantities with compatible units are allowed to be set, and string expressions are automatically parsed into a Quantity.

convertercallable, optional

An optional function that can be used to convert values before setting the attribute.

IndexedParameterAttribute

A parameter attribute with multiple terms.

Create a parameter type with an optional and a required attribute.

>>> class MyParameter:
...     attr_required = ParameterAttribute()
...     attr_optional = ParameterAttribute(default=2)
...
>>> my_par = MyParameter()

Even without explicit assignment, the default value is returned.

>>> my_par.attr_optional
2

If you try to access an attribute without setting it first, an exception is raised.

>>> my_par.attr_required
Traceback (most recent call last):
...
AttributeError: 'MyParameter' object has no attribute '_attr_required'

The attribute allow automatic conversion and validation of units.

>>> from simtk import unit
>>> class MyParameter:
...     attr_quantity = ParameterAttribute(unit=unit.angstrom)
...
>>> my_par = MyParameter()
>>> my_par.attr_quantity = '1.0 * nanometer'
>>> my_par.attr_quantity
Quantity(value=1.0, unit=nanometer)
>>> my_par.attr_quantity = 3.0
Traceback (most recent call last):
...
openforcefield.utils.utils.IncompatibleUnitError: attr_quantity=3.0 dimensionless should have units of angstrom

You can attach a custom converter to an attribute.

>>> class MyParameter:
...     # Both strings and integers convert nicely to floats with float().
...     attr_all_to_float = ParameterAttribute(converter=float)
...     attr_int_to_float = ParameterAttribute()
...     @attr_int_to_float.converter
...     def attr_int_to_float(self, attr, value):
...         # This converter converts only integers to float
...         # and raise an exception for the other types.
...         if isinstance(value, int):
...             return float(value)
...         elif not isinstance(value, float):
...             raise TypeError(f"Cannot convert '{value}' to float")
...         return value
...
>>> my_par = MyParameter()

attr_all_to_float accepts and convert to float both strings and integers

>>> my_par.attr_all_to_float = 1
>>> my_par.attr_all_to_float
1.0
>>> my_par.attr_all_to_float = '2.0'
>>> my_par.attr_all_to_float
2.0

The custom converter associated to attr_int_to_float converts only integers instead. >>> my_par.attr_int_to_float = 3 >>> my_par.attr_int_to_float 3.0 >>> my_par.attr_int_to_float = ‘4.0’ Traceback (most recent call last): … TypeError: Cannot convert ‘4.0’ to float

Methods

add_cosmetic_attribute(attr_name, attr_value)

Add a cosmetic attribute to this object.

add_parameter([parameter_kwargs, parameter, …])

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

assign_parameters(topology, system)

Assign parameters for the given Topology to the specified System object.

attribute_is_cosmetic(attr_name)

Determine whether an attribute of this object is cosmetic.

check_handler_compatibility(handler_kwargs)

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

delete_cosmetic_attribute(attr_name)

Delete a cosmetic attribute from this object.

find_matches(entity)

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.

postprocess_system(topology, system, **kwargs)

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

to_dict([discard_cosmetic_attributes])

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

__init__(allow_cosmetic_attributes=False, skip_version_check=False, **kwargs)[source]

Initialize a ParameterHandler, optionally with a list of parameters and other kwargs.

Parameters
allow_cosmetic_attributesbool, 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.

**kwargsdict

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 forcefield, ensuring all parameters are valid.

assign_parameters(topology, system)

Assign parameters for the given Topology to the specified System object.

attribute_is_cosmetic(attr_name)

Determine whether an attribute of this object is cosmetic.

check_handler_compatibility(handler_kwargs)

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

delete_cosmetic_attribute(attr_name)

Delete a cosmetic attribute from this object.

find_matches(entity)

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.

postprocess_system(topology, system, **kwargs)

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

to_dict([discard_cosmetic_attributes])

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

Attributes

known_kwargs

List of kwargs that can be parsed by the function.

parameters

The ParameterList that holds this ParameterHandler’s parameter objects

version

A descriptor for ParameterType attributes.