{"id":4889,"library":"awkward-cpp","title":"Awkward Array C++ Kernels","description":"awkward-cpp provides the highly optimized C++ and CUDA kernels and compiled extensions that power the Awkward Array library (version 2.x). It serves as a performance backend, enabling NumPy-like idioms for nested, variable-sized data structures to run at compiled speeds. The library itself is not intended for direct end-user interaction but is a core dependency of the main `awkward` package. It is currently at version 52 and maintains an active release cadence aligned with `awkward` releases.","status":"active","version":"52","language":"en","source_language":"en","source_url":"https://github.com/scikit-hep/awkward-1.0","tags":["data science","physics","array","C++","performance","jagged arrays","scientific computing"],"install":[{"cmd":"pip install awkward-cpp","lang":"bash","label":"Basic installation"},{"cmd":"pip install awkward","lang":"bash","label":"Recommended: installs awkward-cpp as dependency"}],"dependencies":[{"reason":"awkward-cpp provides the core computational kernels for the 'awkward' library; it is not typically used standalone by end-users.","package":"awkward","optional":false}],"imports":[{"note":"awkward-cpp provides low-level kernels and does not expose a direct Python API for end-users. Its features are integrated into the 'awkward' library's public API.","wrong":"import awkward_cpp","symbol":"awkward-cpp","correct":"Functionality is accessed via the 'awkward' library, e.g., 'import awkward as ak'"}],"quickstart":{"code":"import awkward as ak\nimport numpy as np\n\n# Create a nested, variable-sized Awkward Array\narray = ak.Array([[1, 2, 3], [], [4, 5]])\nprint(f\"Original Array: {array}, type: {array.type}\")\n\n# Perform a vectorized operation (e.g., multiply by 2)\nresult = array * 2\nprint(f\"Result of array * 2: {result}, type: {result.type}\")\n\n# Use a NumPy ufunc directly (works because of Awkward's NumPy-like behavior)\nsum_per_list = ak.sum(array, axis=1)\nprint(f\"Sum per list: {sum_per_list}, type: {sum_per_list.type}\")\n","lang":"python","description":"Demonstrates basic usage of the Awkward Array library, which internally utilizes `awkward-cpp` for efficient computation. Users typically interact with the `awkward` API, not `awkward-cpp` directly."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later (`requires_python: >=3.10` is specified on PyPI for awkward-cpp).","message":"As of `awkward` version 2.9.0 (and consequently `awkward-cpp` version 52 and later), Python 3.9 is no longer supported. Users must upgrade to Python 3.10 or newer.","severity":"breaking","affected_versions":"awkward-cpp >= 52 (corresponding to awkward >= 2.9.0)"},{"fix":"For GPU operations, ensure `cupy` is installed and use `ak.to_backend('cuda')` to move arrays to the GPU backend.","message":"awkward-cpp primarily provides CPU kernels. For GPU acceleration, `awkward` leverages CuPy and specific CUDA kernels. Users must explicitly use `ak.to_backend('cuda')` and ensure CuPy is installed if they intend to run operations on a GPU, as `awkward-cpp` does not handle GPU computation itself.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If the original data source is mutable and you need to ensure the Awkward Array remains unchanged by external modifications, create a deep copy: `my_awkward_array_copy = ak.copy(my_awkward_array)`.","message":"Awkward Arrays are designed to be immutable, meaning operations create new arrays rather than modifying existing ones in-place. However, if an Awkward Array is created from a mutable underlying data structure (like a NumPy array), modifying the original data structure in-place will also modify the Awkward Array referencing it. To prevent this, make an explicit deep copy using `ak.copy()`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use the `awkward` library for array creation and manipulation (`import awkward as ak`). `awkward-cpp` operates beneath this interface.","message":"While `awkward-cpp` is installable directly via pip, it is primarily a low-level dependency. Attempting to import or use it directly for high-level data manipulation will not work as it does not expose a public Python API for end-users. All high-level functionality is provided by the `awkward` library.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}