FlexiBLAS - A BLAS and LAPACK wrapper library with runtime exchangeable backends

Version 3.5.0 - DOI: 10.5281/zenodo.17431921

Project Website: https://www.mpi-magdeburg.mpg.de/projects/flexiblas

Git Repository: https://gitlab.mpi-magdeburg.mpg.de/software/flexiblas-release

Copyright 2013-2025 by Martin Köhler (ORCID: 0000-0003-2338-9904) and Jens Saak (ORCID: 0000-0001-5567-9637)

Documentation

This Documentation includes:

• About FlexiBLAS
• Installing FlexiBLAS
• Linking with FlexiBLAS
• Setting up FlexiBLAS
• Runtime usage of FlexiBLAS
• Usage Examples
• Environment Variables
• Profiling with FlexiBLAS
• Octave Interface
• Backend Builder

About Flexiblas

FlexiBLAS is a wrapper library that enables the exchange of the BLAS (Basic Linear Algebra System) and LAPACK (Linear Algebra PACKage) implementation used in an executable without recompiling or re-linking it. This could in principle also be achieved using the LD_LIBRARY_PATH mechanism, if all BLAS and LAPACK were consistently implemented as a single library file with a fully compatible interface. Unfortunately, not all BLAS and LAPACK libraries are realized as only this exact one shared library containing all required symbols. Implementations with differing numbers of library files (shared objects) clearly break this mechanism of easily switching via the LD_LIBRARY_PATH environment variable.

The FlexiBLAS library provides a GNU Fortran compatible interface to all functions and subroutines provided by the Netlib reference implementations. As backends FlexiBLAS can employ all BLAS and LAPACK implementations which consist of a single shared library directly. Other variants like the Intel MKL or ATLAS that use multiple files are integrated by FlexiBLAS by wrapping all files into a single surrogate library.

Install

See INSTALL.md.

Linking a Program Against FlexiBLAS

By default FlexiBLAS produces a library called libflexiblas.so, which one can link against a program just like the reference BLAS implementation. Other libraries are not necessary.

64-Bit Integer Build

As already mentioned in the case when the 64-bit integer interface is enabled, the names of all libraries, directories, and environment variables are suffixed by 64, that means in order to link against the 64-bit library, you have to use:

gcc -lflexiblas64 ...

The flexiblas tool is now named flexiblas64. This allows to installed of both variants on a single system.

Configuration Files

FlexiBLAS reads a set of configuration files at startup. These are:

• CMAKE_INSTALL_PREFIX/etc/flexiblasrc
• CMAKE_INSTALL_PREFIX/etc/flexiblasrc.d/*.conf
• ${HOME}/.flexiblasrc
• ${HOME}/.flexiblasrc.$(hostname)
• ${FLEXIBLAS_CONFIG}

If FlexiBLAS is compiled with the INTEGER8 option enabled, flexiblasrc is replaced by flexiblasrc64.

CMAKE_INSTALL_PREFIX/etc/flexiblasrc

and:

~/.flexiblasrc

or:

CMAKE_INSTALL_PREFIX/etc/flexiblasrc64

and:

~/.flexiblasrc64

in case of a 64-bit integer build.

The files contain a mapping between the name of a backend and the corresponding name of the shared object. The setting in the user-owned file overrides the global settings. All settings are superseded eventually by setting environment variables. The syntax of the file is similar to the KDE configuration files or the ini-files known from early MS-Windows versions. Basically, it is a key-value store with section support. In the first section of the configuration file are global definitions like the default BLAS backend or the verbosity level:

default = NETLIB
verbose = 0

Then for each BLAS backend, there is a block of the following style:

[NAME_OF_THE_BACKEND]
library = shared_object.so
comment = Information text about the BLAS backend

If the library argument defines a relative path, FlexiBLAS searches inside its default path (CMAKE_INSTALL_PREFIX/lib/flexiblas or CMAKE_INSTALL_PREFIX/lib/flexiblas64) for this shared object. If the path is absolute it tries to open the library directly. The name of the backend is case-insensitive!

Additionally, one can define additional search paths in the first section. Therefore one has to add a key-value entry of the following style to the first section:

pathXXX = /additional/search/path

where the XXX part of the key should be an increasing unique integer for each additional search path.

If no default mapping is set in one of the configuration files, FlexiBLAS will use the standard Netlib implementation.

The user config files can be handled using the flexiblas tool. This tool can manage the user and the system configuration file, excluding adding additional search paths.

The flexiblas tool can be used for example to:

• List all installed backends and the complete configuration:

  flexiblas list
  

• Set the default backend:

  flexiblas default NAME_OF_THE_BACKEND
  

If the name of the backend is not given, the default setting is removed.

New BLAS backends can also be added to the configuration files using the flexiblas tool. For this please look at the output of

flexiblas help

Caution: In case of a 64-bit integer build the flexiblas tool is renamed to flexiblas64 in order to setup both, a 32-bit and a 64-bit version in parallel.

Selecting the Backend at Runtime

The behavior of the FlexiBLAS wrapper is controlled by a set of environment variables described below and in the above-mentioned configuration files. The most important environment variable is called FLEXIBLAS. This variable describes the shared object library file where the backend BLAS implementation is contained. The variable supports three types of descriptions. If the value does not contain a / FlexiBLAS searches for the given name in CMAKE_INSTALL_PREFIX/lib/flexiblas. That means the value is interpreted as the name of one of the wrapper libraries. If it does not find it there, it searches the configuration files for a line matching the value and fetches the actual name of the shared object library from there. Otherwise, the value is interpreted as a full path description of the BLAS backend library shared object file to use. If the variable is not set, the Netlib reference BLAS, or the default from the configuration files is used. See the documentation for details on the names, syntax, and locations of the configuration files.

Usage Example

If FlexiBLAS is built with an interface to the ATLAS library then one can use the following in an application to call the ATLAS instead of the default BLAS:

FLEXIBLAS="libblas_atlas.so" ./yourapp

In case FlexiBLAS should use OpenBLAS and is registered as OpenBLAS in one of the configuration files the application can be started as follows:

FLEXIBLAS=OpenBLAS ./yourapp

Remember you can list all installed backends with:

flexiblas list

Environment Variables

• FLEXIBLAS=PATH/TO/BLAS

  This is the main variable used by FlexiBLAS. It selects the BLAS library which is used as the backend. This should be a shared object which contains or allows to resolve all symbols defined in the Netlib reference BLAS library. The default search path is CMAKE_INSTALL_PREFIX/lib/flexiblas or CMAKE_INSTALL_PREFIX/lib/flexiblas-profile. Alternatively, an absolute path to a shared object can be given. If the variable is not set it uses libblas_netlib.so as default, or any other backend that is specified as default in the configuration files. For example, if OpenBLAS and ATLAS are available the following two additional implementations can be used: * libblas_openblas.so - to select OpenBLAS * libblas_atlas.so - to select ATLAS FlexiBLAS installs a command flexiblas that can be used to find a list of all available backends (flexiblas list) and prescribe the users default (flexiblas set NAME_OF_BACKEND)

• FLEXIBLAS_VERBOSE=LEVEL

  Enables some additional output at the startup of FlexiBLAS. This can be useful if a backend is not loaded correctly, or when log files should contain the actual BLAS backend used in a certain run of the user application, e.g., because several implementations are compared for benchmark purposes. If the variable is not set, it is assumed to be 0 and the additional output is turned off.

• FLEXIBLAS_NOLAPACK=0/1

  If set to one, FlexiBLAS does not load LAPACK from the backends. Only the internal fallback is used. In this way detailed profiling and logging is possible. The default value is 0.

• FLEXIBLAS_COLOR_OUTPUT=0/1

  Enable / Disable colored output in verbose mode. The default value is 1.

• FLEXIBLAS_CONFIG=PATH

  Specify a flexiblasrc config file. The settings in the file overwrite all setting in the system/user/host config file.

• FLEXIBLAS_LIBRARY_PATH=PATHS

  Add additional paths, in a colon-separated list, to the search paths of the FlexiBLAS library. The paths are added in front of the search list.

Attention: In the case of a 64-bit integer build, all environment variables begin with FLEXIBLAS64 instead of FLEXIBLAS.

Profiling

Since version 3.0.0 the profiling framework is no longer compiled into the library. It is now realized using the function overloading support of FlexiBLAS. The profiling is enabled by loading libflexiblas_hook_profile.so in the for function overloading. This is done using the FLEXIBLAS_HOOK environment variable before starting a problem.

The profiling output can be controlled using the following environment variables:

• FLEXIBLAS_HOOK=libflexiblas_hook_profile.so

  Loads the profile library and installs the functions hooks for it. If already another hook is loaded, The profile library can be chain-loaded by adding it separated by a colon from the other hook libraries.

• FLEXIBLAS_PROFILE_FILE=FILENAME

  Sets a filename to write profiling output to. If the variable is set, the profiling output will be redirected to this file. Otherwise, it is written to the standard error output stderr which is the default setting if the variable is not set.

Octave Interface

The GNU Octave interface is a separate package that can be downloaded from:

http://www.mpi-magdeburg.mpg.de/projects/flexiblas

and installed via:

    pkg install -verbose flexiblas-octave.tar.gz

from the command-line prompt in GNU Octave. After installing the package you can get an overview of the installed functions by calling:

    pkg describe -verbose flexiblas

from the GNU Octave command-line prompt. This package only works on Linux and BSD versions of GNU Octave, but NOT on any version of MS-Windows!

Backend Builder

In order to build backends later without reconfiguring or rebuilding FlexiBLAS, a CMake helper tool exists in tools/backend_builder. This tool can be used to build your own backends individually. Normally, this tool is not required, for single-file BLAS implementations, like OpenBLAS, BLIS,... But in case of libraries like Intel (oneAPI) MKL, this can be helpful.

Versioning

FlexiBLAS uses semantic versioning, with an exception. If the patch level in MAJOR.MINOR.PATCHLEVEL is greater than or equal to 80, this is an alpha/beta/ release candidate of the next FlexiBLAS minor or major release.

Cite As

M. Köhler, J. Saak. FlexiBLAS - A flexible BLAS library with runtime exchangeable backends. LAPACK Working Note: 284, 2013. https://www.netlib.org/lapack/lawnspdf/lawn284.pdf

Acknowledgments

We thank Christian Himpe (0000-0003-2194-6754) for documenting, testing, and providing feedback.

We also thank Iñaki Ucar (0000-0001-6403-5550) for creating a Fedora package and pointing out Linux software maintainer-related issues with the configuration and building process.

Bug Reports

If you find a bug in FlexiBLAS please prepare a minimal examples which reproduces the bug. Without minimal examples, we cannot fix the bug. Send feedback to:

koehlerm@mpi-magdeburg.mpg.de

License

The whole library is provided under the conditions of the LGPLv3 and later The testing code ( contained in test/ ) and the Reference Implementation implementation (contained in contributed/) are covered by the license of LAPACK ( https://www.netlib.org/lapack ). See COPYING.NETLIB for more details about this license.