Python bindings for the xtensor C++ multi-dimensional array library.

xtensor is a C++ library for multi-dimensional arrays enabling numpy-style broadcasting and lazy computing.
xtensor-python enables inplace use of numpy arrays in C++ with all the benefits from xtensor
- C++ universal function and broadcasting
- STL - compliant APIs.
- A broad coverage of numpy APIs (see the numpy to xtensor cheat sheet).

The Python bindings for xtensor are based on the pybind11 C++ library, which enables seamless interoperability between C++ and Python.

Installation

xtensor-python is a header-only library. We provide a package for the mamba (or conda) package manager.

mamba install -c conda-forge xtensor-python

Documentation

To get started with using xtensor-python, check out the full documentation

http://xtensor-python.readthedocs.io/

Usage

xtensor-python offers two container types wrapping numpy arrays inplace to provide an xtensor semantics

pytensor
pyarray.

Both containers enable the numpy-style APIs of xtensor (see the numpy to xtensor cheat sheet).

On the one hand, pyarray has a dynamic number of dimensions. Just like numpy arrays, it can be reshaped with a shape of a different length (and the new shape is reflected on the python side).
On the other hand pytensor has a compile time number of dimensions, specified with a template parameter. Shapes of pytensor instances are stack allocated, making pytensor a significantly faster expression than pyarray.

Example 1: Use an algorithm of the C++ standard library on a numpy array inplace.

C++ code

#include <numeric>                        // Standard library import for std::accumulate
#include <pybind11/pybind11.h>            // Pybind11 import to define Python bindings
#include <xtensor/core/xmath.hpp>              // xtensor import for the C++ universal functions
#define FORCE_IMPORT_ARRAY
#include <xtensor-python/pyarray.hpp>     // Numpy bindings

double sum_of_sines(xt::pyarray<double>& m)
{
    auto sines = xt::sin(m);  // sines does not actually hold values.
    return std::accumulate(sines.begin(), sines.end(), 0.0);
}

PYBIND11_MODULE(xtensor_python_test, m)
{
    xt::import_numpy();
    m.doc() = "Test module for xtensor python bindings";

    m.def("sum_of_sines", sum_of_sines, "Sum the sines of the input values");
}

Python Code

import numpy as np
import xtensor_python_test as xt

v = np.arange(15).reshape(3, 5)
s = xt.sum_of_sines(v)
print(s)

Outputs

1.2853996391883833

Working example

Get the working example here:

Example 2: Create a universal function from a C++ scalar function

C++ code

#include <pybind11/pybind11.h>
#define FORCE_IMPORT_ARRAY
#include <xtensor-python/pyvectorize.hpp>
#include <numeric>
#include <cmath>

namespace py = pybind11;

double scalar_func(double i, double j)
{
    return std::sin(i) - std::cos(j);
}

PYBIND11_MODULE(xtensor_python_test, m)
{
    xt::import_numpy();
    m.doc() = "Test module for xtensor python bindings";

    m.def("vectorized_func", xt::pyvectorize(scalar_func), "");
}

Python Code

import numpy as np
import xtensor_python_test as xt

x = np.arange(15).reshape(3, 5)
y = [1, 2, 3, 4, 5]
z = xt.vectorized_func(x, y)
print(z)

Outputs

[[-0.540302,  1.257618,  1.89929 ,  0.794764, -1.040465],
 [-1.499227,  0.136731,  1.646979,  1.643002,  0.128456],
 [-1.084323, -0.583843,  0.45342 ,  1.073811,  0.706945]]

Installation

We provide a package for the conda package manager.

conda install -c conda-forge xtensor-python

This will pull the dependencies to xtensor-python, that is pybind11 and xtensor.

Project cookiecutter

A template for a project making use of xtensor-python is available in the form of a cookiecutter here.

This project is meant to help library authors get started with the xtensor python bindings.

It produces a project following the best practices for the packaging and distribution of Python extensions based on xtensor-python, including a setup.py file and a conda recipe.

Building and Running the Tests

Testing xtensor-python requires pytest

py.test .

To pick up changes in xtensor-python while rebuilding, delete the build/ directory.

Building the HTML Documentation

xtensor-python's documentation is built with three tools

While doxygen must be installed separately, you can install breathe by typing

pip install breathe

Breathe can also be installed with conda

conda install -c conda-forge breathe

Finally, build the documentation with

make html

from the docs subdirectory.

Dependencies on `xtensor` and `pybind11`

xtensor-python depends on the xtensor and pybind11 libraries

`xtensor-python`	`xtensor`	`pybind11`
master	^0.26.0	>=2.6.1,<3
0.28.0	^0.26.0	>=2.6.1,<3
0.27.0	^0.25.0	>=2.6.1,<3
0.26.1	^0.24.0	~2.4.3
0.26.0	^0.24.0	~2.4.3
0.25.3	^0.23.0	~2.4.3
0.25.2	^0.23.0	~2.4.3
0.25.1	^0.23.0	~2.4.3
0.25.0	^0.23.0	~2.4.3
0.24.1	^0.21.2	~2.4.3
0.24.0	^0.21.1	~2.4.3

These dependencies are automatically resolved when using the conda package manager.

License

We use a shared copyright model that enables all contributors to maintain the copyright on their contributions.

This software is licensed under the BSD-3-Clause license. See the LICENSE file for details.