{"id":4447,"library":"autoray","title":"Abstract your array operations (autoray)","description":"Autoray is a lightweight Python library designed to abstract array and tensor operations, enabling users to write backend-agnostic numeric code. It provides an automatic dispatch mechanism that works across various array libraries such as NumPy, PyTorch, JAX, TensorFlow, CuPy, Dask, and more, as long as they provide a NumPy-ish API. This allows for swapping custom functions, lazy computation tracing, and unified compilation interfaces. The library is actively maintained, with its current version being 0.8.10, and sees a continuous release cadence.","status":"active","version":"0.8.10","language":"en","source_language":"en","source_url":"https://github.com/jcmgray/autoray/","tags":["array","numpy","jax","tensorflow","torch","backend abstraction","dispatch","numeric","tensor"],"install":[{"cmd":"pip install autoray","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Commonly used backend for array operations.","package":"numpy","optional":true},{"reason":"Commonly used backend for deep learning tensor operations.","package":"torch","optional":true},{"reason":"Commonly used backend for high-performance numerical computation.","package":"jax","optional":true},{"reason":"Commonly used backend for deep learning tensor operations.","package":"tensorflow","optional":true}],"imports":[{"note":"The most common and recommended way to import autoray, typically aliased as `ar` for convenience, to access functions like `ar.do` or `ar.get_namespace`.","symbol":"autoray","correct":"import autoray as ar"},{"note":"Imports a NumPy-like API that dispatches through autoray, allowing for a drop-in replacement for existing NumPy code.","symbol":"numpy","correct":"from autoray import numpy as np"},{"note":"While `ar.do` is preferred with the alias, `do` can be imported directly. `autoray.do` is not the correct import path for the function itself.","wrong":"import autoray.do","symbol":"do","correct":"from autoray import do"}],"quickstart":{"code":"import autoray as ar\nimport numpy as np\n\n# Basic usage with automatic dispatch (inferred from array type)\nx_np = np.random.uniform(size=)\ny_np = ar.do('sqrt', x_np)\nprint(f\"Numpy sqrt: {y_np}, type: {type(y_np)}\")\n\n# Using 'like' argument for explicit backend or inference\n# If torch is not installed, this will silently fall back to numpy behavior\n# For full torch functionality, ensure 'torch' is installed.\nx_torch_like = ar.do('random.uniform', size=(10, 10), like=\"torch\")\nprint(f\"Array generated with 'like=\"torch\"': {type(x_torch_like)}\")\n\n# Using get_namespace for a backend-specific API (Python Array API style)\ntry:\n    # Attempt to get a torch namespace\n    xp = ar.get_namespace(like=\"torch\") # Requires 'torch' to be installed for actual torch arrays\n    z = xp.ones((3, 4), dtype=xp.float32)\n    result = xp.exp(z)\n    print(f\"Torch-like exp result shape: {result.shape}, type: {type(result)}\")\nexcept (ImportError, TypeError):\n    # Fallback if torch is not installed, get numpy namespace\n    xp = ar.get_namespace(like=\"numpy\")\n    z = xp.ones((3, 4), dtype=xp.float32)\n    result = xp.exp(z)\n    print(f\"Numpy-like exp result shape (fallback): {result.shape}, type: {type(result)}\")\n\n# Example of a more complex operation with automatic dispatch\ndef noised_svd(x):\n    U, s, VH = ar.do('linalg.svd', x)\n    sn = s + 0.1 * ar.do('random.normal', size=ar.shape(s), like=s)\n    return ar.do('einsum', 'ij,j,jk->ik', U, sn, VH)\n\n# Use a numpy array for demonstration\nx_complex_op = np.random.rand(10, 10)\ny_complex_op = noised_svd(x_complex_op)\nprint(f\"Complex operation result shape: {y_complex_op.shape}\")\n","lang":"python","description":"This quickstart demonstrates the core functionalities of `autoray`: automatic backend dispatch using `ar.do()`, explicit backend selection with the `like` argument, and obtaining a backend-specific API using `ar.get_namespace()`. It also shows how to define a function that works generically across different array backends."},"warnings":[{"fix":"Review any code iterating directly over `LazyArray` instances and adapt it to the new slicing behavior or use `LazyArray.nodes` if access to graph nodes is explicitly required.","message":"The iteration behavior of `LazyArray.__iter__` changed in version `0.8.0`. It now iterates over slices of the array rather than the computational graph nodes, which can break code relying on previous lazy graph inspection.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Upgrade your Python environment to version 3.10 or newer, or pin `autoray` to a version less than `0.8.3` if an upgrade is not feasible.","message":"The minimum required Python version was bumped to `3.10` in version `0.8.3`. Users on older Python versions (e.g., 3.9 or earlier) will need to upgrade their Python environment to use `autoray` versions `0.8.3` and higher.","severity":"breaking","affected_versions":">=0.8.3"},{"fix":"Always explicitly specify `full_matrices=True` or `full_matrices=False` when calling `ar.do('linalg.svd', ...)` to ensure consistent behavior across backends and avoid surprises, aligning with the desired output.","message":"When using `autoray.do('linalg.svd', x)`, the `full_matrices` argument defaults to `False`. This differs from NumPy's default behavior, where `full_matrices` is `True`. This can lead to unexpected output shapes if not explicitly handled.","severity":"gotcha","affected_versions":"all"},{"fix":"Familiarize yourself with the `autoray` documentation regarding backend deviations and translations, especially when encountering unexpected results or performance characteristics with specific backend libraries. For critical operations, consider direct backend calls if fine-grained control is necessary.","message":"Autoray performs internal translations for certain functions to match backend-specific APIs (e.g., NumPy's `sum` becomes TensorFlow's `tf.reduce_sum`). While designed for compatibility, these implicit translations can lead to subtle differences in behavior or performance if not fully understood.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}