From Fedora Project Wiki
mNo edit summary
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Draft}}
{{Draft}}


= Introduction =
= Linear Algebra Libraries =


Besides being implementations, BLAS and LAPACK are also API standards for basic linear algebra operations (such as vector and matrix multiplication). Many implementations of these API exist. The reference implementation of BLAS and LAPACK from Netlib is very stable but is not as fast as optimized ones such as ATLAS and OpenBLAS.
== Introduction ==


Implementations of BLAS:
BLAS (Basic Linear Algebra Subprograms) and LAPACK (Linear Algebra PACKage) are routines that provide standard building blocks for performing a wide range of linear algebra operations operations. There are stable reference implementations from [https://netlib.org/ Netlib] written in Fortran, with C intefaces available (called CBLAS and LAPACKE respectively), as well as several optimized implementations providing fast subsets of these APIs.


* blas - Reference implementation from Netlib.
=== Implementations available ===
* atlas - Automatically Tuned Linear Algebra Software.
* blis - BLAS-like Library Instantiation Software framework.
* openblas - OpenBLAS, an optimized BLAS based on GotoBLAS2.


Both BLIS and OpenBLAS provide several flavors: a sequential version, a threaded one, and another with OpenMP support (all of them with or without support for 64-bit integers).
* `blas`, `lapack` - Netlib's reference implementation of the Fortran and C interfaces.
* `atlas` - Automatically Tuned Linear Algebra Software.
* `blis` - BLAS-like Library Instantiation Software framework.
* `openblas` - OpenBLAS, an optimized BLAS based on GotoBLAS2.


Implementations of LAPACK:


* lapack - Reference implementation from Netlib.
ATLAS, BLIS and OpenBLAS provide BLAS and a subset of LAPACK. Both BLIS and OpenBLAS provide several flavors: a sequential version, a threaded one, and another with OpenMP support (all of them with or without support for 64-bit integers).
* ATLAS, BLIS and OpenBLAS provide an optimized subset of LAPACK.


Due to implementation differences, it is important that all components of a particular software stack link to the same BLAS/LAPACK implementation. Also, users may want to choose a particular implementation that works best for them at run time.  This guideline gives a structure that can enforce the first while allowing the second, as well as providing a transparent fallback mechanism to Netlib's reference implementation for those symbols not included in the selected backend.
Due to implementation differences, it is important that all components of a particular software stack link to the same BLAS/LAPACK implementation. Also, users may want to choose a particular implementation that works best for them at run time.  This guideline gives a structure that can enforce the first while allowing the second, as well as providing a transparent fallback mechanism to Netlib's reference implementation for those symbols not included in the selected backend via [https://www.mpi-magdeburg.mpg.de/projects/flexiblas FlexiBLAS].


= BLAS/LAPACK wrapper =
=== BLAS/LAPACK wrapper ===


[https://www.mpi-magdeburg.mpg.de/projects/flexiblas FlexiBLAS] is a framework that wraps both BLAS and LAPACK APIs in a single library. BLAS/LAPACK consumers must link against FlexiBLAS, and this wrapper is able to redirect calls to a selected optimized backend with negligible overhead. It also provides transparent fallback to Netlib's reference implementation if a certain symbol is not present in the selected backend. These are the main features:
[https://www.mpi-magdeburg.mpg.de/projects/flexiblas FlexiBLAS] is a framework that wraps both BLAS and LAPACK APIs in a single library. BLAS/LAPACK consumers must link against FlexiBLAS, and this wrapper is able to redirect calls to a selected optimized backend with negligible overhead. It also provides transparent fallback to Netlib's reference implementation if a certain symbol is not present in the selected backend. These are the main features:
Line 28: Line 26:
* Runtime exchangeable BLAS and LAPACK backend without recompilation via an environment variable.
* Runtime exchangeable BLAS and LAPACK backend without recompilation via an environment variable.
* Integration of user-owned BLAS libraries without administrator privileges, even in system-wide installed programs.
* Integration of user-owned BLAS libraries without administrator privileges, even in system-wide installed programs.
* Works with OpenBLAS, ATLAS, Intel MKL, ACML, ...
* Works with OpenBLAS, ATLAS and BLIS, as well as non-free alternatives such as Intel MKL, ACML...
* Flexible per-system/user/host configuration files.
* Flexible per-system/user/host configuration files.
* Basic profiling support.
* Basic profiling support.


FlexiBLAS provides a common interface,


%files wrapper
Fedora ships `openblas-openmp` as the system-wide default backend.
%{_libdir}/flexiblas.so.x
%files wrapper64
%{_libdir}/flexiblas64.so.x


as well as fallbacks to Netlib's reference implementation,
== Packaging BLAS/LAPACK dependent packages ==


%files wrapper
Consumers of any subset of BLAS and/or LAPACK MUST compile against FlexiBLAS (unless this is not supported; see [[Exceptions]] below).
%{_libdir}/flexiblas/libflexiblas_netlib.so
%{_libdir}/flexiblas/libflexiblas_fallback_lapack.so
%files wrapper64
%{_libdir}/flexiblas64/libflexiblas_netlib.so
%{_libdir}/flexiblas64/libflexiblas_fallback_lapack.so


and, finally, several wrappers for different implementations under different names:
=== Build requirements ===


%files atlas
First, only FlexiBLAS's development package MUST be listed in `BuildRequires`:
%{_libdir}/flexiblas/libflexiblas_atlas.so
%files blis-serial
%{_libdir}/flexiblas/libflexiblas_blis-serial.so
%files blis-threads
%{_libdir}/flexiblas/libflexiblas_blis-threads.so
%files blis-openmp
%{_libdir}/flexiblas/libflexiblas_blis-openmp.so
%files openblas-serial
%{_libdir}/flexiblas/libflexiblas_openblas-serial.so
%files openblas-threads
%{_libdir}/flexiblas/libflexiblas_openblas-threads.so
%files openblas-openmp
%{_libdir}/flexiblas/libflexiblas_openblas-openmp.so
plus the 64-bit versions for BLIS and OpenBLAS under %{_libdir}/flexiblas64 in 64-bit architectures. These are sub-packaged separately to avoid pulling the whole stack of implementations. The wrapper and wrapper64 sub-packages require a default implementation that is currently set to openblas-serial:


  %global default_backend openblas-serial
  BuildRequires: flexiblas-devel
%package        wrapper
Requires:       %{name}%{?_isa} = %{version}-%{release}
Requires:      %{name}-%{default_backend}%{?_isa} = %{version}-%{release}
%package        wrapper64
Requires:      %{name}%{?_isa} = %{version}-%{release}
Requires:      %{name}-%{default_backend}64%{?_isa} = %{version}-%{release}


= Packaging guidelines =
Alternatively, packages using `pkg-config` SHOULD express this dependency as


== BLAS/LAPACK implementations ==
BuildRequires: pkgconfig(flexiblas)
 
if the package requires the 32-bit interface (this is the most common case), or a conditional `BuildRequires` such as
 
%if 0%{?__isa_bits} == 64
BuildRequires: pkgconfig(flexiblas64)
%else
BuildRequires: pkgconfig(flexiblas)
%endif
 
if the package uses the 64-bit interface when available. However, note that if the package '''only''' supports this 64-bit interface, then 32-bit architectures MUST be excluded.


Implementations of BLAS and/or LAPACK available in Fedora do not need to change anything.
=== Configuration ===


== BLAS/LAPACK dependent packages ==
Packages using `pkg-config` will automatically obtain the proper paths to the headers and libraries. Similarly, CMake-based projects using `FindBLAS` will automatically detect and configure the proper flags for FlexiBLAS (since CMake v3.19), and no further action will be required from the packager.


Consumers of any subset of BLAS and/or LAPACK must compile against FlexiBLAS:
Unfortunately, many upstream projects present heterogeneous ways of accessing these APIs. In a best-case scenario, the building framework may define specific options to explicitly set the BLAS and/or LAPACK libraries. More commonly, the packager MUST ensure that `%{_includedir}/flexiblas` and `%{_libdir}/flexiblas` are injected as header and library locations in the proper flags and configuration files. In rare occasions, hardcoded paths in source files MUST be modified, and patches MAY be required. The packager SHOULD work with upstream to standardize the way in which these libraries are detected and configured.


BuildRequires: pkgconfig(flexiblas)
To ensure that the program has been properly linked against FlexiBLAS, the packager MUST check that the `Requires` are correct, i.e., `libflexiblas` is listed, but not `libblas`, `liblapack` or any other backend.
 
=== Tests ===
 
Optimized BLAS/LAPACK backends are much faster than Netlib's reference implementation, but in return results may vary a little. Consequently, tests that are too tight (with too small tolerances) may fail. In these cases, the packager SHOULD enable the reference implementation in the `%check` section as follows:


if the package uses the 32-bit interface (this is the most common case), or
  export FLEXIBLAS=netlib


BuildRequires: pkgconfig(flexiblas64)
or, alternatively, via `FLEXIBLAS64` for builds using 64-bit integers.


if the package uses the 64-bit interface. Furthermore, if the package **only** supports this 64-bit interface, then 32-bit architectures must be excluded. Otherwise, the package may depend conditionally on the 64-bit version when available, and on the 32-bit one otherwise (as e.g. packages petsc and suitesparse currently do).
=== Exceptions ===


In any case, by compiling against FlexiBLAS, they will automatically use the system-wide default backend, and will benefit from any other system/user/host-selected optimized subset of routines.
* Although support for LAPACKE is planned, the few packages using this interface are not yet supported by FlexiBLAS as of v3.1.2. These packages MUST link against OpenBLAS instead, or `lapack` if the routines used are not supported by this backend. Current exceptions of this type include `opencv`, `scamp` and `sextractor`.


= Backend selection =
* On rare occasions, a package may use an exceptional feature present in a particular backend and cannot be adapted to FlexiBLAS by any means. In such cases, the package MUST link against this backend. Current exceptions of this type include `julia` (linked against OpenBLAS) and `psfex` (linked against ATLAS).


== System-level selection ==
== Backend selection ==


A package compiled against FlexiBLAS pulls out the corresponding flexiblas-wrapper(64) subpackage, which in turn requires the default optimized backend, e.g., flexiblas-openblas-serial(64). This is set via the "default=IMPLEMENTATION-NAME" key (by default, default=openblas-serial), present in the main configuration file shipped in the wrapper subpackages:
=== System-level selection ===


%files wrapper
A package compiled against FlexiBLAS pulls out the corresponding `flexiblas-netlib(64)` subpackage, which in turn requires the default optimized backend (i.e., `flexiblas-openblas-openmp(64)`). This is set via the "default=IMPLEMENTATION-NAME" key (by default, `default=openblas-openmp`), present in the main configuration file shipped in the main subpackages, `%{_sysconfdir}/flexiblasrc` and `%{_sysconfdir}/flexiblas64rc`.
%config(noreplace) %{_sysconfdir}/flexiblasrc
%files wrapper64
%config(noreplace) %{_sysconfdir}/flexiblas64rc


To allow system-level selection of other BLAS/LAPACK implementations, more backends must be installed in the first place (e.g., flexiblas-atlas, flexiblas-blis-serial...), and then they can be swapped system-wide via the flexiblas CLI tool, or just by modifying the "default" key in the configuration file by hand.
To allow system-level selection of other BLAS/LAPACK implementations, more backends must be installed in the first place (e.g., flexiblas-atlas, flexiblas-blis-serial...), and then they can be swapped system-wide via the `flexiblas` CLI tool, or just by modifying the "default" key in the configuration file by hand.


== User-level selection ==
=== User-level selection ===


Persistent user-level selection of system-provided BLAS/LAPACK implementations can be done via the CLI tool:
Persistent user-level selection of system-provided BLAS/LAPACK implementations can be done via the CLI tool:
Line 126: Line 94:
  $ flexiblas64 set IMPLEMENTATION-NAME
  $ flexiblas64 set IMPLEMENTATION-NAME


provided the sub-package for IMPLEMENTATION-NAME is installed.
provided the sub-package for `IMPLEMENTATION-NAME` is installed.


Non-persistent user-level selection can be triggered via an environment variable:
Non-persistent user-level selection can be triggered via an environment variable:
Line 133: Line 101:
  $ FLEXIBLAS64=IMPLEMENTATION-NAME ./yourapp64
  $ FLEXIBLAS64=IMPLEMENTATION-NAME ./yourapp64


User-level selection of user-owned BLAS/LAPACK libraries can be achieved just by changing IMPLEMENTATION-NAME with a path to any custom BLAS/LAPACK-compatible library in the examples above.
User-level selection of user-owned BLAS/LAPACK libraries can be achieved just by changing `IMPLEMENTATION-NAME` with a path to any custom BLAS/LAPACK-compatible library in the examples above.


[[Category:Packaging guidelines drafts]]
[[Category:Packaging guidelines drafts]]

Latest revision as of 17:31, 18 January 2022

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.

Linear Algebra Libraries

Introduction

BLAS (Basic Linear Algebra Subprograms) and LAPACK (Linear Algebra PACKage) are routines that provide standard building blocks for performing a wide range of linear algebra operations operations. There are stable reference implementations from Netlib written in Fortran, with C intefaces available (called CBLAS and LAPACKE respectively), as well as several optimized implementations providing fast subsets of these APIs.

Implementations available

  • blas, lapack - Netlib's reference implementation of the Fortran and C interfaces.
  • atlas - Automatically Tuned Linear Algebra Software.
  • blis - BLAS-like Library Instantiation Software framework.
  • openblas - OpenBLAS, an optimized BLAS based on GotoBLAS2.


ATLAS, BLIS and OpenBLAS provide BLAS and a subset of LAPACK. Both BLIS and OpenBLAS provide several flavors: a sequential version, a threaded one, and another with OpenMP support (all of them with or without support for 64-bit integers).

Due to implementation differences, it is important that all components of a particular software stack link to the same BLAS/LAPACK implementation. Also, users may want to choose a particular implementation that works best for them at run time. This guideline gives a structure that can enforce the first while allowing the second, as well as providing a transparent fallback mechanism to Netlib's reference implementation for those symbols not included in the selected backend via FlexiBLAS.

BLAS/LAPACK wrapper

FlexiBLAS is a framework that wraps both BLAS and LAPACK APIs in a single library. BLAS/LAPACK consumers must link against FlexiBLAS, and this wrapper is able to redirect calls to a selected optimized backend with negligible overhead. It also provides transparent fallback to Netlib's reference implementation if a certain symbol is not present in the selected backend. These are the main features:

  • Provides a 100% BLAS and LAPACK compatible ABI/API, with interfaces for both 32- and 64-bit integers.
  • Runtime exchangeable BLAS and LAPACK backend without recompilation via an environment variable.
  • Integration of user-owned BLAS libraries without administrator privileges, even in system-wide installed programs.
  • Works with OpenBLAS, ATLAS and BLIS, as well as non-free alternatives such as Intel MKL, ACML...
  • Flexible per-system/user/host configuration files.
  • Basic profiling support.


Fedora ships openblas-openmp as the system-wide default backend.

Packaging BLAS/LAPACK dependent packages

Consumers of any subset of BLAS and/or LAPACK MUST compile against FlexiBLAS (unless this is not supported; see Exceptions below).

Build requirements

First, only FlexiBLAS's development package MUST be listed in BuildRequires:

BuildRequires: flexiblas-devel

Alternatively, packages using pkg-config SHOULD express this dependency as

BuildRequires: pkgconfig(flexiblas)

if the package requires the 32-bit interface (this is the most common case), or a conditional BuildRequires such as

%if 0%{?__isa_bits} == 64
BuildRequires: pkgconfig(flexiblas64)
%else
BuildRequires: pkgconfig(flexiblas)
%endif

if the package uses the 64-bit interface when available. However, note that if the package only supports this 64-bit interface, then 32-bit architectures MUST be excluded.

Configuration

Packages using pkg-config will automatically obtain the proper paths to the headers and libraries. Similarly, CMake-based projects using FindBLAS will automatically detect and configure the proper flags for FlexiBLAS (since CMake v3.19), and no further action will be required from the packager.

Unfortunately, many upstream projects present heterogeneous ways of accessing these APIs. In a best-case scenario, the building framework may define specific options to explicitly set the BLAS and/or LAPACK libraries. More commonly, the packager MUST ensure that %{_includedir}/flexiblas and %{_libdir}/flexiblas are injected as header and library locations in the proper flags and configuration files. In rare occasions, hardcoded paths in source files MUST be modified, and patches MAY be required. The packager SHOULD work with upstream to standardize the way in which these libraries are detected and configured.

To ensure that the program has been properly linked against FlexiBLAS, the packager MUST check that the Requires are correct, i.e., libflexiblas is listed, but not libblas, liblapack or any other backend.

Tests

Optimized BLAS/LAPACK backends are much faster than Netlib's reference implementation, but in return results may vary a little. Consequently, tests that are too tight (with too small tolerances) may fail. In these cases, the packager SHOULD enable the reference implementation in the %check section as follows:

 export FLEXIBLAS=netlib

or, alternatively, via FLEXIBLAS64 for builds using 64-bit integers.

Exceptions

  • Although support for LAPACKE is planned, the few packages using this interface are not yet supported by FlexiBLAS as of v3.1.2. These packages MUST link against OpenBLAS instead, or lapack if the routines used are not supported by this backend. Current exceptions of this type include opencv, scamp and sextractor.
  • On rare occasions, a package may use an exceptional feature present in a particular backend and cannot be adapted to FlexiBLAS by any means. In such cases, the package MUST link against this backend. Current exceptions of this type include julia (linked against OpenBLAS) and psfex (linked against ATLAS).

Backend selection

System-level selection

A package compiled against FlexiBLAS pulls out the corresponding flexiblas-netlib(64) subpackage, which in turn requires the default optimized backend (i.e., flexiblas-openblas-openmp(64)). This is set via the "default=IMPLEMENTATION-NAME" key (by default, default=openblas-openmp), present in the main configuration file shipped in the main subpackages, %{_sysconfdir}/flexiblasrc and %{_sysconfdir}/flexiblas64rc.

To allow system-level selection of other BLAS/LAPACK implementations, more backends must be installed in the first place (e.g., flexiblas-atlas, flexiblas-blis-serial...), and then they can be swapped system-wide via the flexiblas CLI tool, or just by modifying the "default" key in the configuration file by hand.

User-level selection

Persistent user-level selection of system-provided BLAS/LAPACK implementations can be done via the CLI tool:

$ flexiblas set IMPLEMENTATION-NAME
$ flexiblas64 set IMPLEMENTATION-NAME

provided the sub-package for IMPLEMENTATION-NAME is installed.

Non-persistent user-level selection can be triggered via an environment variable:

$ FLEXIBLAS=IMPLEMENTATION-NAME ./yourapp
$ FLEXIBLAS64=IMPLEMENTATION-NAME ./yourapp64

User-level selection of user-owned BLAS/LAPACK libraries can be achieved just by changing IMPLEMENTATION-NAME with a path to any custom BLAS/LAPACK-compatible library in the examples above.