GitHub - OpenMathLib/OpenBLAS: OpenBLAS is an optimized BLAS library based on GotoBLAS2 1.13 BSD version. (original) (raw)

OpenBLAS

Join the chat at https://gitter.im/xianyi/OpenBLAS

Cirrus CI: Build Status

Build Status

OSUOSL POWERCI Build Status

OSUOSL IBMZ-CI Build Status

Introduction

OpenBLAS is an optimized BLAS (Basic Linear Algebra Subprograms) library based on GotoBLAS2 1.13 BSD version.

For more information about OpenBLAS, please see:

For a general introduction to the BLAS routines, please refer to the extensive documentation of their reference implementation hosted at netlib:https://www.netlib.org/blas. On that site you will likewise find documentation for the reference implementation of the higher-level library LAPACK - the Linear Algebra Package that comes included with OpenBLAS. If you are looking for a general primer or refresher on Linear Algebra, the set of six 20-minute lecture videos by Prof. Gilbert Strang on either MIT OpenCourseWare here or YouTube here may be helpful.

Binary Packages

We provide official binary packages for the following platform:

You can download them from file hosting on sourceforge.net or from the Releases section of the GitHub project page.

OpenBLAS is also packaged for many package managers - see the installation section of the docs for details.

Installation from Source

Obtain the source code from https://github.com/OpenMathLib/OpenBLAS/. Note that the default branch is develop (a master branch is still present, but far out of date).

Build-time parameters can be chosen in Makefile.rule, see there for a short description of each option. Most options can also be given directly on the command line as parameters to your make or cmake invocation.

Dependencies

Building OpenBLAS requires the following to be installed:

In general, using a recent version of the compiler is strongly recommended. If a Fortran compiler is not available, it is possible to compile an older version of the included LAPACK that has been machine-translated to C.

Normal compile

Simply invoking make (or gmake on BSD) will detect the CPU automatically. To set a specific target CPU, use make TARGET=xxx, e.g. make TARGET=NEHALEM. The full target list is in the file TargetList.txt, other build optionss are documented in Makefile.rule and can either be set there (typically by removing the comment character from the respective line), or used on themake command line. Note that when you run make install after building, you need to repeat all command line options you provided to makein the build step, as some settings like the supported maximum number of threads are automatically derived from the build host by default, which might not be what you want. For building with cmake, the usual conventions apply, i.e. create a build directory either underneath the toplevel OpenBLAS source directory or separate from it, and invoke cmake there with the path to the source tree and any build options you plan to set.

For more details, see the Building from sourcesection in the docs.

Cross compile

Set CC and FC to point to the cross toolchains, and if you use make, also set HOSTCC to your host C compiler. The target must be specified explicitly when cross compiling.

Examples:

make CC="i686-w64-mingw32-gcc -Bstatic" FC="i686-w64-mingw32-gfortran -static-libgfortran" TARGET=HASWELL BINARY=32 CROSS=1 NUM_THREADS=20 CONSISTENT_FPCSR=1 HOSTCC=gcc

You can find instructions for other cases both in the "Supported Systems" section below and in the Building from source docs. The .yml scripts included with the sources (which contain the build scripts for the "continuous integration" (CI) build tests automatically run on every proposed change to the sources) may also provide additional hints.

When compiling for a more modern CPU target of the same architecture, e.g. TARGET=SKYLAKEX on a HASWELL host, option CROSS=1 can be used to suppress the automatic invocation of the tests at the end of the build.

Debug version

A debug version can be built using make DEBUG=1.

Compile with MASS support on Power CPU (optional)

The IBM MASS library consists of a set of mathematical functions for C, C++, and Fortran applications that are tuned for optimum performance on POWER architectures. OpenBLAS with MASS requires a 64-bit, little-endian OS on POWER. The library can be installed as shown:

After installing the MASS library, compile OpenBLAS with USE_MASS=1. For example, to compile on Power8 with MASS support: make USE_MASS=1 TARGET=POWER8.

Install to a specific directory (optional)

Use PREFIX= when invoking make, for example

make install PREFIX=your_installation_directory

(along with all options you added on the make command line in the preceding build step) The default installation directory is /opt/OpenBLAS.

Supported CPUs and Operating Systems

Please read GotoBLAS_01Readme.txt for older CPU models already supported by the 2010 GotoBLAS.

Additional supported CPUs

x86/x86-64

MIPS32

MIPS64

ARM

ARM64

PPC/PPC64

IBM zEnterprise System

RISC-V

LOONGARCH64

Support for multiple targets in a single library

OpenBLAS can be built for multiple targets with runtime detection of the target cpu by specifiying DYNAMIC_ARCH=1 in Makefile.rule, on the gmake command line or as -DDYNAMIC_ARCH=TRUE in cmake.

For x86_64, the list of targets this activates contains Prescott, Core2, Nehalem, Barcelona, Sandybridge, Bulldozer, Piledriver, Steamroller, Excavator, Haswell, Zen, SkylakeX, Cooper Lake, Sapphire Rapids. For cpu generations not included in this list, the corresponding older model is used. If you also specify DYNAMIC_OLDER=1, specific support for Penryn, Dunnington, Opteron, Opteron/SSE3, Bobcat, Atom and Nano is added. Finally there is an option DYNAMIC_LIST that allows to specify an individual list of targets to include instead of the default.

DYNAMIC_ARCH is also supported on x86, where it translates to Katmai, Coppermine, Northwood, Prescott, Banias, Core2, Penryn, Dunnington, Nehalem, Athlon, Opteron, Opteron_SSE3, Barcelona, Bobcat, Atom and Nano.

On ARMV8, it enables support for CortexA53, CortexA57, CortexA72, CortexA73, Falkor, ThunderX, ThunderX2T99, TSV110 as well as generic ARMV8 cpus. If compiler support for SVE is available at build time, support for NeoverseN2, NeoverseV1 as well as generic ArmV8SVE targets is also enabled.

For POWER, the list encompasses POWER6, POWER8 and POWER9. POWER10 is additionally available if a sufficiently recent compiler is used for the build.

on ZARCH it comprises Z13 and Z14 as well as generic zarch support.

On riscv64, DYNAMIC_ARCH enables support for riscv64_zvl128b and riscv64_zvl256b in addition to generic riscv64 support. A compiler that supports RVV 1.0 is required to build OpenBLAS for riscv64 when DYNAMIC_ARCH is enabled.

On LoongArch64, it comprises LA264 and LA464 as well as generic LoongArch64 support.

The TARGET option can - and usually should - be used in conjunction with DYNAMIC_ARCH=1 to specify which cpu model should be assumed for all the common code in the library, usually you will want to set this to the oldest model you expect to encounter. Failure to specify this may lead to advanced instructions being used by the compiler, just because the build host happens to support them. This is most likely to happen when aggressive optimization options are in effect, and the resulting library may then crash with an illegal instruction error on weaker hardware, before it even reaches the BLAS routines specifically included for that cpu.

Please note that it is not possible to combine support for different architectures, so no combined 32 and 64 bit or x86_64 and arm64 in the same library.

Supported OS

Usage

Statically link with libopenblas.a or dynamically link with -lopenblas if OpenBLAS was compiled as a shared library.

Setting the number of threads using environment variables

Environment variables are used to specify a maximum number of threads. For example,

export OPENBLAS_NUM_THREADS=4 export GOTO_NUM_THREADS=4 export OMP_NUM_THREADS=4

The priorities are OPENBLAS_NUM_THREADS > GOTO_NUM_THREADS > OMP_NUM_THREADS.

If you compile this library with USE_OPENMP=1, you should set the OMP_NUM_THREADSenvironment variable; OpenBLAS ignores OPENBLAS_NUM_THREADS and GOTO_NUM_THREADS when compiled with USE_OPENMP=1.

Setting the number of threads at runtime

We provide the following functions to control the number of threads at runtime:

void goto_set_num_threads(int num_threads); void openblas_set_num_threads(int num_threads);

Note that these are only used once at library initialization, and are not available for fine-tuning thread numbers in individual BLAS calls. If you compile this library with USE_OPENMP=1, you should use the above functions too.

Reporting bugs

Please submit an issue in https://github.com/OpenMathLib/OpenBLAS/issues.

Contact

Change log

Please see Changelog.txt.

Troubleshooting

Contributing

  1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
  2. Fork the OpenBLAS repository to start making your changes.
  3. Write a test which shows that the bug was fixed or that the feature works as expected.
  4. Send a pull request. Make sure to add yourself to CONTRIBUTORS.md.

Donation

Please see the donations section in the docs.