xtensor-python

xtensor-python provides Python bindings for the xtensor C++ multi-dimensional array library. It allows for the in-place use of NumPy arrays within C++ code, enabling you to leverage xtensor's features directly on Python data structures.

Key capabilities include:

• C++ Universal Functions (ufuncs): Applying C++ scalar functions to NumPy arrays.
• Broadcasting: Using xtensor's broadcasting rules on NumPy arrays.
• STL Compliance: Providing APIs that are compliant with the C++ Standard Template Library.
• Seamless Interoperability: Using Python's Buffer Protocol via pybind11 to access NumPy data structures in C++ without exposing new types to Python.

The xtensor-python API provides specialized container types designed to bridge C++ xtensor arrays with Python's NumPy ecosystem. The primary container types available are:

• pyarray: Likely used for wrapping or interfacing with NumPy arrays.
• pytensor: Likely used for interfacing with xtensor tensors within a Python context.

Refer to the specific documentation for pyarray and pytensor for detailed method signatures and usage patterns.

To create a flexible C++ API that accepts various types but specifically allows xt::pyarray or xt::pytensor from Python, you can use SFINAE (Substitution Failure Is Not An Error).

This allows you to define a templated C++ function that works with standard xtensor types, while the Python bindings specifically target the xtensor-python wrappers. This ensures that when Python passes a NumPy array, it is treated as an xtensor without unnecessary overhead, while still allowing the C++ side to be type-safe and restricted to xtensor types.

template <class T>
void times_dimension(T& t);

xtensor-python provides two container types that wrap numpy arrays in-place to provide xtensor semantics. Both support numpy-style APIs.

• pyarray: Has a dynamic number of dimensions. Like numpy arrays, it can be reshaped with a shape of a different length, and the new shape is reflected on the Python side.
• pytensor: Has a compile-time number of dimensions specified via a template parameter. Shapes are stack-allocated, making pytensor significantly faster than pyarray for expression evaluation.

The xt::pyarray class is the core interface for working with NumPy arrays within C++. It allows you to wrap a NumPy array (from Python) into an xtensor object, enabling you to use xtensor's high-performance algorithms and expressions directly on data owned by Python/NumPy. This provides a seamless bridge between Python's memory management and C++'s computational power.

// Note: The specific API methods are documented via Doxygen in the source.
// Typically, you wrap a NumPy array like this:
// xt::pyarray<double> array = ...;

To build the documentation, you need doxygen, sphinx, and breathe. You can install breathe via pip or conda.

1. Install breathe: pip install breathe or conda install -c conda-forge breathe.
2. Navigate to the docs subdirectory.
3. Run make html.

# From the docs subdirectory
make html

You can build and install xtensor-python from source using CMake. All installation methods place the cmake project configuration file in the correct location, allowing third-party projects to locate the headers using find_package.

### Unix platforms
```bash
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/path/to/prefix ..
make install

Windows platforms

mkdir build
cd build
cmake -G "NMake Makefiles" -DCMAKE_INSTALL_PREFIX=/path/to/prefix ..
nmake
nmake install

When creating a self-contained extension module in a single C++ file, you must ensure the numpy C API is correctly imported to avoid linker errors.

1. Define FORCE_IMPORT_ARRAY before including any xtensor-python headers.
2. Call xt::import_numpy() within your module initialization function (e.g., inside the PYBIND11_MODULE block).

#define FORCE_IMPORT_ARRAY
#include "xtensor-python/pyarray.hpp"

PYBIND11_MODULE(plugin_name, m)
{
    xt::import_numpy();
    //...
}