openmmml.models.torchmdnetpotential.TorchMDNetPotentialImpl#

class openmmml.models.torchmdnetpotential.TorchMDNetPotentialImpl(name: str, modelPath: str, lengthScale: float, energyScale: float)#

This is the MLPotentialImpl implementing the TorchMDNet potential.

The TorchMDNet potential is constructed using torchmdnet to build a PyTorch model, and then integrated into the OpenMM System using a TorchForce. To use it, specify the model by name and provide the path to a model.

>>> potential = MLPotential('torchmdnet', modelPath=<model_file_path>)

The default energy and length scales assume a model is trained with positions in angstroms and energies in eV. If this is not the case you can specify the length and energy scales by passing the factors that convert the model distance to nm and the energy to kJ/mol, for example:

>>> potential = MLPotential('torchmdnet', modelPath=<model_file_path>,
                            lengthScale=0.1 # angstrom to nm,
                            energyScale=4.184 # kcal/mol to kJ/mol)

During system creation you can enable CUDA graphs for a speed-up for small molecules:

>>>  system = potential.createSystem(pdb.topology, cudaGraphs=True)

The default is to enable this for TensorNet models.

You can also specify the molecule’s total charge:

>>>  system = potential.createSystem(pdb.topology, charge=0)

Pretained AceFF models can be used directly:

>>> potential = MLPotential('aceff-2.0')

>>> potential = MLPotential('aceff-1.1')

>>> potential = MLPotential('aceff-1.0')

Coulomb cutoff behavior#

The Coulomb cutoff in TorchMD-Net uses a reaction-field approximation. Applying it to a non-periodic system introduces errors, so by default the cutoff is only used when the system uses periodic boundary conditions.

You can override this with the useCoulombCutoff argument if you know which behavior you want, for example:

>>>  system = potential.createSystem(pdb.topology, useCoulombCutoff=False)
__init__(name: str, modelPath: str, lengthScale: float, energyScale: float) → None#

Initialize the TorchMDNetPotentialImpl.

Parameters:

  • name (str) – The name of the model. ‘torchmdnet’ for a local model file, or pretrained models are available: ‘aceff-1.0’ or ‘aceff-1.1’.

  • modelPath (str, optional) – The path to the locally trained torchmdnet model if name is ‘torchmdnet’.

  • lengthScale (float) – The length conversion factor from the model units to nanometers. If not specified the default is 0.1 which corresponds to a model in angstrom

  • energyScale (float) – The energy conversion factor from the model units to kJ/mol. If not specified the default is 96.4916 which corresponds to a model in eV.

Methods

__init__(name, modelPath, lengthScale, ...)

Initialize the TorchMDNetPotentialImpl.

addForces(topology, system, atoms, ...)

Add Force objects to a System to implement the potential function.

createMixedSystem(topology, system, atoms, ...)

Creates a mixed system using a potential-specific embedding method.

getMLLongRange()

Returns whether ML interactions are local (False), or long-ranged (True) when periodic boundary conditions are present.

getSupportedEmbeddings()

Retrieves a list of names of supported embedding methods (for the creation of mixed ML/MM systems) specific to this potential.

Attributes

KNOWN_MODELS

addForces(topology: Topology, system: System, atoms: Iterable[int] | None, forceGroup: int, **args)#

Add Force objects to a System to implement the potential function.

This is invoked by MLPotential.createSystem(). Subclasses must implement it to create the requested potential function.

Parameters:

  • topology (Topology) – the Topology from which the System is being created

  • system (System) – the System that is being created

  • atoms (Optional[Iterable[int]]) – the indices of atoms the potential should be applied to, or None if it should be applied to the entire System

  • forceGroup (int) – the force group that any newly added Forces should be in

  • args – any additional keyword arguments that were provided to createSystem() are passed to this method. This allows subclasses to customize their behavior based on extra arguments.

getMLLongRange() → bool | None#

Returns whether ML interactions are local (False), or long-ranged (True) when periodic boundary conditions are present. This controls which interactions are included by some ML/MM embedding methods. Consult the documentation for each embedding method for more details. None can be returned if the nature of the interactions is not known by the MLPotentialImpl.

The default implementation of this method, used if a subclass does not override it, always returns None.

createMixedSystem(topology: Topology, system: System, atoms: list[int], forceGroup: int, interpolate: bool, embedding: str, **args) → System#

Creates a mixed system using a potential-specific embedding method.

This is invoked by MLPotential.createMixedSystem(). It will only be called with one of the names returned by getSupportedEmbeddings(). If subclasses support any potential-specific embedding methods, they must also provide implementations of those methods by overriding this method. If not, it does not need to be implemented.

Each embedding method is responsible for implementing interpolation; if interpolate is True, a global parameter “lambda_interpolate” should be present in the returned system, with the behavior as described by MLPotential.createMixedSystem().

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

  • 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 (will always be one in the list returned by the getSupportedEmbeddings() method)

  • args – any additional arguments for the potential or embedding method

Returns:

  • a newly created System object that uses this potential function and the

  • requested embedding method to model the Topology

getSupportedEmbeddings() → list[str]#

Retrieves a list of names of supported embedding methods (for the creation of mixed ML/MM systems) specific to this potential. If one of these names is provided instead of providing the name of a generic embedding plugin, embedding will be performed by the potential itself.

This is invoked by MLPotential.createMixedSystem(). If a subclass wishes to define one or more potential-specific embedding methods, it should implement this method; otherwise, it does not need to.