hoomd.data.array¶
Overview
A numpy.ndarray-like interface to internal HOOMD-blue data. |
|
A __cuda_array_interface__ to internal HOOMD-blue data on the GPU. |
Details
Implement zero-copy array.
- class hoomd.data.array.HOOMDArray(buffer, callback, read_only=None)¶
A numpy.ndarray-like interface to internal HOOMD-blue data.
HOOMD-blue’s zero copy local snapshot API (
hoomd.State.cpu_local_snapshot
) returnsHOOMDArray
objects.HOOMDArray
acts likenumpy.ndarray
through NumPy’s provided interface. Some exceptions are theview
,resize
,flat
andflatiter
methods and thedata
andbase
properties.To ensure memory safety, a
HOOMDArray
object cannot be accessed outside of the context manager in which it was created. Make an explicit copy to use the array elsewhere (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.Performance Tips
Let
a
represent aHOOMDArray
.Place the
HOOMDArray
to the left of the expression (e.g.a + b + c
is faster thanb + a + c
). This has to do with the mechanismsHOOMDArray
has to do to hook into NumPy’s functionality.Make copies 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
), usingHOOMDArray._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)¶
A __cuda_array_interface__ to internal HOOMD-blue data on the GPU.
The HOOMDGPUArray object exposes a GPU data buffer using __cuda_array_interface__. This class provides buffer access through a context manager to prevent invalid memory accesses (
hoomd.State.gpu_local_snapshot
). To avoid errors, use arrays only within the relevant context manager. For example:with sim.state.gpu_local_snapshot as data: pos = cupy.array(data.particles.position, copy=False) pos[:, 2] += 1
Note
When CuPy can be imported, then this class wraps much of the
cupy.ndarray
class’s functionality. Otherwise, this class exposes only the buffer.HOOMDGPUArray
always supports getting (but not setting) theshape
,strides
, andndim
properties.HOOMDGPUArray
never supports standard binary operators like (+
,-
,*
). This is a current limitation on external classes hooking into CuPy.When CuPy can be imported, slice/element assignment (e.g.
array[0] = 1; array[:2] = 4
) and compound assignment operators (e.g.+=
,-=
,*=
) are available. In addition, most methods besidesview
,resize
,flat
,flatiter
are available. The same is true for properties except thedata
andbase
properties. See CuPy’s documentation for a list of methods.Tip
Use,
cupy.add
,cupy.multiply
, etc. for binary operations on the GPU.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 ofHOOMDGPUArray
objects.