hoomd.custom#

Overview

Action

Base class for user-defined actions.

CustomOperation

User defined operation.

Details

Custom operations.

CustomOperation provides a mechanism for users to insert Python code via an Action subclass that executes during the simulation’s run loop. Use this to prototype new simulation methods in Python, analyze the system state while the simulation progresses, or write output to custom file formats.

class hoomd.custom.Action#

Bases: object

Base class for user-defined actions.

To implement a custom operation in Python, subclass Action and implement the act() method to perform the desired action. To include the action in the simulation run loop, pass an instance of the action to hoomd.update.CustomUpdater, hoomd.write.CustomWriter, or hoomd.tune.CustomTuner.

from hoomd.custom import Action


class ExampleAction(Action):
    def act(self, timestep):
        self.com = self._state.snapshot.particles.position.mean(axis=0)

To request that HOOMD-blue compute virials, pressure, the rotational kinetic energy, or the external field virial, set the flags attribute with the appropriate flags from the internal Action.Flags enumeration.

from hoomd.custom import Action


class ExampleActionWithFlag(Action):
    flags = [Action.Flags.ROTATIONAL_KINETIC_ENERGY,
             Action.Flags.PRESSURE_TENSOR,
             Action.Flags.EXTERNAL_FIELD_VIRIAL]

    def act(self, timestep):
        pass

Use the hoomd.logging.log decorator to define loggable properties.

from hoomd.python_action import Action
from hoomd.logging import log


class ExampleActionWithFlag(Action):

    @log
    def answer(self):
        return 42

    def act(self, timestep):
        pass
flags#

List of flags from the Action.Flags. Used to tell the integrator if specific quantities are needed for the action.

Type

list[Action.Flags]

class Flags(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: IntEnum

Flags to indictate the integrator should calculate quantities.

  • PRESSURE_TENSOR = 0

  • ROTATIONAL_KINETIC_ENERGY = 1

  • EXTERNAL_FIELD_VIRIAL = 2

abstract act(timestep)#

Performs whatever action a subclass implements.

Parameters

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

Note

Use self._state to access the simulation state via hoomd.State when using the base class attach.

attach(simulation)#

Attaches the Action to the hoomd.Simulation.

Parameters

simulation (hoomd.Simulation) – The simulation to attach the action to.

Stores the simulation state in self._state. Override this in derived classes to implement other behaviors.

detach()#

Detaches the Action from the hoomd.Simulation.

property loggables#

Name, category mapping of loggable quantities.

Type

dict[str, str]

class hoomd.custom.CustomOperation(trigger, action)#

Bases: TriggeredOperation

User defined operation.

This is the parent class for hoomd.tune.CustomTuner, hoomd.update.CustomUpdater. and hoomd.write.CustomWriter. These classes wrap Python objects that inherit from hoomd.custom.Action so they can be added to the simulation operations.

This class also implements a “pass-through” system for attributes. Attributes and methods from the passed in action will be available directly in this class. This does not apply to attributes with these names: trigger, _action, and action.

Note

Due to the pass through no attribute should exist both in hoomd.custom.CustomOperation and the hoomd.custom.Action.

Note

This object should not be instantiated or subclassed by an user.

trigger#

A trigger to determine when the wrapped hoomd.custom.Action is run.

Type

hoomd.trigger.Trigger

__getattr__(attr)#

Pass through attributes/methods of the wrapped object.

__setstate__(state)#

Set object state from pickling or deepcopying.

act(timestep)#

Perform the action of the custom action if attached.

Calls through to the action property of the instance.

Parameters

timestep (int) – The current timestep of the state.

property action#

hoomd.custom.Action The action the operation wraps.