What are Actions?

Overview

Questions

  • What are actions?

  • Why would I want to use custom actions?

  • What categories of actions exist for customization in HOOMD-blue?

Objectives

  • Explain the concept of an action in HOOMD-blue.

  • Discuss potential use cases for custom Python actions.

  • Provide the categories of actions in HOOMD-blue.

Actions

Actions are the objects that act or operate on a hoomd.Simulation object. Looking at HOOMD-blue from the Python perspective, actions are wrapped or composed by operations. For example, objects like hoomd.update.BoxResize and hoomd.hpmc.tune.MoveSize contain actions internally. In other words, the actions implement the logic responsible for implementing the functionality of an operation (e.g. resizing the box for hoomd.update.BoxResize), while the operation handles some logistics like determining when the action will run using a hoomd.Trigger object.

Actions can be written in Python using hoomd.custom.Action. Through creating a subclass of Action HOOMD-blue’s capabilities can be augmented and customized.

Why Python Custom Actions?

HOOMD-blue offers Python Actions for a variety of reasons.

  • Enable more customization in Python.

  • Quicker prototyping of new simulation techniques.

  • Allow use of SciPy libraries for use cases like on-the-fly machine learning forcefields.

  • Serve as a foreign function interface from a compiled library through Python to HOOMD-blue’s run loop. For instance, a Python library that uses Rust as a backend could be used in a Python custom action.

Some example use cases are storing simulation data in a user’s desired format whether that is a database, file format like HDF5, or other storage medium, simulating a system under a radiation source, or advanced sampling techniques.

Categories of Actions?

Currently, HOOMD-blue offers three types of actions: updaters, writers, and tuners. These categories serve to distinguish how an action interacts with a simulation and its state attribute.

  • Updaters modify the simulation state when triggered. hoomd.update.BoxResize is an example of an updater as it changes the simulation box.

  • Writers observe the simulation state and write that data to a file or some other object (writers should not modify the simulation state). hoomd.write.GSD is an example of a writer; it does not change the simulation state, but writes it out to a GSD file.

  • Tuners modify another object’s attributes. Tuners should not modify state, but can modify another object to improve performance. hoomd.hpmc.tune.MoveSize is an example of this type of action. MoveSize tunes the integrator’s trial move sizes to reach a specific acceptance rate performance but does not modify the simulation state.

Recap

  • Actions are objects that act on a hoomd.Simulation object.

  • Actions can be written in Python using hoomd.custom.Action.

  • There are three categories of actions.

    • Updaters: modify simulation state

    • Writers: doesn’t modify simulation state, writes out data

    • Tuners: doesn’t modify simulation state, modifies object attributes.

In the next section we start writing custom actions and using them in HOOMD-blue simulations.