flexiblas

Section: The FlexiBLAS Library (1)
Updated: 2013-2020
Page Index

NAME

flexiblas - the FlexiBLAS administration tool

SYNOPSIS

flexiblas [options] command [command-options]

flexiblas64 [options] command [command-options]

DESCRIPTION

The flexiblas tool is a command line utility shipped with the FlexiBLAS library. It is used to configure the global and the local flexiblasrc file. Its main purpose it selecting the default BLAS backend used with FlexiBLAS and other runtime specific options. FlexiBLAS uses up to four locations to search for its configuration, a system-wide configuration file, a per-user configuration file, a per-host configuration file, and one configuration file defined by an environment variable FLEXIBLAS_CONFIG. The configuration files are evaluated in this order and a later loaded one overwrites the settings of a previously loaded one.

The flexiblas64 tool is used for the 64-bit integer variant of FlexiBLAS.

Furthermore, it can be used to add or remove BLAS backends form the configuration files.

Hooks

FlexiBLAS supports so called hooks to modify/extent/change the behavior of BLAS and LAPACK functions. This can be used for profiling, automatic offloadlind, and other debuging purposes. The hooks are configured either via the FLEXIBLAS_HOOK environment variable or the flexiblas tool. The FLEXIBLAS_HOOK variable contains a colon separate list of hooks or shared libraries containing the hook. The hooks are loaded in the order they are specified. If the hook_enabled setting in a configuration file is set but empty all hooks are disabled for this configuration file. In this way the per host setting can disable the user settings. Using the hook disableall command the hook_enabled entry is removed and thus no hook settings are in the configuration.

Configuration Priority

FlexiBLAS uses serveral configuration paths to select the BLAS backend or enable and disable other functionality. The configuration is read in the following order, thereby previous read information is overwritten. That means that last read configuration has the highest priority.

1. /etc/flexiblasrc - The system wide configuration file, hooks can not be configured here.

2. /etc/flexiblasrc.d/*.conf - Additional system wide configurations, read only.

3. ${HOME}/flexiblasrc - The user's configuration file.

4. ${HOME}/flexiblasrc.$(hostname) - The user's configuration file on a host, useful for NFS homedirectories.

5. FLEXIBLAS_CONFIG - The environment variable is used to specified a separate configuration file, e.g. per project.

6. FLEXIBLAS, FLEXIBLAS_HOOK - Select a BLAS implementation or a hook without changing the config.

64-bit Integers

If FlexiBLAS is compiled with 64 bit intergers, flexiblas is replaced by flexiblas64 and FLEXIBLAS is replaced by FLEXIBLAS64 in all names of configuration files, environment variable, etc.

OPTIONS

Commands

help

Print information about the tool and its usage.

print

Print the whole BLAS related configuration including search paths, default settings, etc.

list

List all available BLAS libraries from the configuration files.

default BLASNAME

Sets the default BLAS backend in the selected configuration file.

default

Removes the default setting from the selected configuration file.

add BLASNAME sharedlibrary.so ["comment string"]

Add a new BLAS backend called "BLASNAME" to the selected configuration file. This will create a section like


  [BLASNAME]
  library=sharedlibrary.so
  comment="comment string"

in the selected configuration file. The comment string is optional.

remove NAME

Remove a BLAS backed called "NAME" from the selected configuration file.

set property [value]

Set a property in the configuration file. If the value is not given the property is reset to its default. The available properties are listed below.

Hook commands:

Hooks are additional plugins that integrate in the call of a BLAS or LAPACK function. They are used for debugging or profiling purpose.

hook list: List all available hooks. The hooks are automatically found in the FlexiBLAS library directories.
hook show hook-name: Show details about a specific hook. This includes the name, the authors, a short description, and the list of configurable options.
hook enable hook-name: Enable a hook. If more than one hook is enabled they are executed in the order they got enabled.
hook disable hook-name: Disable a hook.
hook disableall: Disable all hooks in a configuration and remove the setting from the configuration. This is necessary if, i.e., hooks are enabled in the user configuration and the host configuration file has an empty hook_enabled field. In this case the FlexiBLAS does not use a hook since the host configuration overwrites the user configuration. Then hook disableall is used to remove the hook_enabled from the host configuration.
hook enabled: Show all enabled hooks in the configuration files.
hook active: Show the currently active hooks and from which configuration file they are loaded.
hook set hook-name option-name value: Set an option for a hook to the given value. All available options for a hook can be shown with the hook show command. Bhook unset hook-name option-name Unset an option for a hook.

General Options:

-u, --user: Edit the user's flexiblasrc configuration (default options, except of executing as root).
-g, --global: Edit the global flexiblasrc configuration (default in case of executing as root).
-H, --host: Edit the host configuration file.
-E, --environment: Edit the configuration file given by the environment variable FLEXIBLAS_CONFIG.
-p, --pipe: Make the output of some commands, like list pipe compatible to use them in scripts.
-h, --help: Print this information and exit.
-v, --version: Print the versionformation and exit.

Properties

verbose integer: Change the verbosity level of FlexiBLAS. The default verbosity level is 0 which only displays critical errors. If a level larger than is specified, FlexiBLAS will produce many debug information on stderr.
nolapack integer: If the value is non zero, FlexiBLAS does not load the LAPACK functions from the backend. That means that only the internal LAPACK routines are used.

FILES

/etc/flexiblasrc: System-wide FlexiBLAS configuration file.
/etc/flexiblasrc.d/*.conf: Additional system-wide configuration files. Read-only, Installed by BLAS library to be included in FlexiBLAS.
~/.flexiblasrc: User FlexiBLAS configuration file.
~/.flexiblasrc.$(hostname): User FlexiBLAS configuration file for a specific host.

ENVIRONMENT VARIABLES

FLEXIBLAS_CONFIG: Using the FLEXIBLAS_CONFIG environment variable an additional configuration can be set. This can be used for per-project settings.
FLEXIBLAS: Select a BLAS implementation ignoring the configuration settings. If the content of the variable is a path to a shared object containing a BLAS library, this is used as BLAS implementation. It is not required that this BLAS library is configured in any of the configuration files.
FLEXIBLAS_HOOK: The FLEXIBLAS_HOOK variable contains a colon separated list of hooks which should be loaded. If a hook is a path to a shared object instead of a name of an available hook, FlexiBLAS tries to load this library as a hook,
FLEXIBLAS_LIBRARY_PATH: The FLEXIBLAS_LIBRARY_PATH variable contains a colon separated list of addtional search paths for FlexiBLAS. The paths are used to find BLAS implementations and hooks.

REPORTING BUGS

The current information about the developers and reporting bugs can be found on the FlexiBLAS homepage.

FlexiBLAS Homepage: <http://www.mpi-magdeburg.mpg.de/projects/flexiblas>

AUTHORS

Martin Koehler, Jens Saak

COPYRIGHT

LICENSE

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.