Custom

class hoomd.md.force.Custom(aniso=False)

Bases: Force

Custom forces implemented in python.

Derive a custom force class from Custom, and override the set_forces method to compute forces on particles. Users have direct, zero-copy access to the C++ managed buffers via either the cpu_local_force_arrays or gpu_local_force_arrays property. Choose the property that corresponds to the device you wish to alter the data on. In addition to zero-copy access to force buffers, custom forces have access to the local snapshot API via the _state.cpu_local_snapshot or the _state.gpu_local_snapshot property.

See also

See the documentation in hoomd.State for more information on the local snapshot API.

Examples:

class MyCustomForce(hoomd.md.force.Custom):
    def __init__(self):
        super().__init__(aniso=True)

    def set_forces(self, timestep):
        with self.cpu_local_force_arrays as arrays:
            arrays.force[:] = -5
            arrays.torque[:] = 3
            arrays.potential_energy[:] = 27
            arrays.virial[:] = np.arange(6)[None, :]

In addition, since data is MPI rank-local, there may be ghost particle data associated with each rank. To access this read-only ghost data, access the property name with either the prefix ghost_ of the suffix _with_ghost.

Note

Pass aniso=True to the md.force.Custom constructor if your custom force produces non-zero torques on particles.

class MyCustomForce(hoomd.md.force.Custom):
    def __init__(self):
        super().__init__()

    def set_forces(self, timestep):
        with self.cpu_local_force_arrays as arrays:
            # access only the ghost particle forces
            ghost_force_data = arrays.ghost_force

            # access torque data on this rank and ghost torque data
            torque_data = arrays.torque_with_ghost

Note

When accessing the local force arrays, always use a context manager.

Note

The shape of the exposed arrays cannot change while in the context manager.

Note

All force data buffers are MPI rank local, so in simulations with MPI, only the data for a single rank is available.

Note

Access to the force buffers is constant (O(1)) time.

{inherited}

---

Members defined in Custom:

abstract set_forces(timestep)

Set the forces in the simulation loop.

Parameters:

timestep (int) – The current timestep in the simulation.