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 hoomd.custom.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.

Examples:

class ExampleAction(hoomd.custom.Action):
    def act(self, timestep):
        snapshot = self._state.get_snapshot()
        if snapshot.communicator.rank == 0:
            self.com = 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:

class ExampleAction(hoomd.custom.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:

class ExampleAction(hoomd.custom.Action):

    @hoomd.logging.log
    def answer(self):
        return 42

    def act(self, timestep):
        pass

example_action = ExampleAction()
logger.add(example_action, quantities=['answer'])
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=<not given>, *values, 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.