openmmml.MLPotential#

class openmmml.MLPotential(name: str, **args)#

A potential function that can be used in simulations.

To use this class, create a MLPotential, specifying the name of the potential function to use. You can then call createSystem() to create a System object for a simulation. For example,

>>> potential = MLPotential('ani2x')
>>> system = potential.createSystem(topology)

Alternatively, you can use createMixedSystem() to create a System where part is modeled with this potential and the rest is modeled with a conventional force field. As an example, suppose the Topology contains three chains. Chain 0 is a protein, chain 1 is a ligand, and chain 2 is solvent. The following code creates a System in which the internal energy of the ligand is computed with ANI2x, while everything else (including interactions between the ligand and the rest of the System) is computed with Amber14.

>>> forcefield = ForceField('amber14-all.xml', 'amber14/tip3pfb.xml')
>>> mm_system = forcefield.createSystem(topology)
>>> chains = list(topology.chains())
>>> ml_atoms = [atom.index for atom in chains[1].atoms()]
>>> potential = MLPotential('ani2x')
>>> ml_system = potential.createMixedSystem(topology, mm_system, ml_atoms)

__init__(name: str, **args)#

Create a MLPotential.

Parameters:

name (str) – the name of the potential function to use. Built in support is currently provided for the following: ‘ani1ccx’, ‘ani2x’. Others may be added by calling MLPotential.registerImplFactory().
args – particular potential functions may define additional arguments that can be used to customize them. See the documentation on the specific potential functions for more information.

Methods

`__init__`(name, **args)	Create a MLPotential.
`createMixedSystem`(topology, system, atoms[, ...])	Create a System that is partly modeled with this potential and partly with a conventional force field.
`createSystem`(topology[, removeCMMotion])	Create a System for running a simulation with this potential function.
`getSupportedEmbeddings`()	Retrieves a list of the names of all of the supported embedding methods for this potential.
`registerEmbeddingFactory`(name, factory)	Register a new embedding method that can be used with MLPotential.
`registerImplFactory`(name, factory)	Register a new potential function that can be used with MLPotential.

createSystem(topology: Topology, removeCMMotion: bool = True, **args) → System#

Create a System for running a simulation with this potential function.

Parameters:

topology (Topology) – the Topology for which to create a System
removeCMMotion (bool) – if true, a CMMotionRemover will be added to the System.
args – particular potential functions may define additional arguments that can be used to customize them. See the documentation on the specific potential functions for more information.

Return type:

a newly created System object that uses this potential function to model the Topology

createMixedSystem(topology: Topology, system: System, atoms: Iterable[int], removeConstraints: bool = True, forceGroup: int = 0, interpolate: bool = False, embedding: str = 'mechanical', **args) → System#

Create a System that is partly modeled with this potential and partly with a conventional force field.

To use this method, first create a System that is entirely modeled with the conventional force field. Pass it to this method, along with the indices of the atoms to model with this potential (the “ML subset”).

If interpolate is False, the resulting system will compute the interactions between atoms outside of the ML subset with the conventional force field, the interactions between atoms within the ML subset with the ML potential, and the interactions between atoms within and outside of the ML subset according to a selectable embedding method.

If interpolate is True, a global parameter “lambda_interpolate” will be made available permitting linear interpolation between the conventional force field and the mixed ML/MM system. When lambda_interpolate=0, the energy is computed entirely with the conventional force field. When lambda_interpolate=1, the energy is computed with the ML potential and the selected embedding method. You can set its value by calling setParameter() on the Context.

Parameters:

topology (Topology) – the Topology for which to create a System
system (System) – a System that models the Topology with a conventional force field
atoms (Iterable[int]) – the indices of all atoms whose interactions should be computed with this potential
removeConstraints (bool) – if True, remove constraints between pairs of atoms whose interaction will be computed with this potential
forceGroup (int) – the force group the ML potential’s Forces should be placed in
interpolate (bool) – if True, create a System that can smoothly interpolate between the conventional and ML potentials
embedding (str) – the name of the embedding method. The builtin ‘mechanical’ embedding method is used by default. Other generic embedding methods may be available, as well as embedding methods specific to the ML potential selected. MLPotential.getSupportedEmbeddings() will report all embedding methods accepted by the potential.
args – particular potential functions or embedding methods may define additional arguments that can be used to customize them. See the documentation on the specific potential functions and embedding methods for more information.

Return type:

a newly created System object that uses this potential function to model the Topology

getSupportedEmbeddings() → list[str]#: Retrieves a list of the names of all of the supported embedding methods for this potential. This includes all available generic embedding methods and all of those specific to the potential.

static registerImplFactory(name: str, factory: MLPotentialImplFactory)#

Parameters:

name (str) – the name of the potential function that will be passed to the MLPotential constructor
factory (MLPotentialImplFactory) – a factory object that will be used to create MLPotentialImpl objects

static registerEmbeddingFactory(name: str, factory: EmbeddingFactory)#

Parameters:

name (str) – the name of the embedding method to register for use
factory (MLPotentialImplFactory) – a factory object that will be used to create Embedding objects