{"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":"python","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,"search_vec":"'0.8.10':83 'abstract':1,14,96 'across':36 'activ':76 'agnost':25 'allow':61 'api':59 'array':3,15,38,90 'automat':31 'autoray':5,6 'backend':24,95 'backend-agnost':23 'cadenc':89 'code':27 'compil':71 'comput':67 'continu':87 'cupi':46 'current':80 'custom':64 'dask':47 'design':12 'dispatch':32,97 'enabl':19 'function':65 'interfac':72 'ish':58 'jax':44,92 'lazi':66 'librari':11,39,74 'lightweight':9 'long':51 'maintain':77 'mechan':33 'numer':26,98 'numpi':42,57,91 'numpy-ish':56 'oper':4,18 'provid':29,54 'python':10 'pytorch':43 'releas':88 'see':85 'swap':63 'tensor':17,99 'tensorflow':45,93 'torch':94 'trace':68 'unifi':70 'user':20 'various':37 'version':81 'work':35 'write':22","created_at":"2026-04-12T13:53:03.164583+00:00","updated_at":"2026-04-15T21:42:38.887418+00:00","problems":[{"fix":"Update the import statement to 'from ray.train import Checkpoint'.","cause":"The 'Checkpoint' class has been moved from 'ray.air' to 'ray.train' in newer versions of Ray.","error":"ImportError: cannot import name 'Checkpoint' from 'ray.air'"},{"fix":"Ensure the function is decorated with '@ray.remote' before calling its 'remote' method.","cause":"Attempting to call the 'remote' method on a function that has not been decorated with '@ray.remote'.","error":"AttributeError: 'function' object has no attribute 'remote'"},{"fix":"Verify the correct module path and ensure 'x' is defined in 'y'.","cause":"The module 'y' does not contain a definition for 'x', possibly due to a typo or incorrect module path.","error":"ImportError: cannot import name x from y"},{"fix":"Upgrade PennyLane to a compatible version (e.g., `pennylane>=0.29.1`) or downgrade Autoray to a version compatible with your PennyLane installation (e.g., `pip install autoray<0.8`).","cause":"This error often occurs when a newer version of Autoray (e.g., 0.8.x) is used with older versions of libraries like PennyLane (e.g., v0.29), leading to an incompatibility where Autoray expects an array-like object with an `ndim` attribute but receives a float.","error":"AttributeError: 'float' object has no attribute 'ndim'"},{"fix":"Upgrade the dependent library (e.g., PennyLane) to a version compatible with your Autoray installation, or if the issue persists, try downgrading Autoray to an earlier stable version known to work with your specific setup.","cause":"This error typically arises due to an incompatibility between Autoray versions (specifically around `autoray==0.8.0`) and dependent libraries like PennyLane, where the `NumpyMimic` class or attribute was moved or removed in Autoray, breaking the integration.","error":"AttributeError: module 'autoray.autoray' has no attribute 'NumpyMimic'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.11.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jcmgray/autoray","docs":"https://autoray.readthedocs.io/","changelog":"https://github.com/jcmgray/autoray/releases","pypi":"https://pypi.org/project/autoray/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}