Write backend-agnostic code¶
This guide builds one function that runs on NumPy, PyTorch and JAX, and lists the rules that keep it that way.
The pattern¶
Take the backend as the first argument and call everything through it:
from typing import Optional, Tuple
from xbarray import ComputeBackend, BArrayType, BDeviceType, BDtypeType, BRNGType
def augment(
backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
points: BArrayType, # (..., N, 3)
rng: BRNGType,
noise_std: float = 0.01,
max_shift: float = 0.1,
) -> Tuple[BRNGType, BArrayType]:
"""Add per-point noise and one random shift per point cloud."""
device = backend.device(points)
rng, noise = backend.random.random_normal(
points.shape, rng=rng, std=noise_std, dtype=points.dtype, device=device
)
shift_shape = (*points.shape[:-2], 1, 3)
rng, shift = backend.random.random_uniform(
shift_shape, rng=rng, low=-max_shift, high=max_shift, dtype=points.dtype, device=device
)
return rng, points + noise + shift
Run it on each backend:
The JAX version runs under jax.jit. The backend is an ordinary Python object, so it
can be closed over. The array and the key are traced arguments.
Binding the backend¶
If callers always use one backend, bind it with functools.partial. This is how
xbarray.transformations.pointcloud.numpy and its siblings are built from the generic
functions in ...pointcloud.base:
from functools import partial
from xbarray.backends.numpy import NumpyComputeBackend
augment_numpy = partial(augment, NumpyComputeBackend)
To pick the backend from the input instead, use get_backend_from_tensor:
from xbarray import get_backend_from_tensor
def augment_any(points, rng, **kwargs):
return augment(get_backend_from_tensor(points), points, rng, **kwargs)
Rules¶
Call functions on the backend, not methods on the array. Array methods differ
between libraries: x.astype(dtype) exists on NumPy and JAX arrays but not on
PyTorch tensors. backend.astype(x, dtype) works everywhere. Operators such as +,
*, @, < and basic indexing like x[..., :3] are fine.
Do not write into arrays. x[i] = v and x += y on a slice fail on JAX. Build a
new array with backend.where, backend.concat or backend.stack, or use
backend.at(x, i).set(v) and keep the result.
Take dtypes and devices from the inputs. Create new arrays with
dtype=x.dtype, device=backend.device(x). Otherwise a NumPy default (float64) and a
PyTorch default (float32) give different results, and PyTorch fails when arrays sit
on different devices.
Use default_index_dtype for indices. take_along_axis on PyTorch only accepts
int64 indices, and default_integer_dtype is int32 on PyTorch.
Thread the generator. Accept rng, use the one returned by each draw, and return
it. See Random number generation.
Use only Array API names. Library-specific functions such as np.einsum or
torch.cdist are not on the backend. Check the
Array API specification
and array-api-extra for what is.
Keep host round trips out of hot paths. float(x), int(x) and to_numpy copy
to the host and synchronize with the GPU. Under jax.jit they fail on traced values.
Testing on every backend¶
The XBArray test suite runs each test once per installed backend with a parametrised pytest fixture. You can do the same in your own project:
import importlib
import pytest
_BACKENDS = {
"numpy": ("xbarray.backends.numpy", "NumpyComputeBackend", "numpy"),
"pytorch": ("xbarray.backends.pytorch", "PyTorchComputeBackend", "torch"),
"jax": ("xbarray.backends.jax", "JaxComputeBackend", "jax"),
}
@pytest.fixture(params=list(_BACKENDS))
def backend(request):
module_name, cls_name, requirement = _BACKENDS[request.param]
pytest.importorskip(requirement)
return getattr(importlib.import_module(module_name), cls_name)
def test_augment_keeps_shape(backend):
rng = backend.random.random_number_generator(0)
points = backend.zeros((4, 10, 3), dtype=backend.float32)
rng, out = augment(backend, points, rng)
assert tuple(out.shape) == (4, 10, 3)
assert out.dtype == backend.float32
Backends whose library is not installed are skipped.