{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Usage Guide\n",
    "\n",
    "Abracudabra is a Python library designed to simplify conversions\n",
    "between arrays, dataframes, series, and tensors, seamlessly\n",
    "handling CPU (NumPy/Pandas/Torch) and CUDA (CuPy/cuDF/Torch) environments.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Supported Data Types and Libraries\n",
    "\n",
    "| Data Object   | CPU                | CUDA             |\n",
    "|---------------|--------------------|------------------|\n",
    "| **Array**     | `numpy.ndarray`    | `cupy.ndarray`   |\n",
    "| **Series**    | `pandas.Series`    | `cudf.Series`    |\n",
    "| **DataFrame** | `pandas.DataFrame` | `cudf.DataFrame` |\n",
    "| **Index**     | `pandas.Index`     | `cudf.Index`     |\n",
    "| **Tensor**    | `torch.Tensor`     | `torch.Tensor`   |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Device Management\n",
    "\n",
    "Abracudabra manages devices through the [Device](autoapi/abracudabra/index.rst#abracudabra.Device) object:\n",
    "\n",
    "- **type** (`\"cpu\"` or `\"cuda\"`)\n",
    "- **idx** (optional integer, e.g., `0` for `cuda:0`)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from abracudabra import Device\n",
    "\n",
    "cpu_device = Device(type=\"cpu\")\n",
    "cuda_device = Device(type=\"cuda\", idx=0)\n",
    "\n",
    "print(f\"CPU device: {cpu_device}\")\n",
    "print(f\"CUDA device: {cuda_device}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conversion Functions\n",
    "\n",
    "Abracudabra provides high-level functions for data conversion:\n",
    "\n",
    "| Function                                                                 | Converts From                            | Converts To |\n",
    "|--------------------------------------------------------------------------|------------------------------------------|-------------|\n",
    "| [to_array](autoapi/abracudabra/index.rst#abracudabra.to_array)         | array, series, dataframe, tensor         | array       |\n",
    "| [to_tensor](autoapi/abracudabra/index.rst#abracudabra.to_tensor)       | array, series, dataframe, tensor         | tensor      |\n",
    "| [to_series](autoapi/abracudabra/index.rst#abracudabra.to_series)       | array, tensor                            | series      |\n",
    "| [to_dataframe](autoapi/abracudabra/index.rst#abracudabra.to_dataframe) | array, tensor, mapping of arrays/tensors | dataframe   |\n",
    "\n",
    "All functions accept an optional `device` parameter:\n",
    "- If specified, output data is moved to that device.\n",
    "- If not specified, data stays on its original device."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example Usage\n",
    "\n",
    "**Convert a torch tensor to an array:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import torch\n",
    "\n",
    "from abracudabra import to_array\n",
    "\n",
    "tensor = torch.rand(2, 3, device=\"cuda:0\")\n",
    "array = to_array(tensor)\n",
    "\n",
    "print(\"type:\", type(array))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Convert array to series:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from abracudabra import to_series\n",
    "\n",
    "array = np.ones((4,), dtype=np.float32)\n",
    "\n",
    "series = to_series(array, device=\"cuda:0\")\n",
    "print(series)\n",
    "print(\"type:\", type(series))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Build dataframe from mixed data types and devices:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cupy as cp\n",
    "import numpy as np\n",
    "import torch\n",
    "\n",
    "from abracudabra import to_dataframe\n",
    "\n",
    "numpy_array = np.full((5,), 1, dtype=np.float32)\n",
    "cupy_array = cp.full((5,), 2, dtype=cp.int8)\n",
    "torch_tensor = torch.full((5,), 3, dtype=torch.float32, device=\"cuda:0\")\n",
    "\n",
    "dataframe = to_dataframe(\n",
    "    {\"numpy\": numpy_array, \"cupy\": cupy_array, \"torch\": torch_tensor}, device=\"cuda:0\"\n",
    ")\n",
    "\n",
    "print(dataframe)\n",
    "print(\"type:\", type(dataframe))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Device Management\n",
    "\n",
    "### Check the Device of an Object\n",
    "\n",
    "Use [get_device](autoapi/abracudabra/index.rst#abracudabra.get_device) to determine the current device of an object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from abracudabra import get_device\n",
    "\n",
    "numpy_array = np.ones((4,), dtype=np.float32)\n",
    "\n",
    "get_device(numpy_array)  # CPU device"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Move Data Between Devices\n",
    "\n",
    "Use [to_device](autoapi/abracudabra/index.rst#abracudabra.to_device)\n",
    "to move data between devices:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cupy as cp\n",
    "\n",
    "from abracudabra import to_device\n",
    "\n",
    "numpy_array = cp.ones((4,), dtype=cp.float32)\n",
    "\n",
    "cupy_array = to_device(numpy_array, device=\"cuda:0\")  # Move to CUDA device\n",
    "\n",
    "print(cupy_array)\n",
    "print(\"type:\", type(cupy_array))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Library Selection Helpers\n",
    "\n",
    "Use helper functions to obtain the correct library based on the target device:\n",
    "- [get_np_or_cp](autoapi/abracudabra/index.rst#abracudabra.get_np_or_cp)\n",
    "  returns `numpy` (`\"cpu\"`) or `cupy` (for `\"cuda\"`).\n",
    "- [get_pd_or_cudf](autoapi/abracudabra/index.rst#abracudabra.get_pd_or_cudf)\n",
    "  returns `pandas` (for `\"cpu\"`) or `cudf` (for `\"cuda\"`).\n",
    "\n",
    "It can be particularly useful since these libraries intentionally share a common API.\n",
    "\n",
    "**Example:**\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from abracudabra import get_np_or_cp\n",
    "\n",
    "device_type = \"cuda\"\n",
    "\n",
    "# Get numpy or cupy (here: cupy)\n",
    "np_or_cp = get_np_or_cp(device_type)\n",
    "\n",
    "# Create a numpy or cupy array (here: cupy)\n",
    "array = np_or_cp.ones((4,), dtype=np.float32)\n",
    "print(type(array))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}