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)[source]¶

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('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_handler('Electrostatics').method = 'PME'

Inspect the first few vdW parameters:

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

Retrieve the vdW parameters by SMIRKS string and manipulate it:

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

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

>>> forcefield.get_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_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_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:

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.

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`(topology, **kwargs)	Create an OpenMM System representing the interactions for the specified Topology with the current force field
`create_parmed_structure`(topology, positions, …)	Create a ParmEd Structure object representing the interactions for the specified Topology with the current force field
`get_handler`(tagname[, handler_kwargs])	Retrieve the parameter handlers associated with the provided tagname.
`get_io_handler`(io_format)	Retrieve the parameter handlers associated with the provided tagname.
`label_molecules`(topology)	Return labels for a list of molecules corresponding to parameters from this force field.
`load_smirnoff_data`(smirnoff_data)	Add parameters from a SMIRNOFF-format data structure to this ForceField.
`parse_smirnoff_from_source`(source)	Reads a SMIRNOFF data structure from a source, which can be one of many types.
`parse_sources`(sources)	Parse a SMIRNOFF force field definition.
`register_parameter_handler`(…)	Register a new ParameterHandler from a specified class, instantiating the ParameterHandler object and making it available for lookup in the ForceField.
`register_parameter_io_handler`(…)	Register a new ParameterIOHandler from a specified class, instantiating the ParameterIOHandler object and making it available for lookup in the ForceField.
`to_smirnoff_data`()	Convert this ForceField and all related ParameterHandlers to an OrderedDict representing a SMIRNOFF data object.

__init__(*sources, parameter_handler_classes=None, parameter_io_handler_classes=None, disable_version_check=False)[source]¶

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

Parameters:

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.

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.

Examples

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

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

Load multiple SMIRNOFF parameter sets:

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

Load a parameter set from a string:

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

Methods

`__init__`(*sources[, …])	Create a new `ForceField` object from one or more SMIRNOFF parameter definition files.
`create_openmm_system`(topology, **kwargs)	Create an OpenMM System representing the interactions for the specified Topology with the current force field
`create_parmed_structure`(topology, positions, …)	Create a ParmEd Structure object representing the interactions for the specified Topology with the current force field
`get_handler`(tagname[, handler_kwargs])	Retrieve the parameter handlers associated with the provided tagname.
`get_io_handler`(io_format)	Retrieve the parameter handlers associated with the provided tagname.
`label_molecules`(topology)	Return labels for a list of molecules corresponding to parameters from this force field.
`load_smirnoff_data`(smirnoff_data)	Add parameters from a SMIRNOFF-format data structure to this ForceField.
`parse_smirnoff_from_source`(source)	Reads a SMIRNOFF data structure from a source, which can be one of many types.
`parse_sources`(sources)	Parse a SMIRNOFF force field definition.
`register_parameter_handler`(…)	Register a new ParameterHandler from a specified class, instantiating the ParameterHandler object and making it available for lookup in the ForceField.
`register_parameter_io_handler`(…)	Register a new ParameterIOHandler from a specified class, instantiating the ParameterIOHandler object and making it available for lookup in the ForceField.
`to_smirnoff_data`()	Convert this ForceField and all related ParameterHandlers to an OrderedDict representing a SMIRNOFF data object.

register_parameter_handler(parameter_handler_class, parameter_handler_kwargs)[source]¶

Register a new ParameterHandler from a specified class, instantiating the ParameterHandler object and making it available for lookup in the ForceField.

Warning

This API is experimental and subject to change.

Parameters:	parameter_handler_class : A ParameterHandler-derived object The ParameterHandler to register
Returns:	new_handler : an openforcefield.engines.typing.smirnoff.ParameterHandler-derived object. The newly-created ParameterHandler

register_parameter_io_handler(parameter_io_handler_class)[source]¶

Register a new ParameterIOHandler from a specified class, instantiating the ParameterIOHandler object and making it available for lookup in the ForceField.

Warning

This API is experimental and subject to change.

Parameters:	parameter_io_handler_class : A subclass of ParameterIOHandler

get_handler(tagname, handler_kwargs=None)[source]¶

Retrieve the parameter handlers associated with the provided tagname.

If the parameter handler has not yet been instantiated, it will be created. 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.

Parameters:	tagame : 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 None, will be assumed to represent handler defaults.
Returns:	handler : An openforcefield.engines.typing.smirnoff.ParameterHandler
Raises:	KeyError if there is no ParameterHandler for the given tagname

get_io_handler(io_format)[source]¶

Retrieve the parameter handlers associated with the provided tagname.

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(sources)[source]¶

Parse a SMIRNOFF force field definition.

Parameters:

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

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.

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

to_smirnoff_data()[source]¶

Convert this ForceField and all related ParameterHandlers to an OrderedDict representing a SMIRNOFF data object.

Returns:	smirnoff_dict : OrderedDict A nested OrderedDict representing this ForceField as a SMIRNOFF data object.

load_smirnoff_data(smirnoff_data)[source]¶

Add parameters from a SMIRNOFF-format data structure to this ForceField.

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

parse_smirnoff_from_source(source)[source]¶

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

Parameters:

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.

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.

create_openmm_system(topology, **kwargs)[source]¶

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
Returns:	system : simtk.openmm.System The newly created OpenMM System corresponding to the specified `topology`

create_parmed_structure(topology, positions, **kwargs)[source]¶

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(topology)[source]¶

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:

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), ... ]`. .. todo :: What is the most useful API for this method? Should we instead accept `Molecule` objects as input and individually return labels? Should we attach the labels to the `Molecule` object? Or should we label all interactions in a `Topology` instead of just labeling its `unique_molecules`?

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), ... ].
.. todo ::: What is the most useful API for this method? Should we instead accept Molecule objects as input and individually return labels? Should we attach the labels to the Molecule object? Or should we label all interactions in a Topology instead of just labeling its unique_molecules?