Файловый менеджер - Редактировать - /usr/share/doc/flexiblas/README.md
�азад
FlexiBLAS - A BLAS and LAPACK wrapper library with runtime exchangeable backends ================================================================================ **Version 3.0.4** https://doi.org/10.5281/zenodo.3949804 **Project Website:** https://www.mpi-magdeburg.mpg.de/projects/flexiblas **Git Repository:** https://gitlab.mpi-magdeburg.mpg.de/software/flexiblas-release Copyright 2013-2020 by *Martin Köhler* (0000-0003-2338-9904) and *Jens Saak* (0000-0001-5567-9637) **FlexiBLAS** is a wrapper library that enables the exchange of the [*BLAS*](https://en.wikipedia.org/wiki/BLAS) (Basic Linear Algebra System) and [*LAPACK*](https://en.wikipedia.org/wiki/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 The build system used by **FlexiBLAS** is *cmake* which prefers an out-of-source build: mkdir build cd build cmake ../ <FURTHEROPTIONS> make make install If the build system should try to build backends for *BLAS* and *LAPACK* libraries that are not known to the *FindBLAS cmake* module, or reside in non-standard paths on your system, make sure to include their location (containing directory) to the `LD_LIBRARY_PATH` environment variable. At the end of the configuration step, *cmake* will inform you about the additional backends found on your system. The configuration via *cmake* can be influenced further by the following options: * `-DCMAKE_INSTALL_PREFIX=/PATH/` Defines an alternative location for the installation of the resulting library. The default installation location is `/usr/local`. The library called `libflexiblas.so` is installed in `CMAKE_INSTALL_PREFIX/lib` and the default search path for backends is `CMAKE_INSTALL_PREFIX/lib/flexiblas`. * `-DDEBUG=ON/OFF` Turns the inclusion of debugging symbols `ON` or `OFF`. The default is `OFF`. * `-DINTEGER8=ON/OFF` Enables 8-byte integers for the *Fortran* interface. Be aware that the application and the backend libraries must be compiled to support 8-byte integers as well. Since most applications and libraries still us the classic 32-bit integers the default is `OFF`. * `-DCBLAS=ON/OFF` Enables the *CBLAS* frontend. If the backend itself contains a *CBLAS* interface that one is used. Otherwise **FlexiBLAS** acts like the *CBLAS*-wrapper from *Netlib*. This option is set to `ON` by default. * `-DABI=GNU|Intel` Selects the ABI (Application Binary Interface) of the *Fortran* Interface. By default the compiler used determines which ABI is used, but it can also be forced using this parameter. The difference between both ABIs is how complex values are returned from Functions. The *GNU*-style returns them as a normal return value on the stack. The *Intel* (*F2C*, *GNU F77*) style returns them as an additional parameters in front of the proper function arguments. That means it is a subroutine from the *C* point of view. * `-DBLASNAME=OFF` Deactivate the automatic search for the *BLAS* library with the name **BLASNAME**. * `-DEXTRA=List` Add an additional list of *BLAS* libraries to the default setup of **FlexiBLAS**. See below for details. * `-DMKL_CUSTOM=ON/OFF` Turn `ON`/`OFF` the build of an *Intel MKL* custom library instead of searching for the *MKL* directly. This is necessary if you plan to switch between single and multithreaded *MKL* in your application. Turning this option on requires to have the `MKLROOT` environment variable set properly and an *MKL* version >=11.1. The default is `OFF`. * `-DDEV=ON/OFF` Configures the build to work only in the build directory. In this case **FlexiBLAS** searches in the root of the build directory for its configuration file and the build directory is added to the default library search path. Turning on this option is only useful during the development in order to work independently from an installed **FlexiBLAS**. If you plan to install **FlexiBLAS**, set it to `OFF` which is also the default value. * `-DBLAS_AUTO_DETECT=ON/OFF` Enable/disable the automatic search for *BLAS* libraries during configuration. They need to be added separately using the `-DEXTRA` option or configured afterwards. The default value is `ON`. * `-DLAPACK=ON/OFF` Turn `ON/OFF` the *LAPACK* support of **FlexiBLAS**. If enabled **FlexiBLAS** also includes the wrappers around *LAPACK*. Default value is `ON`. * `-DLAPACK_API_VERSION=VERSION` Selects *LAPACK* API compatibility level. By default the newest one is used. If a *LAPACK* library loaded at runtime does not provide all functions and subroutines, the missing ones are loaded from the fallback. The following *LAPACK* versions are supported: | LAPACK_API_VERSION | | Testing | |--------------------|------------------------------------------|---------| | 3.9.0 | LAPACK 3.9.0 | yes | | 3.9.0-wodprc | LAPACK 3.9.0 without deprecated routines | yes | | 3.8.0 | LAPACK 3.8.0 | yes | | 3.8.0-wodprc | LAPACK 3.8.0 without deprecated routines | yes | | 3.7.1 | LAPACK 3.7.1 | yes | | 3.7.1-wodprc | LAPACK 3.7.1 without deprecated routines | yes | | 3.7.0 | LAPACK 3.7.0 | yes | | 3.7.0-wodprc | LAPACK 3.7.0 without deprecated routines | yes | | 3.6.1 | LAPACK 3.6.1 | yes | | 3.6.1-wodprc | LAPACK 3.6.1 without deprecated routines | yes | | 3.6.0 | LAPACK 3.6.0 | no | | 3.6.0-wodprc | LAPACK 3.6.0 without deprecated routines | no | | 3.5.0 | LAPACK 3.5.0 | no | | 3.4.2 | LAPACK 3.4.2 | no | | 3.4.1 | LAPACK 3.4.1 | no | | 3.4.0 | LAPACK 3.4.0 | no | | 3.3.1 | LAPACK 3.3.1 | no | | 3.3.0 | LAPACK 3.3.0 | no | * `-DFLEXIBLAS_DEFAULT=NAME` Set the default *BLAS* at compile time. If the option is not set `NETLIB` is used by default. The `PROFILE=ON/OFF` option was removed from version 1.1.0 onwards. Beginning with version 3.0.0 profiling is done using a hook functionality and is not longer compiled in **FlexiBLAS** directly. See the Profiling section for details. The following *BLAS* backends are tested during development: * *Netlib* [*BLAS*](https://www.netlib.org/blas/) and [*LAPACK*](https://www.netlib.org/lapack/) Reference Implementation * [*ATLAS*](http://math-atlas.sourceforge.net/) * [*OpenBLAS*](http://www.openblas.net/) * [*BLIS*](https://github.com/flame/blis) * [*Intel MKL*](https://software.intel.com/content/www/us/en/develop/tools/math-kernel-library.html) ### Setup with precompiled reference BLAS and LAPACK On many Linux and *BSD* operating systems static versions of *BLAS* and *LAPACK* can be installed from the package management system. These versions can be used instead of **FlexiBLAS**'s internal fallback implementation. In order to use a provided static library providing a *BLAS* API it needs to be ensured that this library is compiled with support for position independent code (`-fPIC`). The *BLAS* implementation is set in the configuration procedure via ``` cmake -DSYS_BLAS_LIBRARY=/absolute/path/to/liblas.a ``` The *BLAS* library have to provided all functions and subroutines available in the reference *BLAS* implementation since *LAPACK* 3.0. The *LAPACK* fallback implementation can be provided in the same way via ``` cmake -DSYS_LAPACK_LIBRARY=/absolute/path/to/liblapack.a \ -DLAPACK_API_VERSION="LAPACK-VERSION" ``` The *LAPACK* library must provide all symbols that the reference implementation from *NETLIB* with the given version provides. A list of supported *LAPACK* versions is given above. If the version is not specified *cmake* tries to obtain it with a call to *LAPACK*'s `ILAVER`. Note that the path must be absolute, the `~`-operator to reference the home directory is not allowed. ### Setup with Custom *BLAS* and *LAPACK* Implementations. By default, **FlexiBLAS** tries to locate as many *BLAS* and *LAPACK* installations as possible on your system. If you want to add our own ones to the default setup you can pass the `-DEXTRA` option to *cmake*. It specifies a semicolon separated list of additional *BLAS* names that should be added. For each addtional library name `name` in the list, a path needs to be specified via `-Dname_LIBRARY=PATH_TO_NAME`. If special linker flags are required the option `-Dname_LINKER_FLAGS="FLAGS"` can be passed to *cmake*. For example, if a custom build *OpenBLAS-0.3.4* and *OpenBLAS-0.3.10* should be included, the following options have to be added to cmake: ``` -DEXTRA="OpenBLAS034;OpenBLAS0310" \ -DOpenBLAS034_LIBRARY="/home/user/openblas-0.3.4/libopenblas.a;gomp;pthread;" \ -DOpenBLAS0310_LIBRARY="/home/user/openblas-0.3.10/libopenblas.a;gomp;pthread;" ``` ### Setup on *Debian* and Derivates The easiest way is to build a *Debian* package out of the source and install it. At the moment we support the package creation on *Ubuntu 20.04* and *Debian 11* (Testing) since they provide *OpenBLAS* and *BLIS* split in different packages depending on the used threading model. In order to build the package the following prerequisites need to be installed: ``` sudo apt-get install debhelper cmake gfortran gcc libatlas-base-dev \ libopenblas-openmp-dev libopenblas-pthread-dev libopenblas-serial-dev \ libopenblas64-openmp-dev libopenblas64-pthread-dev \ libopenblas64-serial-dev libblis-openmp-dev libblis-pthread-dev \ libblis-serial-dev libblis64-openmp-dev libblis64-pthread-dev \ libblis64-serial-dev libblas-dev libblas64-dev liblapack-dev \ liblapack64-dev ``` Afterwards you can build the *Debian* package out of the source code by typing: ``` fakeroot dpkg-buildpackage -us -uc ``` inside the extracted source. After building the package the source directory can be cleaned using ``` debian/rules clean ``` The build process creates a set of packages which are available one directory level above. They are installed using: ``` sudo dpkg -i ../libflexiblas*.deb ``` If you update from **FlexiBLAS** <= 2.0.0 please remove all related packages and configuration files before. ### Caveats * If **FlexiBLAS** is not automatically selected by the `update-alternatives` mechanism you have to select it via: sudo update-alternatives --config libblas.so sudo update-alternatives --config libblas.so.3 sudo update-alternatives --config libblas.so.3gf The last line is only necessary up to *Ubuntu 12.04* and *Debian 6*. * **FlexiBLAS** requires that you use the reference implementation of *LAPACK* that means if `update-alternatives` uses the *LAPACK* implementation provided by *ATLAS* many programs will fail. Please install the reference *LAPACK* package and set it in the `update-alternatives` mechanism via sudo update-alternatives --config liblapack.so sudo update-alternatives --config liblapack.so.3 sudo update-alternatives --config liblapack.so.3gf The last one is only necessary up to *Ubuntu 12.04* and *Debian 6*. * Due to a bug in the *Ubuntu* *OpenBLAS* packages **FlexiBLAS** does not work with the **OpenBLAS** package versions between 0.2.6 and 0.2.8-4. If you have one of these version installed, please update *OpenBLAS* before installing **FlexiBLAS**. ### Testing **FlexiBLAS** comes with the reference *BLAS* and reference *LAPACK* test suite. The tests are executed using ``` make test ``` and use the *NETLIB BLAS* implementation by default in order to check the compliance with the reference implementation. Other *BLAS* and *LAPACK* implementations can be tested by setting the `FLEXIBLAS_TEST` environment variable. The variable has the same meaning as the `FLEXIBLAS` environment variable but only for the tests. If single tests need to be selected we refer to the help of the *cmake* `ctest` utility. ## 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 definition like the default *BLAS* backend or the verbosity level: default = NETLIB verbose = 0 Than 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 an 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 handle using the `flexiblas` tool. This tool can manage the user and the system configuration file, excluding the 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 a 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 stated like: FLEXIBLAS=OpenBLAS ./yourapp ## 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. ## Environment Variables * `FLEXIBLAS=PATH/TO/BLAS` This is the main variable used by **FlexiBLAS**. It selects the *BLAS* library which is used as 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 list 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 benchmarking 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 interal fallback is used. In this way a 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`. ## 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 both variants on a single system. ## 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 an other 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 which 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 about 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*! ## 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 a 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 *GPLv3* and later with a linking exception according to section 7 of the GNU General Public License, version 3 ("GPLv3"). This exception, written in COPYING.ADDITIONAL, is valid for all files in the src/ directory. It allows to link FlexiBLAS against all software, opensource or proprietary, without violating the GPL license as long as only the BLAS/LAPACK interface of the reference implementation is used. 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.
| ver. 1.4 |
Github
|
.
| PHP 8.2.29 | Генераци� �траницы: 0 |
proxy
|
phpinfo
|
�а�тройка