xtensor

In xtensor, containers are in-memory expressions that implement the xexpression API. While the primary user-facing classes are xt::xarray and xt::xtensor (which handle constructors and value semantics), the core functionality of the xexpression API is implemented in the underlying xstrided_container and xcontainer classes.

Views (such as xview, xstrided_view, etc.) allow for non-owning manipulations of data, whereas containers like xarray own the underlying data.

xtensor provides specialized bindings to wrap native arrays from other languages into xtensor containers, allowing for in-place modification and reshapes:

• Python: Use xtensor-python to get pyarray and pytensor containers which wrap NumPy arrays. It also includes utilities to generate NumPy-style universal functions from scalar functions.
• Julia: Use xtensor-julia to get jlarray and jltensor containers which wrap Julia arrays. It includes utilities to generate NumPy-style universal functions.
• R: Use xtensor-r to get rarray and rtensor containers which wrap R arrays. It includes utilities to generate NumPy-style universal functions.

xtensor uses lazy evaluation. Operations like x + y do not return a container, but an expression that holds references, const references, or copies of the operands. These operands are called closure types.

To avoid dangling references:

• When an argument is an rvalue, the closure type is a value (the rvalue is moved).
• When an argument is an lvalue reference, the closure type is a reference to that type.

If you want to avoid the complexities of lazy evaluation and closure semantics, you can use xt::eval() to return an evaluated container instead of an expression.

Extend xtensor functionality using these specialized library bindings:

• Linear Algebra: Use xtensor-blas to provide bindings to BLAS libraries, enabling linear-algebra operations directly on xtensor expressions.
• File I/O: Use xtensor-io to load various file formats into xtensor expressions, including image files, sound files, HDF5 files, and NumPy .npy and .npz files.

Most expressions in xtensor are lazy-evaluated, meaning they do not hold values immediately. Instead, they represent a node in an expression tree that computes values only upon access or when assigned to a container.

Nodes in the tree are often represented by the xfunction template class, which stores:

1. A functor describing the mathematical operation.
2. The closures of the child expressions (the most optimal way to store each child, such as constant references or moved rvalues).

Beyond the standard iterators provided by expression types, xtensor provides specialized iterator classes designed to iterate over slices of an expression along a specific axis. This allows for more granular control when traversing multidimensional data structures. The available iterator types include:

• xaxis_iterator: For iterating over elements along a specific axis.
• xaxis_slice_iterator: For iterating over slices along a specific axis.

xtensor provides several container types depending on whether you need dynamic or static shapes:

• xarray<T>: A tensor that can be reshaped to any number of dimensions (dynamic shape).
• xtensor<T, N>: A tensor where the number of dimensions N is fixed at compile time.
• xtensor_fixed<T, xshape<I, J, K>>: A tensor where both the number of dimensions and the specific shape are fixed at compile time.
• xchunked_array<CS>: A chunked array using the specified CS chunk storage.

Most methods described in the documentation apply to xarray, xtensor, and xtensor_fixed unless otherwise specified.

Windows users must activate the /bigobj flag to prevent compilation failures. For optimization, it is recommended to link against xtensor::optimize and disable the manifest.

If XTENSOR_USE_XSIMD is enabled, you must also specify a target instruction set (e.g., /arch:AVX2, /arch:AVX, or /arch:ARMv7VE).

target_link_libraries(... xtensor xtensor::optimize)
set(CMAKE_EXE_LINKER_FLAGS /MANIFEST:NO)

# OR

target_compile_options(target_name PRIVATE /EHsc /MP /bigobj)
set(CMAKE_EXE_LINKER_FLAGS /MANIFEST:NO)

# If using XSIMD, specify instruction set:
target_compile_options(target_name PRIVATE /arch:AVX2)

Use xt::load_npy to load data from a .npy file and xt::dump_npy to save xtensor data to a .npy file. When calling xt::load_npy, you must provide the template argument for the data type being loaded.

#include <istream>
#include <iostream>
#include <fstream>

#include <xtensor/containers/xarray.hpp>
#include <xtensor/io/xnpy.hpp>

int main()
{
    // Note: you need to supply the data type you are loading
    //       in this case "double".
    auto data = xt::load_npy<double>("in.npy");

    xt::xarray<double> a = {{1,2,3,4}, {5,6,7,8}};
    xt::dump_npy("out.npy", a);

    return 0;
}