array-api-extra¶

This is a library housing extra array functions built on top of the Python array API standard.

The intended users of this library are “array-consuming” libraries which are using array-api-compat to make their own library’s functions array-agnostic. In this library, they will find a set of tools which provide extra functionality on top of the array API standard, which other array-consuming libraries in a similar position have themselves found useful.

It is currently used by:

SciPy — Fundamental algorithms for scientific computing.
scikit-learn — Machine Learning in Python.
pyRiemann — Machine learning for multivariate data through the Riemannian geometry of positive definite matrices.
SysIdentPy — System Identification Using NARMAX Models.
bilby — A unified framework for stochastic sampling packages and gravitational-wave inference.
ccdproc — Astropy affiliated package for reducing optical/IR CCD data.
GLASS — Generator for Large Scale Structure.
ASPIRE — Accelerated Sequential Posterior Inference via REuse.
your library? Let us know!

Installation¶

array-api-extra is available on PyPI:

uv add array-api-extra

And on conda-forge:

pixi add array-api-extra

Note

This library depends on array-api-compat. We aim for compatibility with the latest released versions of the standard and array-api-compat, and your mileage may vary with older versions.

Versioning¶

This project uses EffVer.

To bump from version x.y.z to x.(y+1).0 of array-api-extra, expect that you may need to put in some work.
To bump from version x.y.z to x.y.(z+1), any work needed on your side should be minimal. Please open an issue if this is not the case!

Usage¶

Typical usage of this library looks like:

import array_api_extra as xpx

...
xp = array_namespace(x)
y = xp.sum(x)  # use functions from `xp` as normal
...
return xpx.atleast_nd(y, ndim=2, xp=xp)  # use functions from `xpx`, passing `xp=xp`

Note

Functions in this library assume input arrays are arrays (not “array-likes”) and that the namespace passed as xp (if given) is compatible with the standard - in most cases, it should come from array-api-compat’s array_namespace. Calling functions without providing an xp argument means that array_namespace is called internally on the input arrays to determine the namespace.

In the examples shown in the docstrings of functions from this library, array-api-strict is used as the array namespace xp. In reality, code using this library will be written to work with any compatible array namespace as xp, not any particular implementation.

Some functions may only work with specific array libraries supported by array-api-compat. This should be clearly indicated in the docs - please open an issue if this is not the case!

Vendoring¶

If stability is important for your library, it is recommended to either pin array-api-extra to a specific (micro or meso) version, or vendor array-api-extra inside your library.

To achieve the latter, clone the array-api-extra repository and copy it into the appropriate place in your library, like:

cp -a array-api-extra/src/array_api_extra mylib/vendored/

You may either add a dependency to array-api-compat in your own project, or vendor it too:

Clone the array-api-compat repository and copy it next to your vendored array-api-extra:
```
cp -a array-api-compat/array_api_compat mylib/vendored/
```
Create a new hook file which array-api-extra will use instead of the top-level array-api-compat if present:
```
echo 'from mylib.vendored.array_api_compat import *' > mylib/vendored/_array_api_compat_vendor.py
```

This also allows overriding array-api-compat functions if you so wish. E.g. your mylib/vendored/_array_api_compat_vendor.py could look like this:

from mylib.vendored.array_api_compat import *
from mylib.vendored.array_api_compat import array_namespace as _array_namespace_orig


def array_namespace(*xs, **kwargs):
    import mylib

    if any(isinstance(x, mylib.MyArray) for x in xs):
        return mylib
    else:
        return _array_namespace_orig(*xs, **kwargs)

Tip

See an example of this in SciPy.