Backends and the ComputeBackend interface¶
A backend is a class that bundles everything you need to work with one array library. XBArray ships three:
| Class | Module | simplified_name |
ARRAY_TYPE |
DEVICE_TYPE |
DTYPE_TYPE |
RNG_TYPE |
|---|---|---|---|---|---|---|
NumpyComputeBackend |
xbarray.backends.numpy |
"numpy" |
numpy.ndarray |
Any |
numpy.dtype |
numpy.random.Generator |
PyTorchComputeBackend |
xbarray.backends.pytorch |
"pytorch" |
torch.Tensor |
torch.device |
torch.dtype |
torch.Generator |
JaxComputeBackend |
xbarray.backends.jax |
"jax" |
jax.Array |
jax.Device or jax.sharding.Sharding |
numpy.dtype |
jax.Array (a PRNG key) |
The ARRAY_TYPE, DEVICE_TYPE, DTYPE_TYPE and RNG_TYPE columns are class
attributes. You can use them for isinstance checks or in your own type hints.
Backends are used as classes. Their methods are plain functions, so there is no
self and nothing to instantiate. Calling NumpyComputeBackend() raises
RuntimeError. str() and repr() of a backend return its simplified_name.
What a backend contains¶
A backend's attributes come from four places.
1. The Array API namespace. All functions and constants of the
Array API Standard:
array creation (zeros, arange, asarray, ...), element-wise math, matmul,
where, sort, argsort, the linalg and fft extensions, dtype objects such as
float32, and __array_api_version__. NumPy and PyTorch get these from
array_api_compat.numpy and array_api_compat.torch. JAX uses jax.numpy, or
jax.experimental.array_api on older JAX versions.
2. array-api-compat helpers. device(x), to_device(x, device), size(x),
array_namespace(*xs), is_array_api_obj(x) and the is_*_array checks.
3. array-api-extra functions. Every public function of
array-api-extra, bound to the backend's
namespace so you do not pass xp=. Examples are at, isclose, pad, one_hot,
nunique, cov, kron, sinc, expand_dims and apply_where. The exact set
depends on the installed array-api-extra version. Where a name exists in both the
namespace and array-api-extra, the array-api-extra version is the one on the backend.
4. XBArray extras. The parts the standard does not cover:
| Attribute | What it does | Page |
|---|---|---|
simplified_name |
"numpy", "pytorch" or "jax" |
|
default_integer_dtype, default_index_dtype, default_floating_dtype, default_boolean_dtype |
Dtypes to use when you need one | Devices and dtypes |
dtype_is_real_integer, dtype_is_real_floating, dtype_is_boolean |
Dtype predicates | Devices and dtypes |
serialize_device, deserialize_device |
Device to and from a string | Devices and dtypes |
random |
Random number functions | Random number generation |
is_backendarray, from_numpy, to_numpy, from_other_backend, to_dlpack |
Conversion | Converting between backends |
map_fn_over_arrays, map_fn_over_arrays_ex |
Apply a function to every array in nested data | Converting between backends |
pad_dim |
Pad one axis to a target size with a constant | below |
abbreviate_array |
Collapse an array whose elements are all equal to a Python scalar | API reference |
The NumPy backend also overrides clip with a faster version that keeps the Array API
behaviour: the result has the dtype of x, and NaN propagates.
The ComputeBackend protocol¶
xbarray.ComputeBackend is a typing.Protocol that lists the attributes above. The
three backend classes satisfy it. Your code should accept a ComputeBackend and call
functions on it, rather than importing a specific backend:
from xbarray import ComputeBackend
def center(backend: ComputeBackend, x):
return x - backend.mean(x, axis=0, keepdims=True)
Random functions have their own protocol, xbarray.RNGBackend. It is the type of
backend.random.
Choosing a backend¶
Import the class you want:
from xbarray.backends.numpy import NumpyComputeBackend
from xbarray.backends.pytorch import PyTorchComputeBackend
from xbarray.backends.jax import JaxComputeBackend
Or find it from an existing array:
import torch
from xbarray import get_backend_from_tensor
backend = get_backend_from_tensor(torch.ones(2))
print(backend) # pytorch
Importing xbarray itself does not require PyTorch or JAX. get_backend_from_tensor
only checks the libraries that import successfully. Any error while importing one,
not only ImportError, makes that backend unavailable.
Older import paths
xbarray.numpy, xbarray.pytorch and xbarray.jax re-export the backend
classes for code written before version 0.0.1a9. New code should import from
xbarray.backends.*. The PyTorch class was renamed from PytorchComputeBackend
to PyTorchComputeBackend in 0.0.1a14.
Updating arrays without in-place writes¶
JAX arrays are immutable, so x[i] = v fails on the JAX backend. Use at from
array-api-extra. By default it may write into x (NumPy, PyTorch) or return a new
array (JAX):
from xbarray.backends.jax import JaxComputeBackend as backend
x = backend.zeros(4)
x = backend.at(x, 1).set(5.0)
x = backend.at(x, 2).add(1.0)
print(x) # [0. 5. 1. 0.]
Assign the result back, as above, and do not reuse the old x. Pass copy=True to
set/add/... if the input must stay unchanged; see the
array-api-extra docs.
Padding one axis¶
pad_dim(x, dim, target_size, value=0) appends constant values along one axis until it
has target_size entries. It returns x unchanged if the axis is already that size,
and raises ValueError if it is larger.