zarr.buffer.gpu
===============

.. py:module:: zarr.buffer.gpu


Attributes
----------

.. autoapisummary::

   zarr.buffer.gpu.buffer_prototype


Classes
-------

.. autoapisummary::

   zarr.buffer.gpu.Buffer
   zarr.buffer.gpu.NDBuffer


Module Contents
---------------

.. py:class:: Buffer(array_like: zarr.core.buffer.core.ArrayLike)

   Bases: :py:obj:`zarr.core.buffer.core.Buffer`


   
   A flat contiguous memory block on the GPU

   We use Buffer throughout Zarr to represent a contiguous block of memory.

   A Buffer is backed by a underlying array-like instance that represents
   the memory. The memory type is unspecified; can be regular host memory,
   CUDA device memory, or something else. The only requirement is that the
   array-like instance can be copied/converted to a regular Numpy array
   (host memory).

   :Parameters:

       **array_like**
           array-like object that must be 1-dim, contiguous, and byte dtype.











   .. rubric:: Notes

   This buffer is untyped, so all indexing and sizes are in bytes.



   ..
       !! processed by numpydoc !!

   .. py:method:: as_array_like() -> ArrayLike

      
      Returns the underlying array (host or device memory) of this buffer

      This will never copy data.




      :Returns:

          The underlying 1d array such as a NumPy or CuPy array.
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: as_buffer_like() -> zarr.core.common.BytesLike

      
      Returns the buffer as an object that implements the Python buffer protocol.





      :Returns:

          An object that implements the Python buffer protocol
              ..








      .. rubric:: Notes

      Might have to copy data, since the implementation uses `.as_numpy_array()`.



      ..
          !! processed by numpydoc !!


   .. py:method:: as_numpy_array() -> numpy.typing.NDArray[Any]

      
      Returns the buffer as a NumPy array (host memory).





      :Returns:

          NumPy array of this buffer (might be a data copy)
              ..








      .. rubric:: Notes

      Might have to copy data, consider using `.as_array_like()` instead.



      ..
          !! processed by numpydoc !!


   .. py:method:: create_zero_length() -> Self
      :classmethod:


      
      Create an empty buffer with length zero





      :Returns:

          New empty 0-length buffer
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: from_array_like(array_like: ArrayLike) -> Self
      :classmethod:


      
      Create a new buffer of an array-like object


      :Parameters:

          **array_like**
              array-like object that must be 1-dim, contiguous, and byte dtype.



      :Returns:

          New buffer representing `array_like`
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: from_buffer(buffer: zarr.core.buffer.core.Buffer) -> Self
      :classmethod:


      
      Create an GPU Buffer given an arbitrary Buffer
      This will try to be zero-copy if `buffer` is already on the
      GPU and will trigger a copy if not.





      :Returns:

          New GPU Buffer constructed from `buffer`
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: from_bytes(bytes_like: zarr.core.common.BytesLike) -> Self
      :classmethod:


      
      Create a new buffer of a bytes-like object (host memory)


      :Parameters:

          **bytes_like**
              bytes-like object



      :Returns:

          New buffer representing `bytes_like`
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: to_bytes() -> bytes

      
      Returns the buffer as `bytes` (host memory).





      :Returns:

          `bytes` of this buffer (data copy)
              ..






      .. warning::

          Will always copy data, only use this method for small buffers such as metadata
          buffers. If possible, use `.as_numpy_array()` or `.as_array_like()` instead.





      ..
          !! processed by numpydoc !!


.. py:class:: NDBuffer(array: zarr.core.buffer.core.NDArrayLike)

   Bases: :py:obj:`zarr.core.buffer.core.NDBuffer`


   
   A n-dimensional memory block on the GPU

   We use NDBuffer throughout Zarr to represent a n-dimensional memory block.

   A NDBuffer is backed by a underlying ndarray-like instance that represents
   the memory. The memory type is unspecified; can be regular host memory,
   CUDA device memory, or something else. The only requirement is that the
   ndarray-like instance can be copied/converted to a regular Numpy array
   (host memory).

   :Parameters:

       **array**
           ndarray-like object that is convertible to a regular Numpy array.











   .. rubric:: Notes

   The two buffer classes Buffer and NDBuffer are very similar. In fact, Buffer
   is a special case of NDBuffer where dim=1, stride=1, and dtype="B". However,
   in order to use Python's type system to differentiate between the contiguous
   Buffer and the n-dim (non-contiguous) NDBuffer, we keep the definition of the
   two classes separate.



   ..
       !! processed by numpydoc !!

   .. py:method:: all_equal(other: Any, equal_nan: bool = True) -> bool

      
      Compare to `other` using np.array_equal.
















      ..
          !! processed by numpydoc !!


   .. py:method:: as_ndarray_like() -> NDArrayLike

      
      Returns the underlying array (host or device memory) of this buffer

      This will never copy data.




      :Returns:

          The underlying array such as a NumPy or CuPy array.
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: as_numpy_array() -> numpy.typing.NDArray[Any]

      
      Returns the buffer as a NumPy array (host memory).





      :Returns:

          NumPy array of this buffer (might be a data copy)
              ..






      .. warning::

          Might have to copy data, consider using `.as_ndarray_like()` instead.





      ..
          !! processed by numpydoc !!


   .. py:method:: as_scalar() -> ScalarType

      
      Returns the buffer as a scalar value
















      ..
          !! processed by numpydoc !!


   .. py:method:: astype(dtype: numpy.typing.DTypeLike, order: Literal['K', 'A', 'C', 'F'] = 'K') -> Self


   .. py:method:: copy() -> Self


   .. py:method:: create(*, shape: collections.abc.Iterable[int], dtype: numpy.typing.DTypeLike, order: Literal['C', 'F'] = 'C', fill_value: Any | None = None) -> Self
      :classmethod:


      
      Create a new buffer and its underlying ndarray-like object


      :Parameters:

          **shape**
              The shape of the buffer and its underlying ndarray-like object

          **dtype**
              The datatype of the buffer and its underlying ndarray-like object

          **order**
              Whether to store multi-dimensional data in row-major (C-style) or
              column-major (Fortran-style) order in memory.

          **fill_value**
              If not None, fill the new buffer with a scalar value.



      :Returns:

          New buffer representing a new ndarray_like object
              ..








      .. rubric:: Notes

      A subclass can overwrite this method to create a ndarray-like object
      other then the default Numpy array.



      ..
          !! processed by numpydoc !!


   .. py:method:: empty(shape: tuple[int, Ellipsis], dtype: numpy.typing.DTypeLike, order: Literal['C', 'F'] = 'C') -> Self
      :classmethod:


      
      Create an empty buffer with the given shape, dtype, and order.

      This method can be faster than ``NDBuffer.create`` because it doesn't
      have to initialize the memory used by the underlying ndarray-like
      object.

      :Parameters:

          **shape**
              The shape of the buffer and its underlying ndarray-like object

          **dtype**
              The datatype of the buffer and its underlying ndarray-like object

          **order**
              Whether to store multi-dimensional data in row-major (C-style) or
              column-major (Fortran-style) order in memory.



      :Returns:

          buffer
              New buffer representing a new ndarray_like object with empty data.







      .. seealso::

          
          :obj:`NDBuffer.create`
              Create a new buffer with some initial fill value.
          
          



      ..
          !! processed by numpydoc !!


   .. py:method:: fill(value: Any) -> None


   .. py:method:: from_ndarray_like(ndarray_like: NDArrayLike) -> Self
      :classmethod:


      
      Create a new buffer of a ndarray-like object


      :Parameters:

          **ndarray_like**
              ndarray-like object



      :Returns:

          New buffer representing `ndarray_like`
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: from_numpy_array(array_like: numpy.typing.ArrayLike) -> Self
      :classmethod:


      
      Create a new buffer of Numpy array-like object


      :Parameters:

          **array_like**
              Object that can be coerced into a Numpy array



      :Returns:

          New buffer representing `array_like`
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: reshape(newshape: tuple[int, Ellipsis] | Literal[-1]) -> Self


   .. py:method:: squeeze(axis: tuple[int, Ellipsis]) -> Self


   .. py:method:: transpose(axes: SupportsIndex | collections.abc.Sequence[SupportsIndex] | None) -> Self


   .. py:property:: byteorder
      :type: zarr.codecs.bytes.Endian



   .. py:property:: dtype
      :type: numpy.dtype[Any]



   .. py:property:: shape
      :type: tuple[int, Ellipsis]



.. py:data:: buffer_prototype

