openforcefield.typing.engines.smirnoff.parameters.
ParameterAttribute
(default=<class 'openforcefield.typing.engines.smirnoff.parameters.ParameterAttribute.UNDEFINED'>, unit=None, converter=None)[source]¶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.
See also
IndexedParameterAttribute
A parameter attribute with multiple terms.
Examples
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
Custom type used by |
|
|
Create a new ParameterAttribute with an associated converter. |
__init__
(self, default=<class 'openforcefield.typing.engines.smirnoff.parameters.ParameterAttribute.UNDEFINED'>, unit=None, converter=None)[source]¶Initialize self. See help(type(self)) for accurate signature.
Methods
|
Initialize self. |
|
Create a new ParameterAttribute with an associated converter. |
Attributes
|