DOCSEARCHbyAlgolia
Submit Docs

OpenBLAS Documentation

repository·develop·Indexed 27 days ago

https://github.com/openmathlib/openblas

An optimized BLAS (Basic Linear Algebra Subprograms) library based on GotoBLAS2 with LAPACK support. This documentation covers building from source for various CPU architectures (x86_64, ARMV8, POWER, ZARCH, riscv64, LoongArch64), configuring thread counts, linking the library to applications, and running the pytest-benchmark suite. It also includes installation guides for LAPACK via make, CMake, and vcpkg, as well as troubleshooting for JVM integration and compiler requirements.

Tokens
15.7K
Snippets
44
Records
128
Agent score
92%

What's inside OpenBLAS

  1. Overview of OpenBLAS

    develop

    OpenBLAS is an optimized Basic Linear Algebra Subprograms (BLAS) library based on the GotoBLAS2 1.13 BSD version. It provides low-level routines for linear algebra operations, including:

    • Vector addition
    • Scalar multiplication
    • Dot products
    • Linear combinations
    • Matrix multiplication

    OpenBLAS is designed for high performance across multiple platforms (server, desktop, and mobile) and supports various architectures including x86, ARM, MIPS, PPC, RISC-V, and zarch.

  2. Understand the OpenBLAS source code layout

    develop

    The OpenBLAS repository is organized into several functional directories:

    • benchmark: Benchmark codes for BLAS.
    • cmake: CMake configuration files.
    • ctest: Test codes for CBLAS interfaces.
    • driver: Implementation of BLAS levels (level2, level3), memory management, and threading.
    • exports: Logic to generate shared libraries.
    • interface: Implementation of BLAS and CBLAS interfaces (calling drivers or kernels). Includes lapack and netlib subdirectories.
    • kernel: Optimized assembly kernels for specific CPU architectures (e.g., arm, arm64, ia64, riscv64, x86, x86_64).
    • lapack: Optimized LAPACK codes.
    • lapack-netlib: LAPACK codes from the netlib reference implementation.
    • relapack: Recursive LAPACK implementation.
    • test: Test codes for BLAS.
    • utest: Regression tests.

  3. Use ReLAPACK in existing applications

    develop
    ReLAPACK preserves established LAPACK interfaces, allowing it to be integrated into existing application code as a replacement for certain LAPACK compute kernels. Any existing LAPACK example involving covered routines can be used directly with ReLAPACK.

  4. Distribution models for OpenBLAS

    develop

    OpenBLAS is typically distributed using one of the following three models:

    1. Standalone Packages: Distributed via packaging ecosystems such as Linux distributions (Fedora, Debian), Homebrew, conda-forge, or MSYS2.
    2. Vendored: Included as a component within a larger software package, such as Julia, NumPy, SciPy, or R.
    3. Local/HPC: Built and made available locally on specific environments like High-Performance Computing (HPC) clusters.

  5. Compile OpenBLAS with IBM MASS support on Power CPU

    develop
    To use IBM MASS (Mathematical Acceleration Subsystem) for optimized performance on POWER architectures, you must first install the libxlmass-devel library on a 64-bit, little-endian OS. After installation, compile OpenBLAS with USE_MASS=1.

  6. Link to OpenBLAS shared library

    develop

    To link against the shared library (typically libopenblas.so), use the -lopenblas flag. You will also need to provide the include path with -I and the library path with -L.

    To avoid runtime errors like cannot open shared object file, use the -Wl,-rpath flag to specify the library location, or ensure the path is in LD_LIBRARY_PATH or a system search path.

    Common additional flags:

    • -lpthread: If the library is multi-threaded.
    • -lgfortran: If the library contains LAPACK functions (unless only using LAPACKE routines).

    You can use pkg-config to automatically retrieve these flags.

    gcc -o test test.c -I/your_path/OpenBLAS/include/ -L/your_path/OpenBLAS/lib -Wl,-rpath,/your_path/OpenBLAS/lib -lopenblas

  8. Build ILP64 interface using the current OpenBLAS convention

    develop

    The current agreed-upon convention for ILP64 builds uses the symbol suffix 64_. This results in library names like libopenblas64_.so and symbols ending in 64_. This prevents clashes when both LP64 and ILP64 libraries are loaded simultaneously.

    Using Make: Use INTERFACE64=1 and SYMBOLSUFFIX=64_.

    Using CMake: Use -DINTERFACE64=1 and -DSYMBOLSUFFIX=64_. Note that CMake may produce library names ending in _64 instead of 64_; it is recommended to rename them to match the Make convention and update the libsuffix in the .pc file.

    # Using Make
make INTERFACE64=1 SYMBOLSUFFIX=64_

# Using CMake
mkdir build && cd build
cmake .. -DINTERFACE64=1 -DSYMBOLSUFFIX=64_ -DBUILD_SHARED_LIBS=ON -DBUILD_STATIC_LIBS=ON
cmake --build . -j

  10. Build OpenBLAS for Cortex-M (Embedded)

    develop

    To build OpenBLAS for Cortex-M (e.g., STM32F4xx), use the Arm GCC compiler and a custom toolchain.cmake file.

    1. Create toolchain.cmake:

    set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(CMAKE_C_COMPILER "arm-none-eabi-gcc.exe")
set(CMAKE_CXX_COMPILER "arm-none-eabi-g++.exe")
set(CMAKE_EXE_LINKER_FLAGS "--specs=nosys.specs" CACHE INTERNAL "")
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

    2. Build:

    cmake .. -G Ninja -DCMAKE_C_COMPILER=arm-none-eabi-gcc -DCMAKE_TOOLCHAIN_FILE:PATH="toolchain.cmake" -DNOFORTRAN=1 -DTARGET=ARMV5 -DEMBEDDED=1

    3. Required Runtime Functions: Embedded applications must provide the following functions for OpenBLAS to operate:

    • void free(void* ptr);
    • void* malloc(size_t size);
    cmake .. -G Ninja -DCMAKE_C_COMPILER=arm-none-eabi-gcc -DCMAKE_TOOLCHAIN_FILE:PATH="toolchain.cmake" -DNOFORTRAN=1 -DTARGET=ARMV5 -DEMBEDDED=1

  11. Build OpenBLAS for multiple CPU targets with DYNAMIC_ARCH

    develop

    To build a single OpenBLAS library that supports multiple CPU architectures via runtime detection, use the DYNAMIC_ARCH=1 flag during compilation (via gmake or -DDYNAMIC_ARCH=TRUE in cmake).

    Important Considerations:

    • Target Selection: You should use the TARGET option in conjunction with DYNAMIC_ARCH=1 to specify the oldest CPU model you expect to encounter. This ensures the compiler uses common code rather than assuming the build host's advanced instructions, which prevents illegal instruction errors on older hardware.
    • Architecture Limits: You cannot combine support for different instruction set architectures (e.g., you cannot combine 32-bit and 64-bit, or x86_64 and arm64) in a single library.

    Supported Targets by Architecture:

    • x86_64: Includes Prescott, Core2, Nehalem, Barcelona, Sandybridge, Bulldozer, Piledriver, Steamroller, Excavator, Haswell, Zen, SkylakeX, Cooper Lake, Sapphire Rapids. Use DYNAMIC_OLDER=1 for additional support (Penryn, Dunnington, Opteron, etc.).
    • ARMV8: Enables support for CortexA53, CortexA57, CortexA72, CortexA73, Falkor, ThunderX, ThunderX2T99, TSV110, and generic ARMV8. If the compiler supports SVE, NeoverseN2 and NeoverseV1 are also enabled.
    • POWER: Includes POWER6, POWER8, and POWER9. POWER10 is available with a sufficiently recent compiler.
    • ZARCH: Includes Z13, Z14, and generic zarch support.
    • riscv64: Enables support for riscv64_zvl128b and riscv64_zvl256b in addition to generic riscv64. Requires a compiler supporting RVV 1.0.
    • LoongArch64: Includes LA264, LA464, and generic LoongArch64 support.