xtensor-blas

xtensor-blas is an extension for the xtensor library that provides bindings to BLAS and LAPACK libraries via cxxblas and cxxlapack (from the FLENS project).

It provides two main levels of access:

1. High-level linear algebra operations: Located in the xt::linalg namespace, these functions aim for 1-to-1 equivalence with NumPy. Supported operations include dot, norm (1- and 2-norm for vectors), inverse, solve, eig, cross, det, slogdet, matrix_rank, inv, cholesky, qr, and svd.
2. Low-level interfaces: Located in the blas and lapack namespaces, these allow direct interfacing with BLAS or LAPACK using xtensor containers.

xtensor-blas provides high-level linear algebra functions in the xt::linalg namespace. These functions are designed to be 1-to-1 equivalent to NumPy signatures.

Available high-level functions include:

• dot
• norm (1- and 2-norm for vectors)
• inverse / inv
• solve
• eig
• cross
• det
• slogdet
• matrix_rank
• cholesky
• qr
• svd

For low-level interfacing directly with BLAS or LAPACK using xtensor containers, use the blas and lapack namespaces. Detailed function signatures can be found in the xlinalg.hpp header.

While xt::linalg is the recommended high-level interface, you can use xblas or xlapack directly for potential performance gains. If you choose this route, you must satisfy the following requirements:

1. Pre-allocation: The result container must be allocated and passed into the function beforehand.
2. Memory Layout: For LAPACK functions, all arguments must be in column_major order.
3. Contiguity: All xexpressions must be evaluated and stored in contiguous memory.

xt::linalg handles these requirements automatically.

If you are not using CMake, you can manually pass the necessary flags to your compiler (e.g., g++). You must define -DHAVE_CBLAS=1 and link the -lblas and -llapack libraries.

g++ test.cpp -o test -lblas -llapack -DHAVE_CBLAS=1

You can install xtensor-blas using the mamba or conda package manager from the conda-forge channel. This will also automatically install the required xtensor package.

Alternatively, you can install it from source using CMake.

Note: To use the library or run tests, you must have openblas and lapack binaries installed on your system (also available via conda-forge).

# Using mamba or conda
mamba install -c conda-forge xtensor-blas

# Using CMake from source
cmake -D CMAKE_INSTALL_PREFIX=your_install_prefix
make install

To build and install xtensor-blas from source, you must have a BLAS implementation (such as OpenBLAS or MKL) already installed on your system. Even though xtensor-blas is a header-only library, these installation methods ensure that the cmake project configuration files are placed correctly so that other projects can find the headers using find_package.

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

On Windows platforms

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

To achieve optimal performance with xtensor-blas, your target program must be linked against a BLAS (Basic Linear Algebra Subprograms) and LAPACK implementation.

• Conda users: The default installation uses OpenBLAS, though MKL is also available.
• Manual installation: You must manually verify that a BLAS and LAPACK implementation is available on your system.
• Fallback mode: If you cannot provide a high-performance BLAS, you can fallback to a slower, more generic implementation by defining -DXTENSOR_USE_FLENS_BLAS at compile time.

To use xtensor-blas, you must use a modern C++ compiler that supports the C++14 standard.

Supported compilers include:

• Windows: Visual C++ 2015 Update 2 or more recent.
• Unix: gcc 4.9 or a recent version of Clang.

You can install xtensor-blas using the mamba or conda package manager from the conda-forge channel.

mamba install -c conda-forge xtensor-blas

If you are using CMake and want to link against OpenBLAS, add the following configuration to your CMakeLists.txt. This setup handles Windows specifically by searching for OpenBLAS, while on other platforms it uses the standard BLAS and LAPACK packages.

add_definitions(-DHAVE_CBLAS=1)

if (WIN32)
    find_package(OpenBLAS REQUIRED)
    set(BLAS_LIBRARIES ${CMAKE_INSTALL_PREFIX}${OpenBLAS_LIBRARIES})
else()
    find_package(BLAS REQUIRED)
    find_package(LAPACK REQUIRED)
endif()

message(STATUS "BLAS VENDOR:    " ${BLA_VENDOR})
message(STATUS "BLAS LIBRARIES: " ${BLAS_LIBRARIES})

target_link_libraries(your_target_name ${BLAS_LIBRARIES} ${LAPACK_LIBRARIES})

The xt::linalg namespace provides implementations of many NumPy np.linalg functions. To use these functions, include the xtensor-blas/xlinalg.hpp header. The interfaces are designed to be very similar to NumPy's.

#include "xtensor-blas/xlinalg.hpp"

int main()
{
    xt::xarray<double> a = {{3, 2, 1}, {0, 4, 2}, {1, 3, 5}};
    auto d = xt::linalg::det(a);
    std::cout << d << std::endl;  // 42.0
}