# openforcefield.typing.engines.smirnoff.forcefield.ForceField

class `openforcefield.typing.engines.smirnoff.forcefield.``ForceField`(*sources, parameter_handler_classes=None, parameter_io_handler_classes=None, disable_version_check=False, allow_cosmetic_attributes=False)

  A factory that assigns SMIRNOFF parameters to a molecular system

  `ForceField` is a factory that constructs an OpenMM `simtk.openmm.System` object from a `openforcefield.topology.Topology` object defining a (bio)molecular system containing one or more molecules.

  When a `ForceField` object is created from one or more specified SMIRNOFF serialized representations, all `ParameterHandler` subclasses currently imported are identified and registered to handle different sections of the SMIRNOFF force field definition file(s).

  All `ParameterIOHandler` subclasses currently imported are identified and registered to handle different serialization formats (such as XML).

  The force field definition is processed by these handlers to populate the `ForceField` object model data structures that can easily be manipulated via the API:

  Processing a `Topology` object defining a chemical system will then call all :class`ParameterHandler` objects in an order guaranteed to satisfy the declared processing order constraints of each :class`ParameterHandler`.

  Examples

  Create a new ForceField containing the smirnoff99Frosst parameter set:

      >>> from openforcefield.typing.engines.smirnoff import ForceField
      >>> forcefield = ForceField('test_forcefields/smirnoff99Frosst.offxml')

  Create an OpenMM system from a `openforcefield.topology.Topology` object:

      >>> from openforcefield.topology import Molecule, Topology
      >>> ethanol = Molecule.from_smiles('CCO')
      >>> topology = Topology.from_molecules(molecules=[ethanol])
      >>> system = forcefield.create_openmm_system(topology)

  Modify the long-range electrostatics method:

      >>> forcefield.get_parameter_handler('Electrostatics').method = 'PME'

  Inspect the first few vdW parameters:

      >>> low_precedence_parameters = forcefield.get_parameter_handler('vdW').parameters[0:3]

  Retrieve the vdW parameters by SMIRKS string and manipulate it:

      >>> parameter = forcefield.get_parameter_handler('vdW').parameters['[#1:1]-[#7]']
      >>> parameter.rmin_half += 0.1 * unit.angstroms
      >>> parameter.epsilon *= 1.02

  Make a child vdW type more specific (checking modified SMIRKS for validity):

      >>> forcefield.get_parameter_handler('vdW').parameters[-1].smirks += '~[#53]'

  Warning

  While we check whether the modified SMIRKS is still valid and has the appropriate valence type, we currently don’t check whether the typing remains hierarchical, which could result in some types no longer being assignable because more general types now come below them and preferentially match.

  Delete a parameter:

      >>> del forcefield.get_parameter_handler('vdW').parameters['[#1:1]-[#6X4]']

  Insert a parameter at a specific point in the parameter tree:

      >>> from openforcefield.typing.engines.smirnoff import vdWHandler
      >>> new_parameter = vdWHandler.vdWType(smirks='[*:1]', epsilon=0.0157*unit.kilocalories_per_mole, rmin_half=0.6000*unit.angstroms)
      >>> forcefield.get_parameter_handler('vdW').parameters.insert(0, new_parameter)

  Warning

  We currently don’t check whether removing a parameter could accidentally remove the root type, so it’s possible to no longer type all molecules this way.

  Attributes
    parameters dict of str

      `parameters[tagname]` is the instantiated `ParameterHandler` class that handles parameters associated with the force `tagname`. This is the primary means of retrieving and modifying parameters, such as `parameters['vdW'][0].sigma *= 1.1`

    parameter_object_handlers dict of str

      Registered list of `ParameterHandler` classes that will handle different forcefield tags to create the parameter object model. `parameter_object_handlers[tagname]` is the `ParameterHandler` that will be instantiated to process the force field definition section `tagname`. `ParameterHandler` classes are registered when the ForceField object is created, but can be manipulated afterwards.

    parameter_io_handlers dict of str

      Registered list of `ParameterIOHandler` classes that will handle serializing/deserializing the parameter object model to string or file representations, such as XML. `parameter_io_handlers[iotype]` is the `ParameterHandler` that will be instantiated to process the serialization scheme `iotype`. `ParameterIOHandler` classes are registered when the ForceField object is created, but can be manipulated afterwards.

  Methods

  `create_openmm_system`(self, topology, \*\*kwargs) | Create an OpenMM System representing the interactions for the specified Topology with the current force field
  `create_parmed_structure`(self, topology, …) | Create a ParmEd Structure object representing the interactions for the specified Topology with the current force field
  `get_parameter_handler`(self, tagname[, …]) | Retrieve the parameter handlers associated with the provided tagname.
  `get_parameter_io_handler`(self, io_format) | Retrieve the parameter handlers associated with the provided tagname.
  `label_molecules`(self, topology) | Return labels for a list of molecules corresponding to parameters from this force field.
  `parse_smirnoff_from_source`(self, source) | Reads a SMIRNOFF data structure from a source, which can be one of many types.
  `parse_sources`(self, sources[, …]) | Parse a SMIRNOFF force field definition.
  `register_parameter_handler`(self, …) | Register a new ParameterHandler for a specific tag, making it available for lookup in the ForceField.
  `register_parameter_io_handler`(self, …) | Register a new ParameterIOHandler, making it available for lookup in the ForceField.
  `to_file`(self, filename[, io_format, …]) | Write this Forcefield and all its associated parameters to a string in a given format which complies with the SMIRNOFF spec.
  `to_string`(self[, io_format, …]) | Write this Forcefield and all its associated parameters to a string in a given format which complies with the SMIRNOFF spec.

  `__init__`(self, *sources, parameter_handler_classes=None, parameter_io_handler_classes=None, disable_version_check=False, allow_cosmetic_attributes=False)

    Create a new `ForceField` object from one or more SMIRNOFF parameter definition files.

    Parameters
      sources string or file-like object or open file handle or URL (or iterable of these)

        A list of files defining the SMIRNOFF force field to be loaded. Currently, only the SMIRNOFF XML format is supported. Each entry may be an absolute file path, a path relative to the current working directory, a path relative to this module’s data subdirectory (for built in force fields), or an open file-like object with a `read()` method from which the forcefield XML data can be loaded. If multiple files are specified, any top-level tags that are repeated will be merged if they are compatible, with files appearing later in the sequence resulting in parameters that have higher precedence. Support for multiple files is primarily intended to allow solvent parameters to be specified by listing them last in the sequence.

      parameter_handler_classes iterable of ParameterHandler classes, optional, default=None

        If not None, the specified set of ParameterHandler classes will be instantiated to create the parameter object model. By default, all imported subclasses of ParameterHandler are automatically registered.

      parameter_io_handler_classes iterable of ParameterIOHandler classes

        If not None, the specified set of ParameterIOHandler classes will be used to parse/generate serialized parameter sets. By default, all imported subclasses of ParameterIOHandler are automatically registered.

      disable_version_check bool, optional, default=False

        If True, will disable checks against the current highest supported forcefield version. This option is primarily intended for forcefield development.

      allow_cosmetic_attributes bool, optional. Default = False

        Whether to retain non-spec kwargs from data sources.

    Examples

    Load one SMIRNOFF parameter set in XML format (searching the package data directory by default, which includes some standard parameter sets):

        >>> forcefield = ForceField('test_forcefields/smirnoff99Frosst.offxml')

    Load multiple SMIRNOFF parameter sets:

    forcefield = ForceField(‘test_forcefields/smirnoff99Frosst.offxml’, ‘test_forcefields/tip3p.offxml’)

    Load a parameter set from a string:

        >>> offxml = '<SMIRNOFF version="0.2" aromaticity_model="OEAroModel_MDL"/>'
        >>> forcefield = ForceField(offxml)

  Methods

  `__init__`(self, \*sources[, …]) | Create a new `ForceField` object from one or more SMIRNOFF parameter definition files.
  `create_openmm_system`(self, topology, \*\*kwargs) | Create an OpenMM System representing the interactions for the specified Topology with the current force field
  `create_parmed_structure`(self, topology, …) | Create a ParmEd Structure object representing the interactions for the specified Topology with the current force field
  `get_parameter_handler`(self, tagname[, …]) | Retrieve the parameter handlers associated with the provided tagname.
  `get_parameter_io_handler`(self, io_format) | Retrieve the parameter handlers associated with the provided tagname.
  `label_molecules`(self, topology) | Return labels for a list of molecules corresponding to parameters from this force field.
  `parse_smirnoff_from_source`(self, source) | Reads a SMIRNOFF data structure from a source, which can be one of many types.
  `parse_sources`(self, sources[, …]) | Parse a SMIRNOFF force field definition.
  `register_parameter_handler`(self, …) | Register a new ParameterHandler for a specific tag, making it available for lookup in the ForceField.
  `register_parameter_io_handler`(self, …) | Register a new ParameterIOHandler, making it available for lookup in the ForceField.
  `to_file`(self, filename[, io_format, …]) | Write this Forcefield and all its associated parameters to a string in a given format which complies with the SMIRNOFF spec.
  `to_string`(self[, io_format, …]) | Write this Forcefield and all its associated parameters to a string in a given format which complies with the SMIRNOFF spec.

  Attributes

  `author` | Returns the author data for this ForceField object.
  `date` | Returns the date data for this ForceField object.

  property `author`

    Returns the author data for this ForceField object. If not defined in any loaded files, this will be None.

    Returns
      author str

        The author data for this forcefield.

  property `date`

    Returns the date data for this ForceField object. If not defined in any loaded files, this will be None.

    Returns
      date str

        The date data for this forcefield.

  `register_parameter_handler`(self, parameter_handler)

    Register a new ParameterHandler for a specific tag, making it available for lookup in the ForceField.

    Warning

    This API is experimental and subject to change.

    Parameters
      parameter_handler A ParameterHandler object

        The ParameterHandler to register. The TAGNAME attribute of this object will be used as the key for registration.

  `register_parameter_io_handler`(self, parameter_io_handler)

    Register a new ParameterIOHandler, making it available for lookup in the ForceField.

    Warning

    This API is experimental and subject to change.

    Parameters
      parameter_io_handler A ParameterIOHandler object

        The ParameterIOHandler to register. The FORMAT attribute of this object will be used to associate it to a file format/suffix.

  `get_parameter_handler`(self, tagname, handler_kwargs=None, allow_cosmetic_attributes=False)

    Retrieve the parameter handlers associated with the provided tagname.

    If the parameter handler has not yet been instantiated, it will be created and returned. If a parameter handler object already exists, it will be checked for compatibility and an Exception raised if it is incompatible with the provided kwargs. If compatible, the existing ParameterHandler will be returned.

    Parameters
      tagname str

        The name of the parameter to be handled.

      handler_kwargs dict, optional. Default = None

        Dict to be passed to the handler for construction or checking compatibility. If this is None and no existing ParameterHandler exists for the desired tag, a handler will be initialized with all default values. If this is None and a handler for the desired tag exists, the existing ParameterHandler will be returned.

      allow_cosmetic_attributes bool, optional. Default = False

        Whether to permit non-spec kwargs in smirnoff_data.

    Returns
      handler An openforcefield.engines.typing.smirnoff.ParameterHandler
    Raises
      KeyError if there is no ParameterHandler for the given tagname
  `get_parameter_io_handler`(self, io_format)

    Retrieve the parameter handlers associated with the provided tagname. If the parameter IO handler has not yet been instantiated, it will be created.

    Parameters
      io_format str

        The name of the io format to be handled.

    Returns
      io_handler An openforcefield.engines.typing.smirnoff.ParameterIOHandler
    Raises
      KeyError if there is no ParameterIOHandler for the given tagname
  `parse_sources`(self, sources, allow_cosmetic_attributes=True)

    Parse a SMIRNOFF force field definition.

    Parameters
      sources string or file-like object or open file handle or URL (or iterable of these)

        A list of files defining the SMIRNOFF force field to be loaded. Currently, only the SMIRNOFF XML format is supported. Each entry may be an absolute file path, a path relative to the current working directory, a path relative to this module’s data subdirectory (for built in force fields), or an open file-like object with a `read()` method from which the forcefield XML data can be loaded. If multiple files are specified, any top-level tags that are repeated will be merged if they are compatible, with files appearing later in the sequence resulting in parameters that have higher precedence. Support for multiple files is primarily intended to allow solvent parameters to be specified by listing them last in the sequence.

      allow_cosmetic_attributes bool, optional. Default = False

        Whether to permit non-spec kwargs present in the source.

      .. notes ::

        - New SMIRNOFF sections are handled independently, as if they were specified in the same file.

        - If a SMIRNOFF section that has already been read appears again, its definitions are appended to the end of the previously-read definitions if the sections are configured with compatible attributes; otherwise, an `IncompatibleTagException` is raised.

  `parse_smirnoff_from_source`(self, source)

    Reads a SMIRNOFF data structure from a source, which can be one of many types.

    Parameters
      source str or bytes

        sources : string or file-like object or open file handle or URL (or iterable of these) A list of files defining the SMIRNOFF force field to be loaded Currently, only the SMIRNOFF XML format is supported. Each entry may be an absolute file path, a path relative to the current working directory, a path relative to this module’s data subdirectory (for built in force fields), or an open file-like object with a `read()` method from which the forcefield XML data can be loaded.

    Returns
      smirnoff_data OrderedDict

        A representation of a SMIRNOFF-format data structure. Begins at top-level ‘SMIRNOFF’ key.

  `to_string`(self, io_format='XML', discard_cosmetic_attributes=False)

    Write this Forcefield and all its associated parameters to a string in a given format which complies with the SMIRNOFF spec.

    Parameters
      io_format str or ParameterIOHandler, optional. Default=’XML’

        The serialization format to write to

      discard_cosmetic_attributes bool, default=False

        Whether to discard any non-spec attributes stored in the ForceField.

    Returns
      forcefield_string str

        The string representation of the serialized forcefield

  `to_file`(self, filename, io_format=None, discard_cosmetic_attributes=False)

    Write this Forcefield and all its associated parameters to a string in a given format which complies with the SMIRNOFF spec.

    Parameters
      filename str

        The filename to write to

      io_format str or ParameterIOHandler, optional. Default=None

        The serialization format to write out. If None, will attempt to be inferred from the filename.

      discard_cosmetic_attributes bool, default=False

        Whether to discard any non-spec attributes stored in the ForceField.

    Returns
      forcefield_string str

        The string representation of the serialized forcefield

  `create_openmm_system`(self, topology, **kwargs)

    Create an OpenMM System representing the interactions for the specified Topology with the current force field

    Parameters
      topology openforcefield.topology.Topology

        The `Topology` corresponding to the system to be parameterized

      charge_from_molecules List[openforcefield.molecule.Molecule], optional

        If specified, partial charges will be taken from the given molecules instead of being determined by the force field.

    Returns
      system simtk.openmm.System

        The newly created OpenMM System corresponding to the specified `topology`

  `create_parmed_structure`(self, topology, positions, **kwargs)

    Create a ParmEd Structure object representing the interactions for the specified Topology with the current force field

    This method creates a ParmEd `Structure` object containing a topology, positions, and parameters.

    Parameters
      topology openforcefield.topology.Topology

        The `Topology` corresponding to the `System` object to be created.

      positions simtk.unit.Quantity of dimension (natoms,3) with units compatible with angstroms

        The positions corresponding to the `System` object to be created

    Returns
      structure parmed.Structure

        The newly created `parmed.Structure` object

  `label_molecules`(self, topology)

    Return labels for a list of molecules corresponding to parameters from this force field. For each molecule, a dictionary of force types is returned, and for each force type, each force term is provided with the atoms involved, the parameter id assigned, and the corresponding SMIRKS.

    Parameters
      topology openforcefield.topology.Topology

        A Topology object containing one or more unique molecules to be labeled

    Returns
      molecule_labels list

        List of labels for unique molecules. Each entry in the list corresponds to one unique molecule in the Topology and is a dictionary keyed by force type, i.e., `molecule_labels[0]['HarmonicBondForce']` gives details for the harmonic bond parameters for the first molecule. Each element is a list of the form: `[ ( [ atom1, ..., atomN], parameter_id, SMIRKS), ... ]`.