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, **args)	Create a System for running a simulation with this potential function.
`registerImplFactory`(name, factory)	Register a new potential function that can be used with MLPotential.

createSystem(topology: Topology, **args) → System#

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

Parameters:

topology (Topology) – the Topology for which to create a 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, **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”). It returns a new System that is identical to the original one except for the following changes.

Removing all bonds, angles, and torsions for which all atoms are in the ML subset.
For every NonbondedForce and CustomNonbondedForce, adding exceptions/exclusions to prevent atoms in the ML subset from interacting with each other.
(Optional) Removing constraints between atoms that are both in the ML subset.
Adding Forces as necessary to compute the internal energy of the ML subset with this potential.

Alternatively, the System can include Forces to compute the energy both with the conventional force field and with this potential, and to smoothly interpolate between them. In that case, it creates a CustomCVForce containing the following.

The Forces to compute this potential.
Forces to compute the bonds, angles, and torsions that were removed above.
For every NonbondedForce, a corresponding CustomBondForce to compute the nonbonded interactions within the ML subset.

The CustomCVForce defines a global parameter called “lambda_interpolate” that interpolates between the two potentials. When lambda_interpolate=0, the energy is computed entirely with the conventional force field. When lambda_interpolate=1, the energy is computed entirely with the ML potential. 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
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

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