openmmml.models.macepotential.MACEPotentialImpl

class openmmml.models.macepotential.MACEPotentialImpl(name: str, modelPath)

This is the MLPotentialImpl implementing the MACE potential.

The MACE potential is constructed using MACE to build a PyTorch model, and then integrated into the OpenMM System using a TorchForce. This implementation supports both MACE-OFF23 and locally trained MACE models.

To use one of the pre-trained MACE-OFF23 models, specify the model name. For example:

>>> potential = MLPotential('mace-off23-small')

Other available MACE-OFF23 models include ‘mace-off23-medium’ and ‘mace-off23-large’.

To use a locally trained MACE model, provide the path to the model file. For example:

>>> potential = MLPotential('mace', modelPath='MACE.model')

During system creation, you can optionally specify the precision of the model using the precision keyword argument. Supported options are ‘single’ and ‘double’. For example:

>>> system = potential.createSystem(topology, precision='single')

By default, the implementation uses the precision of the loaded MACE model. According to the MACE documentation, ‘single’ precision is recommended for MD (faster but less accurate), while ‘double’ precision is recommended for geometry optimization.

Additionally, you can request computation of the full atomic energy, including the atom self-energy, instead of the default interaction energy, by setting returnEnergyType to ‘energy’. For example:

>>> system = potential.createSystem(topology, returnEnergyType='energy')

The default is to compute the interaction energy, which can be made explicit by setting returnEnergyType='interaction_energy'.

name

The name of the MACE model.

Type:

str

modelPath

The path to the locally trained MACE model if name is ‘mace’.

Type:

str

__init__(name: str, modelPath) → None

Initialize the MACEPotentialImpl.

Parameters:

• name (str) – The name of the MACE model. Options include ‘mace-off23-small’, ‘mace-off23-medium’, ‘mace-off23-large’, and ‘mace’.

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

Methods

__init__(name, modelPath)	Initialize the MACEPotentialImpl.
addForces(topology, system, atoms, forceGroup)	Add the MACEForce to the OpenMM System.

addForces(topology: Topology, system: System, atoms: Iterable[int] | None, forceGroup: int, precision: str | None = None, returnEnergyType: str = 'interaction_energy', **args) → None

Add the MACEForce to the OpenMM System.

Parameters:

• topology (openmm.app.Topology) – The topology of the system.

• system (openmm.System) – The system to which the force will be added.

• atoms (iterable of int) – The indices of the atoms to include in the model. If None, all atoms are included.

• forceGroup (int) – The force group to which the force should be assigned.

• precision (str, optional) – The precision of the model. Supported options are ‘single’ and ‘double’. If None, the default precision of the model is used.

• returnEnergyType (str, optional) – Whether to return the interaction energy or the energy including the self-energy. Default is ‘interaction_energy’. Supported options are ‘interaction_energy’ and ‘energy’.