Getting started¶
Install¶
XBArray needs Python 3.10 or newer.
This installs NumPy, array-api-compat, array-api-extra and typing_extensions.
PyTorch and JAX are optional. Install them through the extras, or install them yourself:
pip install "xbarray[torch]" # adds torch
pip install "xbarray[jax]" # adds jax
pip install "xbarray[torch,jax]" # both
The extras install the default torch and jax packages from PyPI. For a CUDA build
of either library, follow the PyTorch or JAX install instructions, then install
xbarray.
A first example¶
Each backend is a class in xbarray.backends. Call Array API functions on it the way
you would call them on numpy or torch:
The three snippets differ only in the import. The arrays you get back are plain NumPy arrays, PyTorch tensors and JAX arrays. XBArray does not wrap them.
The ComputeBackend object¶
ComputeBackend is the interface that all three backends implement. The concrete
backends are:
| Backend | Import | str(backend) |
|---|---|---|
NumpyComputeBackend |
from xbarray.backends.numpy import NumpyComputeBackend |
numpy |
PyTorchComputeBackend |
from xbarray.backends.pytorch import PyTorchComputeBackend |
pytorch |
JaxComputeBackend |
from xbarray.backends.jax import JaxComputeBackend |
jax |
A backend is a class that you use directly. You never create an instance:
from xbarray.backends.numpy import NumpyComputeBackend
print(NumpyComputeBackend.simplified_name) # numpy
NumpyComputeBackend() # RuntimeError: NumpyComputeBackend is not meant to be instantiated. ...
Importing a backend module needs its library. xbarray.backends.pytorch imports
torch, and xbarray.backends.jax imports jax.
Getting the backend for an array¶
If you already have an array, get_backend_from_tensor returns the matching backend:
import numpy as np
from xbarray import get_backend_from_tensor
backend = get_backend_from_tensor(np.zeros(3))
print(backend) # numpy
It recognises numpy.ndarray, torch.Tensor and jax.Array, and raises ValueError
for anything else. It also works on JAX tracers inside jax.jit, since those are
jax.Array instances.
Type hints¶
ComputeBackend is generic over the array, device, dtype and random generator types.
Use it in annotations to say "any backend":
from xbarray import ComputeBackend, BArrayType
def double(backend: ComputeBackend, x: BArrayType) -> BArrayType:
return backend.multiply(x, 2)
See Generic typing for the type variables.
Next steps¶
- Concepts: what a backend contains, dtypes and devices, random numbers.
- Write backend-agnostic code: patterns and pitfalls.
- API reference: every function and signature.