abracudabra.device.query
========================

.. py:module:: abracudabra.device.query

.. autoapi-nested-parse::

   Query the device of a NumPy/CuPy array, series or Torch tensor.



Functions
---------

.. autoapisummary::

   abracudabra.device.query.frame_get_device_type
   abracudabra.device.query.get_device
   abracudabra.device.query.guess_device


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

.. py:function:: frame_get_device_type(frame: abracudabra._annotations.Series | abracudabra._annotations.DataFrame, /, *, raise_if_unknown: Literal[True] = ...) -> abracudabra.device.base.DeviceType
                 frame_get_device_type(frame: abracudabra._annotations.Series | abracudabra._annotations.DataFrame, /, *, raise_if_unknown: bool = ...) -> abracudabra.device.base.DeviceType | None

   Get the device type of a pandas or cudf series or dataframe.

   :param frame: The frame to check.
   :param raise_if_unknown: Whether to raise an error if the frame is not
                            a series or dataframe.

   :returns: The device type of the frame.
             If  ``raise_if_unknown`` is ``False`` and the frame is not a series or
             dataframe, return ``None``.

   :raises TypeError: If the frame is not a series or dataframe and
       ``raise_if_unknown`` is ``True``.


.. py:function:: get_device(element: abracudabra._annotations.Array | torch.Tensor, /, *, raise_if_unknown: Literal[True] = ...) -> abracudabra.device.base.Device
                 get_device(element: abracudabra._annotations.Array | torch.Tensor, /, *, raise_if_unknown: bool = ...) -> abracudabra.device.base.Device | None

   Get the device of a NumPy/CuPy array or series.

   :param element: The element to check.
   :param raise_if_unknown: Whether to raise an error if the element is not a known
                            array or tensor.

   :returns: The device of the element.

   .. rubric:: Examples

   >>> import numpy as np
   >>> array = np.random.rand(3)
   >>> get_device(array)
   Device(type="cpu", idx=None)
   >>> import torch
   >>> tensor = torch.rand(3, device="cuda")
   >>> get_device(tensor)
   Device(type="cuda", idx=0)


.. py:function:: guess_device(*elements, skip_unknown = True)

   Guess the device of a sequence of arrays or tensors.

   This function checks the device of the elements and returns the device if all
   elements are on the same device.
   Otherwise, it raises an error.

   :param \*elements: The elements to check.
   :param skip_unknown: Whether to skip elements that are not known arrays or tensors
                        (e.g., lists, tuples, etc.).

   :returns: The device of the elements.

   :raises ValueError: If no elements are given.
   :raises ValueError: If the device cannot be inferred from any of the elements
       (if ``skip_unknown`` is ``True``).
   :raises ValueError: If the elements are on different devices.