# openforcefield.typing.engines.smirnoff.parameters.ParameterHandler

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

  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`(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.
  `attribute_is_cosmetic`(self, attr_name) | Determine whether an attribute of this object is cosmetic.
  `check_handler_compatibility`(self, handler_kwargs) | Checks if a set of kwargs used to create a ParameterHandler are compatible with this 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.

  `__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_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__`(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.
  `attribute_is_cosmetic`(self, attr_name) | Determine whether an attribute of this object is cosmetic.
  `check_handler_compatibility`(self, handler_kwargs) | Checks if a set of kwargs used to create a ParameterHandler are compatible with this 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.

  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.