openforcefield.typing.engines.smirnoff.parameters.ImproperTorsionHandler.
ImproperTorsionType
(smirks, allow_cosmetic_attributes=False, **kwargs)¶A SMIRNOFF torsion type for improper torsions.
Warning
This API is experimental and subject to change.
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).
When specified, the descriptor makes this attribute optional by attaching a default value to it.
When specified, only quantities with compatible units are allowed
to be set, and string expressions are automatically parsed into a
Quantity
.
An optional function that can be used to convert values before setting the attribute.
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
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.
When specified, the descriptor makes this attribute optional by attaching a default value to it.
When specified, only sequences of quantities with compatible units are allowed to be set.
An optional function that can be used to validate and cast each element of the sequence before setting the attribute.
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]
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.
When specified, the descriptor makes this attribute optional by attaching a default value to it.
When specified, only sequences of quantities with compatible units are allowed to be set.
An optional function that can be used to validate and cast each element of the sequence before setting the attribute.
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]
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).
When specified, the descriptor makes this attribute optional by attaching a default value to it.
When specified, only quantities with compatible units are allowed
to be set, and string expressions are automatically parsed into a
Quantity
.
An optional function that can be used to convert values before setting the attribute.
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
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.
When specified, the descriptor makes this attribute optional by attaching a default value to it.
When specified, only sequences of quantities with compatible units are allowed to be set.
An optional function that can be used to validate and cast each element of the sequence before setting the attribute.
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]
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.
When specified, the descriptor makes this attribute optional by attaching a default value to it.
When specified, only sequences of quantities with compatible units are allowed to be set.
An optional function that can be used to validate and cast each element of the sequence before setting the attribute.
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]
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).
When specified, the descriptor makes this attribute optional by attaching a default value to it.
When specified, only quantities with compatible units are allowed
to be set, and string expressions are automatically parsed into a
Quantity
.
An optional function that can be used to convert values before setting the attribute.
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 a cosmetic attribute to this object. |
|
Determine whether an attribute of this object is cosmetic. |
|
Delete a cosmetic attribute from this object. |
|
Convert this object to dict format. |
__init__
(self, smirks, allow_cosmetic_attributes=False, **kwargs)¶Create a ParameterType.
The SMIRKS match for the provided parameter type.
Whether to permit non-spec kwargs (“cosmetic attributes”). If True, non-spec kwargs will be stored as an attribute of this parameter which can be accessed and written out. Otherwise an exception will be raised.
Methods
|
Create a ParameterType. |
|
Add a cosmetic attribute to this object. |
|
Determine whether an attribute of this object is cosmetic. |
|
Delete a cosmetic attribute from this object. |
|
Convert this object to dict format. |
Attributes
|
A descriptor for |
|
The attribute of a parameter with an unspecified number of terms. |
|
The attribute of a parameter with an unspecified number of terms. |
|
A descriptor for |
|
The attribute of a parameter with an unspecified number of terms. |
|
The attribute of a parameter with an unspecified number of terms. |
|
A descriptor for |
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).
Name of the attribute to define for this object.
The value of the attribute to define for this object.
attribute_is_cosmetic
(self, 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).
The attribute name to check
Returns True if the attribute is defined and is cosmetic. Returns False otherwise.
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).
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
.
Whether to discard non-spec attributes of this object
The SMIRNOFF-compliant dict representation of this object.