hoomd.operation¶

Overview

`AutotunedObject`	An object with autotuned kernel parameters.
`Compute`	Compute properties of the simulation's state.
`Integrator`	Advance the simulation state forward one time step.
`Operation`	Represents an operation.
`Tuner`	Adjust the parameters of other operations to improve performance.
`TriggeredOperation`	Operations that include a trigger to determine when to run.
`Updater`	Change the simulation's state.
`Writer`	Write output that depends on the simulation's state.

Details

Operation class types.

Operations act on the state of the system at defined points during the simulation’s run loop. Add operation objects to the Simulation.operations collection.

See also

hoomd.Operations

hoomd.Simulation

class hoomd.operation.Operation¶

Bases: AutotunedObject

Represents an operation.

Operations in the HOOMD-blue data scheme are objects that operate on a hoomd.Simulation object. They broadly consist of 5 subclasses: Updater, Writer, Compute, Tuner, and Integrator. All HOOMD-blue operations inherit from one of these five base classes. To find the purpose of each class see its documentation.

Warning

This class should not be instantiated by users. The class can be used for isinstance or issubclass checks.

Note

Developers or those contributing to HOOMD-blue, see our architecture file for information on HOOMD-blue’s architecture decisions regarding operations.

__dir__()¶: Expose all attributes for dynamic querying in notebooks and IDEs.

property is_tuning_complete¶

Check if kernel parameter tuning is complete.

True when tuning is complete and kernel_parameters has locked optimal parameters for all active kernels used by this object.

Example:

while (not operation.is_tuning_complete):
    simulation.run(1000)

Type:: bool

property kernel_parameters¶

Kernel parameters.

The dictionary maps GPU kernel names to tuples of integers that control how the kernel executes on the GPU. These values will change during the tuning process and remain static after tuning completes. Set the kernel parameters for one or more kernels to force specific values and stop tuning.

Warning

The keys and valid values in this dictionary depend on the hardware device, the HOOMD-blue version, and the value of class attributes. Keys and/or valid values may change even with new patch releases of HOOMD-blue.

Provided that you use the same HOOMD-blue binary on the same hardware and execute a script with the same parameters, you may save the tuned values from one run and load them in the next.

Examples:

kernel_parameters = operation.kernel_parameters

operation.kernel_parameters = kernel_parameters

Type:: dict[str, tuple[float]]

property loggables¶

Name, category mapping of loggable quantities.

Type:: dict[str, str]

tune_kernel_parameters()¶

Start tuning kernel parameters.

After calling tune_kernel_parameters, AutotunedObject will vary the kernel parameters in subsequent time steps, check the run time of each, and lock to the fastest performing parameters after the scan is complete.

Example:

operation.tune_kernel_parameters()

class hoomd.operation.AutotunedObject¶

Bases:

An object with autotuned kernel parameters.

AutotunedObject instances may complete portions of their computation with one or more GPU kernels. Each GPU kernel is executed with a set of parameters (kernel_parameters) that influence the run time of the execution. After initialization, AutotunedObject varies these parameters as the simulation runs and searches for the best performing combination. The optimal parameters depend on your system’s size, density, force field parameters, the specific hardware you execute on, and more.

Check is_tuning_complete to check if the search is complete. After the search is complete, AutotunedObject holds the parameters constant at the optimal values. Typical operations require thousands of time steps to complete tuning. Some may take tens of thousands or more depending on the parameters you set.

Tip

When you significantly change your system during the simulation (e.g. compress to a higher density), then you can tune the parameters again after with tune_kernel_parameters. This step is optional, but may increase performance as the new system parameters may lead to different optimal parameters.

Note

In MPI parallel execution, all methods and attributes of AutotunedObject reference the rank local tuner objects. Different ranks may tune different optimal kernel parameters and may complete tuning at different times. Use only hoomd.Operations.is_tuning_complete in control flow operations, as this method is reduced across all ranks.

See also

property is_tuning_complete¶

Check if kernel parameter tuning is complete.

True when tuning is complete and kernel_parameters has locked optimal parameters for all active kernels used by this object.

Example:

while (not operation.is_tuning_complete):
    simulation.run(1000)

Type:: bool

property kernel_parameters¶

Kernel parameters.

Warning

Provided that you use the same HOOMD-blue binary on the same hardware and execute a script with the same parameters, you may save the tuned values from one run and load them in the next.

Examples:

kernel_parameters = operation.kernel_parameters

operation.kernel_parameters = kernel_parameters

Type:: dict[str, tuple[float]]

tune_kernel_parameters()¶

Start tuning kernel parameters.

Example:

operation.tune_kernel_parameters()

class hoomd.operation.Compute¶

Bases: Operation

Compute properties of the simulation’s state.

A compute is an operation which computes some property for another operation or use by a user.

Warning

This class should not be instantiated by users. The class can be used for isinstance or issubclass checks.

class hoomd.operation.Integrator¶

Bases: Operation

Advance the simulation state forward one time step.

An integrator is the operation which evolves a simulation’s state in time. In hoomd.hpmc, integrators perform particle based Monte Carlo moves. In hoomd.md, the hoomd.md.Integrator class organizes the forces, equations of motion, and other factors of the given simulation.

Warning

This class should not be instantiated by users. The class can be used for isinstance or issubclass checks.

class hoomd.operation.TriggeredOperation(trigger)¶

Bases: Operation

Operations that include a trigger to determine when to run.

Warning

This class should not be instantiated by users. The class can be used for isinstance or issubclass checks.

trigger¶

The trigger to activate this operation.

Example

operation.trigger = hoomd.trigger.Periodic(10)

Type:: hoomd.trigger.Trigger

class hoomd.operation.Tuner(trigger)¶

Bases: TriggeredOperation

Adjust the parameters of other operations to improve performance.

A tuner is an operation which tunes the parameters of another operation for performance or other reasons. A tuner does not modify the current microstate of the simulation. That is a tuner does not change quantities like temperature, particle position, or the number of bonds in a simulation.

Warning

This class should not be instantiated by users. The class can be used for isinstance or issubclass checks.

class hoomd.operation.Updater(trigger)¶

Bases: TriggeredOperation

Change the simulation’s state.

An updater is an operation which modifies a simulation’s state.

Warning

This class should not be instantiated by users. The class can be used for isinstance or issubclass checks.

class hoomd.operation.Writer(trigger)¶

Bases: TriggeredOperation

Write output that depends on the simulation’s state.

A writer is an operation which writes out a simulation’s state.

Warning

This class should not be instantiated by users. The class can be used for isinstance or issubclass checks.