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, load_plugins=False)[source]¶ A factory that assigns SMIRNOFF parameters to a molecular system
ForceField
is a factory that constructs an OpenMMsimtk.openmm.System
object from aopenforcefield.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, allParameterHandler
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
- parametersdict of str
parameters[tagname]
is the instantiatedParameterHandler
class that handles parameters associated with the forcetagname
. This is the primary means of retrieving and modifying parameters, such asparameters['vdW'][0].sigma *= 1.1
- parameter_object_handlersdict of str
Registered list of
ParameterHandler
classes that will handle different forcefield tags to create the parameter object model.parameter_object_handlers[tagname]
is theParameterHandler
that will be instantiated to process the force field definition sectiontagname
.ParameterHandler
classes are registered when the ForceField object is created, but can be manipulated afterwards.- parameter_io_handlersdict 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 theParameterHandler
that will be instantiated to process the serialization schemeiotype
.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_parameter_handler
(tagname[, …])Retrieve the parameter handlers associated with the provided tagname.
get_parameter_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.
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
(parameter_handler)Register a new ParameterHandler for a specific tag, making it available for lookup in the ForceField.
register_parameter_io_handler
(…)Register a new ParameterIOHandler, making it available for lookup in the ForceField.
to_file
(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
([io_format, …])Write this Forcefield and all its associated parameters to a string in a given format which complies with the SMIRNOFF spec.
-
__init__
(*sources, parameter_handler_classes=None, parameter_io_handler_classes=None, disable_version_check=False, allow_cosmetic_attributes=False, load_plugins=False)[source]¶ Create a new
ForceField
object from one or more SMIRNOFF parameter definition files.- Parameters
- sourcesstring 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_classesiterable 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_classesiterable 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_checkbool, 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_attributesbool, optional. Default = False
Whether to retain non-spec kwargs from data sources.
- load_plugins: bool, optional. Default = False
Whether to load
ParameterHandler
classes which have been registered by installed plugins.
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__
(*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_parameter_handler
(tagname[, …])Retrieve the parameter handlers associated with the provided tagname.
get_parameter_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.
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
(parameter_handler)Register a new ParameterHandler for a specific tag, making it available for lookup in the ForceField.
register_parameter_io_handler
(…)Register a new ParameterIOHandler, making it available for lookup in the ForceField.
to_file
(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
([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.