PythonForce¶

class openmm.openmm.PythonForce(*args)¶

This class provides a mechanism for computing forces and energy with Python code. To use it, define a Python function that takes a State object as its only argument. The State contains particle positions and global parameters. Based on it, the function should compute the potential energy and forces, returning them as its two return values. The forces should be represented as a NumPy array of shape (# particles, 3). For example,

def compute(state):
    pos = state.getPositions(asNumpy=True).value_in_unit(nanometer)
    k = state.getParameters()['k']
    energy = k*np.sum(pos*pos)
    force = -0.5*k*pos
    return energy*kilojoules_per_mole, force*kilojoules_per_mole/nanometer

Attaching units to the return values is optional. If units are omitted, the values are assumed to be in the default units (energy in kJ/mol, forces in kJ/mol/nm).

Now create a Python force, passing the function to the constructor. If you want the force to depend on global parameters, pass a dict as the second parameter with the names and default values of the parameters.

force = PythonForce(compute, {'k':2.5})

The default value of a parameter is its value in newly created Contexts. After a Context is created, you can change the values of parameters by calling setParameter() on it.

The PythonForce cannot tell whether the function you provide makes use of periodic boundary conditions, so you must tell it. To make the force periodic, call setUsesPeriodicBoundaryConditions(True). This will cause usesPeriodicBoundaryConditions() to return True, and the State passed to the computation function will contain periodic box vectors. The positions may also be wrapped into a different periodic box to keep them closer to the origin and improve accuracy.

When using XmlSerializer to save a PythonForce, it uses the Python pickle module to save the computation function. If it cannot be pickled, you will not be able to serialize the PythonForce. Functions defined at the top level of a module can usually be pickled, but local functions defined inside another function cannot.

Compared to other types of forces, computing a force with Python code is slow and has high overhead. When possible, using a different force class is usually preferred. For example, the Python force shown in the example code above (a harmonic force attracting every particle to the origin) could be implemented just as easily with a CustomExternalForce, and would execute much faster if done that way.

__init__(self, computation, globalParameters={}) → PythonForce¶

Create a PythonForce.

Parameters:

computation (function) – A function that performs the computation. It should take a State as its argument and return two values: the potential energy (a scalar) and the forces (a NumPy array).
globalParameters (dict) – Any global parameters the function depends on. Keys are the parameter names, and the corresponding values are their default values.

Methods

`__init__`(self, computation[, globalParameters])	Create a PythonForce.
`getForceGroup`(self)	Get the force group this Force belongs to.
`getGlobalParameters`(self)	Get all global parameters defined by this force.
`getName`(self)	Get the name of this Force.
`getPickledFunction`(self)	Get the pickled representation of the computation function.
`setForceGroup`(self, group)	Set the force group this Force belongs to.
`setName`(self, name)	Set the name of this Force.
`setUsesPeriodicBoundaryConditions`(self, periodic)	Set whether or not this force makes use of periodic boundary conditions.
`usesPeriodicBoundaryConditions`(self)	Returns whether or not this force makes use of periodic boundary conditions.

Attributes

thisown

The membership flag

property thisown¶: The membership flag

getGlobalParameters(self) → Mapping[str, float]¶: Get all global parameters defined by this force. Keys are the parameter names, and the corresponding values are their default values.

getPickledFunction(self) → tuple[char]¶: Get the pickled representation of the computation function. If it cannot be pickled, this will be an empty vector.

usesPeriodicBoundaryConditions(self) → bool¶

Returns whether or not this force makes use of periodic boundary conditions.

Returns:: true if force uses PBC and false otherwise
Return type:: bool

setUsesPeriodicBoundaryConditions(self, periodic)¶: Set whether or not this force makes use of periodic boundary conditions. If this is set to true, periodic box vectors can be retrieved from the State passed to the computation function.

getForceGroup(self) → int¶: Get the force group this Force belongs to.

getName(self) → str¶: Get the name of this Force. This is an arbitrary, user modifiable identifier. By default it equals the class name, but you can change it to anything useful.

setForceGroup(self, group)¶

Set the force group this Force belongs to.

Parameters:: group (int) – the group index. Legal values are between 0 and 31 (inclusive).

setName(self, name)¶: Set the name of this Force. This is an arbitrary, user modifiable identifier. By default it equals the class name, but you can change it to anything useful.