openforcefield.typing.engines.smirnoff.parameters.ProperTorsionHandler

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

Handle SMIRNOFF <ProperTorsionForce> tags

Warning

This API is experimental and subject to change.

Attributes
default_idivf

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

known_kwargs

List of kwargs that can be parsed by the function.

parameters

The ParameterList that holds this ParameterHandler’s parameter objects

potential

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

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

ProperTorsionType(smirks[, …])

A SMIRNOFF torsion type for proper torsions.

add_cosmetic_attribute(self, attr_name, …)

Add a cosmetic attribute to this object.

add_parameter(self, parameter_kwargs)

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

assign_parameters(self, topology, system)

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

check_handler_compatibility(self, other_handler)

Checks whether this ParameterHandler encodes compatible physics as another ParameterHandler.

delete_cosmetic_attribute(self, attr_name)

Delete a cosmetic attribute from this object.

find_matches(self, entity)

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

get_parameter(self, parameter_attrs)

Return the parameters in this ParameterHandler that match the parameter_attrs argument

postprocess_system(self, topology, system, …)

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

to_dict(self[, discard_cosmetic_attributes])

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

create_force

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

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

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

add_cosmetic_attribute(self, attr_name, …)

Add a cosmetic attribute to this object.

add_parameter(self, parameter_kwargs)

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

assign_parameters(self, topology, system)

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

check_handler_compatibility(self, other_handler)

Checks whether this ParameterHandler encodes compatible physics as another ParameterHandler.

create_force(self, system, topology, \*\*kwargs)

delete_cosmetic_attribute(self, attr_name)

Delete a cosmetic attribute from this object.

find_matches(self, entity)

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

get_parameter(self, parameter_attrs)

Return the parameters in this ParameterHandler that match the parameter_attrs argument

postprocess_system(self, topology, system, …)

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

to_dict(self[, discard_cosmetic_attributes])

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

Attributes

default_idivf

A descriptor for ParameterType attributes.

known_kwargs

List of kwargs that can be parsed by the function.

parameters

The ParameterList that holds this ParameterHandler’s parameter objects

potential

A descriptor for ParameterType attributes.

version

A descriptor for ParameterType attributes.

class ProperTorsionType(smirks, allow_cosmetic_attributes=False, **kwargs)[source]

A SMIRNOFF torsion type for proper torsions.

Warning

This API is experimental and subject to change.

Attributes
id

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

idivf

The attribute of a parameter with an unspecified number of terms.

Some parameters can be associated to multiple terms, For example, torsions have parameters such as k1, k2, …, and IndexedParameterAttribute can be used to encapsulate the sequence of terms.

The only substantial difference with ParameterAttribute is that only sequences are supported as values and converters and units are checked on each element of the sequence.

Currently, the descriptor makes the sequence immutable. This is to avoid that an element of the sequence could be set without being properly validated. In the future, the data could be wrapped in a safe list that would safely allow mutability.

defaultobject, optional

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

unitsimtk.unit.Quantity, optional

When specified, only sequences of quantities with compatible units are allowed to be set.

convertercallable, optional

An optional function that can be used to validate and cast each element of the sequence before setting the attribute.

ParameterAttribute

A simple parameter attribute.

Create an optional indexed attribute with unit of angstrom.

>>> from simtk import unit
>>> class MyParameter:
...     length = IndexedParameterAttribute(default=None, unit=unit.angstrom)
...
>>> my_par = MyParameter()
>>> my_par.length is None
True

Strings are parsed into Quantity objects.

>>> my_par.length = ['1 * angstrom', 0.5 * unit.nanometer]
>>> my_par.length[0]
Quantity(value=1, unit=angstrom)

Similarly, custom converters work as with ParameterAttribute, but they are used to validate each value in the sequence.

>>> class MyParameter:
...     attr_indexed = IndexedParameterAttribute(converter=float)
...
>>> my_par = MyParameter()
>>> my_par.attr_indexed = [1, '1.0', '1e-2', 4.0]
>>> my_par.attr_indexed
[1.0, 1.0, 0.01, 4.0]
k

The attribute of a parameter with an unspecified number of terms.

Some parameters can be associated to multiple terms, For example, torsions have parameters such as k1, k2, …, and IndexedParameterAttribute can be used to encapsulate the sequence of terms.

The only substantial difference with ParameterAttribute is that only sequences are supported as values and converters and units are checked on each element of the sequence.

Currently, the descriptor makes the sequence immutable. This is to avoid that an element of the sequence could be set without being properly validated. In the future, the data could be wrapped in a safe list that would safely allow mutability.

defaultobject, optional

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

unitsimtk.unit.Quantity, optional

When specified, only sequences of quantities with compatible units are allowed to be set.

convertercallable, optional

An optional function that can be used to validate and cast each element of the sequence before setting the attribute.

ParameterAttribute

A simple parameter attribute.

Create an optional indexed attribute with unit of angstrom.

>>> from simtk import unit
>>> class MyParameter:
...     length = IndexedParameterAttribute(default=None, unit=unit.angstrom)
...
>>> my_par = MyParameter()
>>> my_par.length is None
True

Strings are parsed into Quantity objects.

>>> my_par.length = ['1 * angstrom', 0.5 * unit.nanometer]
>>> my_par.length[0]
Quantity(value=1, unit=angstrom)

Similarly, custom converters work as with ParameterAttribute, but they are used to validate each value in the sequence.

>>> class MyParameter:
...     attr_indexed = IndexedParameterAttribute(converter=float)
...
>>> my_par = MyParameter()
>>> my_par.attr_indexed = [1, '1.0', '1e-2', 4.0]
>>> my_par.attr_indexed
[1.0, 1.0, 0.01, 4.0]
parent_id

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

periodicity

The attribute of a parameter with an unspecified number of terms.

Some parameters can be associated to multiple terms, For example, torsions have parameters such as k1, k2, …, and IndexedParameterAttribute can be used to encapsulate the sequence of terms.

The only substantial difference with ParameterAttribute is that only sequences are supported as values and converters and units are checked on each element of the sequence.

Currently, the descriptor makes the sequence immutable. This is to avoid that an element of the sequence could be set without being properly validated. In the future, the data could be wrapped in a safe list that would safely allow mutability.

defaultobject, optional

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

unitsimtk.unit.Quantity, optional

When specified, only sequences of quantities with compatible units are allowed to be set.

convertercallable, optional

An optional function that can be used to validate and cast each element of the sequence before setting the attribute.

ParameterAttribute

A simple parameter attribute.

Create an optional indexed attribute with unit of angstrom.

>>> from simtk import unit
>>> class MyParameter:
...     length = IndexedParameterAttribute(default=None, unit=unit.angstrom)
...
>>> my_par = MyParameter()
>>> my_par.length is None
True

Strings are parsed into Quantity objects.

>>> my_par.length = ['1 * angstrom', 0.5 * unit.nanometer]
>>> my_par.length[0]
Quantity(value=1, unit=angstrom)

Similarly, custom converters work as with ParameterAttribute, but they are used to validate each value in the sequence.

>>> class MyParameter:
...     attr_indexed = IndexedParameterAttribute(converter=float)
...
>>> my_par = MyParameter()
>>> my_par.attr_indexed = [1, '1.0', '1e-2', 4.0]
>>> my_par.attr_indexed
[1.0, 1.0, 0.01, 4.0]
phase

The attribute of a parameter with an unspecified number of terms.

Some parameters can be associated to multiple terms, For example, torsions have parameters such as k1, k2, …, and IndexedParameterAttribute can be used to encapsulate the sequence of terms.

The only substantial difference with ParameterAttribute is that only sequences are supported as values and converters and units are checked on each element of the sequence.

Currently, the descriptor makes the sequence immutable. This is to avoid that an element of the sequence could be set without being properly validated. In the future, the data could be wrapped in a safe list that would safely allow mutability.

defaultobject, optional

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

unitsimtk.unit.Quantity, optional

When specified, only sequences of quantities with compatible units are allowed to be set.

convertercallable, optional

An optional function that can be used to validate and cast each element of the sequence before setting the attribute.

ParameterAttribute

A simple parameter attribute.

Create an optional indexed attribute with unit of angstrom.

>>> from simtk import unit
>>> class MyParameter:
...     length = IndexedParameterAttribute(default=None, unit=unit.angstrom)
...
>>> my_par = MyParameter()
>>> my_par.length is None
True

Strings are parsed into Quantity objects.

>>> my_par.length = ['1 * angstrom', 0.5 * unit.nanometer]
>>> my_par.length[0]
Quantity(value=1, unit=angstrom)

Similarly, custom converters work as with ParameterAttribute, but they are used to validate each value in the sequence.

>>> class MyParameter:
...     attr_indexed = IndexedParameterAttribute(converter=float)
...
>>> my_par = MyParameter()
>>> my_par.attr_indexed = [1, '1.0', '1e-2', 4.0]
>>> my_par.attr_indexed
[1.0, 1.0, 0.01, 4.0]
smirks

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(self, attr_name, …)

Add a cosmetic attribute to this object.

delete_cosmetic_attribute(self, attr_name)

Delete a cosmetic attribute from this object.

to_dict(self[, discard_cosmetic_attributes])

Convert this object to dict format.

add_cosmetic_attribute(self, 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_namestr

Name of the attribute to define for this object.

attr_valuestr

The value of the attribute to define for this object.

delete_cosmetic_attribute(self, 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_namestr

Name of the cosmetic attribute to delete.

to_dict(self, discard_cosmetic_attributes=False)

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_attributesbool, optional. Default = False

Whether to discard non-spec attributes of this object

Returns
smirnoff_dictdict

The SMIRNOFF-compliant dict representation of this object.

check_handler_compatibility(self, 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_handlera ParameterHandler object

The handler to compare to.

Raises
IncompatibleParameterError if handler_kwargs are incompatible with existing parameters.
add_cosmetic_attribute(self, 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_namestr

Name of the attribute to define for this object.

attr_valuestr

The value of the attribute to define for this object.

add_parameter(self, parameter_kwargs)

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

Parameters
parameter_kwargsdict

The kwargs to pass to the ParameterHandler.INFOTYPE (a ParameterType) constructor

assign_parameters(self, topology, system)

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

Parameters
topologyopenforcefield.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.

systemsimtk.openmm.System

The OpenMM System object to add the Force (or append new parameters) to.

delete_cosmetic_attribute(self, 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_namestr

Name of the cosmetic attribute to delete.

find_matches(self, entity)

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

Parameters
entityopenforcefield.topology.Topology

Topology to search.

Returns
matchesValenceDict[Tuple[int], ParameterHandler._Match]

matches[particle_indices] is the ParameterType object matching the tuple of particle indices in entity.

get_parameter(self, parameter_attrs)

Return the parameters in this ParameterHandler that match the parameter_attrs argument

Parameters
parameter_attrsdict of {attr: value}

The attrs mapped to desired values (for example {“smirks”: “[:1]~[#16:2]=,:[#6:3]~[:4]”, “id”: “t105”} )

Returns
list of ParameterType objects

A list of matching ParameterType objects

property known_kwargs

List of kwargs that can be parsed by the function.

property parameters

The ParameterList that holds this ParameterHandler’s parameter objects

postprocess_system(self, topology, system, **kwargs)

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

Parameters
topologyopenforcefield.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.

systemsimtk.openmm.System

The OpenMM System object to add the Force (or append new parameters) to.

to_dict(self, discard_cosmetic_attributes=False)

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

Parameters
discard_cosmetic_attributesbool, optional. Default = False.

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

Returns
smirnoff_dataOrderedDict

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