abracudabra.device.conversion
=============================

.. py:module:: abracudabra.device.conversion

.. autoapi-nested-parse::

   Move an array, series, or tensor to a device.



Functions
---------

.. autoapisummary::

   abracudabra.device.conversion.to_cupy_array
   abracudabra.device.conversion.array_to_device
   abracudabra.device.conversion.frame_to_device
   abracudabra.device.conversion.tensor_to_device
   abracudabra.device.conversion.to_device


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

.. py:function:: to_cupy_array(sequence, /, device_idx = None)

   Convert a sequence to a cupy array.

   :param sequence: The sequence to convert.
   :param device_idx: The device index to move the array to.

   :returns: The sequence as a cupy array.


.. py:function:: array_to_device(array, /, device)

   Move a NumPy/CuPy array to a device.

   :param array: The array to move.
   :param device: The device to move the array to.

   :returns: The array on the specified device.


.. py:function:: frame_to_device(frame: abracudabra._annotations.Index, /, device_type: Literal['cpu']) -> pandas.Index
                 frame_to_device(frame: abracudabra._annotations.Index, /, device_type: Literal['cuda']) -> cudf.Index
                 frame_to_device(frame: abracudabra._annotations.Series, /, device_type: Literal['cpu']) -> pandas.Series
                 frame_to_device(frame: abracudabra._annotations.Series, /, device_type: Literal['cuda']) -> cudf.Series
                 frame_to_device(frame: abracudabra._annotations.DataFrame, /, device_type: Literal['cpu']) -> pandas.DataFrame
                 frame_to_device(frame: abracudabra._annotations.DataFrame, /, device_type: Literal['cuda']) -> cudf.DataFrame
                 frame_to_device(frame: object, /, device_type: abracudabra.device.base.DeviceType) -> abracudabra._annotations.Index | abracudabra._annotations.Series | abracudabra._annotations.DataFrame

   Move a Pandas/cuDF index, series or dataframe to a device.

   :param frame: The series or dataframe to move.
   :param device_type: The device type to move the frame to.

   :returns: The series or dataframe on the specified device.


.. py:function:: tensor_to_device(tensor, /, device)

   Move a Torch tensor to a device.


.. py:function:: to_device(sequence: abracudabra._annotations.Series, /, device: abracudabra.device.base.Device | str) -> abracudabra._annotations.Series
                 to_device(sequence: torch.Tensor, /, device: abracudabra.device.base.Device | str) -> torch.Tensor
                 to_device(sequence: abracudabra._annotations.DataFrame, /, device: abracudabra.device.base.Device | str) -> abracudabra._annotations.DataFrame
                 to_device(sequence: abracudabra._annotations.Index, /, device: abracudabra.device.base.Device | str) -> abracudabra._annotations.Index
                 to_device(sequence: abracudabra._annotations.Array, /, device: abracudabra.device.base.Device | str) -> abracudabra._annotations.Array
                 to_device(sequence: abracudabra._annotations.Array | abracudabra._annotations.Series | torch.Tensor, /, device: abracudabra.device.base.Device | str) -> abracudabra._annotations.Index | abracudabra._annotations.Series | abracudabra._annotations.DataFrame | abracudabra._annotations.Array | torch.Tensor

   Move an array, series, or tensor to a device.

   Call the appropriate function to move the element to the device:

   * :py:func:`abracudabra.device.conversion.array_to_device` for NumPy/CuPy arrays.
   * :py:func:`abracudabra.device.conversion.frame_to_device`
     for Pandas/cuDF index/series/dataframes.
   * :py:func:`abracudabra.device.conversion.tensor_to_device` for Torch tensors.

   :param sequence: The sequence to move to the device.
   :param device: The device to move the sequence to.

   :returns: The sequence on the specified device.

   :raises TypeError: If the sequence is not a NumPy/CuPy array, Pandas/cuDF
       index/series/dataframe or Torch tensor.

   .. rubric:: Examples

   Move a Pandas dataframe to the GPU (cuDF dataframe):

   >>> import pandas as pd
   >>> from abracudabra import to_device
   >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
   >>> df_gpu = to_device(df, "cuda")
   >>> print(type(df_gpu))
   <class 'cudf.core.dataframe.DataFrame'>

   Move a cuDF dataframe to the CPU (Pandas dataframe):

   >>> df_cpu = to_device(df_gpu, "cpu")
   >>> print(type(df_cpu))
   <class 'pandas.core.frame.DataFrame

   Move a numpy array to the GPU (cupy):

   >>> import numpy as np
   >>> arr = np.array([1, 2, 3])
   >>> arr_gpu = to_device(arr, "cuda")
   >>> print(type(arr_gpu))
   <class 'cupy.ndarray'>