hoomd.data.array

Overview

HOOMDArray

A NumPy like interface to internal HOOMD-blue data.

HOOMDGPUArray

Exposes an internal HOOMD-blue GPU buffer.

Details

class hoomd.data.array.HOOMDArray(buffer, callback, read_only=None)

A NumPy like interface to internal HOOMD-blue data.

These objects are returned by HOOMD-blue’s zero copy local snapshot API (hoomd.State.cpu_local_snapshot). This class acts like a numpy.ndarray object through NumPy’s provided interface. Some exceptions are the view, resize, flat and flatiter methods and the data and base properties. For typical use cases, understanding this class is not necessary. Treat it as a numpy.ndarray.

In general, whenever possible (when an array pointing to a new buffer is returned) we return a numpy.ndarray. However, any array pointing to the same data will be returned as a HOOMDArray. To ensure memory safety, a HOOMDArray object cannot be accessed outside of the context manager in which it was created. To have access outside the manager an explicit copy must be made (e.g. numpy.array(obj, copy=True)).

In general this class should be nearly as fast as a standard NumPy array, but there is some overhead. This is mitigated by returning a numpy.ndarray whenever possible. If every ounce of performance is necessary, HOOMDArray._coerce_to_ndarray can provide a numpy.ndarray object inside the context manager. References to a ``HOOMDArray`` object’s buffer after leaving the context manager is UNSAFE. It can cause SEGFAULTs and cause your program to crash. Use this function only if absolutely necessary.

Performance Tips:

Assume a represents a HOOMDArray for examples given.

  • Place the HOOMDArray to the left of the expression (e.g. a + b + c is faster than b + a + c). This has to do with the mechanisms HOOMDArray has to do to hook into NumPy’s functionality.

  • If a copy will need to be made, do it as early as possible. In other words, if you will need access outside the context manager, use numpy.array(a, copy=True) before doing any calculations.

  • If you know that your access of the internal buffer is safe and we cannot detect this (i.e. we return a HOOMDArray), using HOOMDArray._coerce_to_ndarray should help. Note that for large arrays this only gives minimal performance improvements at greater risk of breaking your program.

class hoomd.data.array.HOOMDGPUArray(*args, **kwargs)

Exposes an internal HOOMD-blue GPU buffer.

The HOOMDGPUArray object exposes a GPU data buffer using the __cuda_array_interface__. This class tries to prevent invalid memory access through only allow the buffer to be exposed within a context manager (hoomd.State.gpu_local_snapshot). However, to prevent copying the data, we cannot guarentee the data will not leak. This means that it is possible to escape this class. An example of an error of this kind is shown below.

with sim.state.gpu_local_snapshot as data:
    # valid within context manager
    pos = cupy.array(data.particles.position, copy=False)
    # can use pos within manager
    pos[:, 2] += 1
# invalid data access can cause SEGFAULTs and other issues
pos[:, 2] -= 1

In general, it is safer to not store any non HOOMDGPUArray references to a data buffer. This can be done when necessary, but care must be taken not to use references to the data outside the context manager.

The full functionality of this class depends on whether, HOOMD-blue can import CuPy. If CuPy can be imported then, we wrap much of the cupy.ndarray class’s functionality. Otherwise, we just expose the buffer and provide a few basic properties.

In either case HOOMDGPUArray supports getting (but not setting) the shape, strides, and ndim properties.

When CuPy is imported, compound assignment operators (e.g. +=, -=, *=) are available. In addition, most methods besides view, resize, flat, flatiter are available. The same is true for properties except the data and base properties. See CuPy’s documentation for a list of methods. An important note is that due their being no way to hook into standard operators like (+, -, *) direct addition, subtraction, and multiplication cannot be performed between HOOMDGPUArray and cupy.ndarray objects. However, cupy.add can be directly used and is recommended for memory safety.

Note

Packages like Numba and PyTorch can use HOOMDGPUArray without CuPy installed. Any package that supports version 2 of the __cuda_array_interface__ should support the direct use of HOOMDGPUArray objects.