OpenBLAS/README.md

# OpenBLAS

[![Join the chat at https://gitter.im/xianyi/OpenBLAS](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/xianyi/OpenBLAS?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Travis CI: [![Build Status](https://travis-ci.org/xianyi/OpenBLAS.png?branch=develop)](https://travis-ci.org/xianyi/OpenBLAS)

AppVeyor: [![Build status](https://ci.appveyor.com/api/projects/status/09sohd35n8nkkx64/branch/develop?svg=true)](https://ci.appveyor.com/project/xianyi/openblas/branch/develop)
## Introduction
OpenBLAS is an optimized BLAS library based on GotoBLAS2 1.13 BSD version.

Please read the documents on OpenBLAS wiki pages <http://github.com/xianyi/OpenBLAS/wiki>.

## Binary Packages
We provide binary packages for the following platform.

  * Windows x86/x86_64

You can download them from [file hosting on sourceforge.net](https://sourceforge.net/projects/openblas/files/).

## Installation from Source
Download from project homepage. http://xianyi.github.com/OpenBLAS/

Or, check out codes from git://github.com/xianyi/OpenBLAS.git
### Normal compile
  * type "make" to detect the CPU automatically.
  or
  * type "make TARGET=xxx" to set target CPU, e.g. "make TARGET=NEHALEM". The full target list is in file TargetList.txt.

### Cross compile
Please set CC and FC with the cross toolchains. Then, set HOSTCC with your host C compiler. At last, set TARGET explicitly.

Examples:

On X86 box, compile this library for loongson3a CPU.

    make BINARY=64 CC=mips64el-unknown-linux-gnu-gcc FC=mips64el-unknown-linux-gnu-gfortran HOSTCC=gcc TARGET=LOONGSON3A

On X86 box, compile this library for loongson3a CPU with loongcc (based on Open64) compiler.

    make CC=loongcc FC=loongf95 HOSTCC=gcc TARGET=LOONGSON3A CROSS=1 CROSS_SUFFIX=mips64el-st-linux-gnu-   NO_LAPACKE=1 NO_SHARED=1 BINARY=32

### Debug version

    make DEBUG=1

### Install to the directory (optional)

Example:

    make install PREFIX=your_installation_directory

The default directory is /opt/OpenBLAS

## Support CPU & OS
Please read GotoBLAS_01Readme.txt

### Additional support CPU:

#### x86/x86-64:
- **Intel Xeon 56xx (Westmere)**: Used GotoBLAS2 Nehalem codes.
- **Intel Sandy Bridge**: Optimized Level-3 and Level-2 BLAS with AVX on x86-64.
- **Intel Haswell**: Optimized Level-3 and Level-2 BLAS with AVX2 and FMA  on x86-64.
- **AMD Bobcat**: Used GotoBLAS2 Barcelona codes.
- **AMD Bulldozer**: x86-64 ?GEMM FMA4 kernels. (Thank Werner Saar)
- **AMD PILEDRIVER**: Uses Bulldozer codes with some optimizations.
- **AMD STEAMROLLER**: Uses Bulldozer codes with some optimizations.

#### MIPS64:
- **ICT Loongson 3A**: Optimized Level-3 BLAS and the part of Level-1,2.
- **ICT Loongson 3B**: Experimental

#### ARM:
- **ARMV6**: Optimized BLAS for vfpv2 and vfpv3-d16 ( e.g. BCM2835, Cortex M0+ )
- **ARMV7**: Optimized BLAS for vfpv3-d32 ( e.g. Cortex A8, A9 and A15 )

#### ARM64:
- **ARMV8**: Experimental
- **ARM Cortex-A57**: Experimental

### Support OS:
- **GNU/Linux**
- **MingWin or Visual Studio(CMake)/Windows**: Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-use-OpenBLAS-in-Microsoft-Visual-Studio>.
- **Darwin/Mac OS X**: Experimental. Although GotoBLAS2 supports Darwin, we are the beginner on Mac OS X.
- **FreeBSD**: Supported by community. We didn't test the library on this OS.
- **Android**: Supported by community. Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-build-OpenBLAS-for-Android>.

## Usages
Link with libopenblas.a or -lopenblas for shared library.

### Set the number of threads with environment variables.

Examples:

    export OPENBLAS_NUM_THREADS=4

 or

    export GOTO_NUM_THREADS=4

 or

    export OMP_NUM_THREADS=4

The priorities are OPENBLAS_NUM_THREADS > GOTO_NUM_THREADS > OMP_NUM_THREADS.

If you compile this lib with USE_OPENMP=1, you should set OMP_NUM_THREADS environment variable. OpenBLAS ignores OPENBLAS_NUM_THREADS and GOTO_NUM_THREADS with USE_OPENMP=1.

### Set the number of threads on runtime.

We provided the below functions to control the number of threads on runtime.

    void goto_set_num_threads(int num_threads);

    void openblas_set_num_threads(int num_threads);

If you compile this lib with USE_OPENMP=1, you should use the above functions, too.

## Report Bugs
Please add a issue in https://github.com/xianyi/OpenBLAS/issues

## Contact
* OpenBLAS users mailing list: https://groups.google.com/forum/#!forum/openblas-users
* OpenBLAS developers mailing list: https://groups.google.com/forum/#!forum/openblas-dev

## ChangeLog
Please see Changelog.txt to obtain the differences between GotoBLAS2 1.13 BSD version.

## Troubleshooting
* Please read [Faq](https://github.com/xianyi/OpenBLAS/wiki/Faq) at first.
* Please use gcc version 4.6 and above to compile Sandy Bridge AVX kernels on Linux/MingW/BSD.
* Please use Clang version 3.1 and above to compile the library on Sandy Bridge microarchitecture. The Clang 3.0 will generate the wrong AVX binary code.
* The number of CPUs/Cores should less than or equal to 256. On Linux x86_64(amd64), there is experimental support for up to 1024 CPUs/Cores and 128 numa nodes if you build the library with BIGNUMA=1.
* OpenBLAS does not set processor affinity by default. On Linux, you can enable processor affinity by commenting the line NO_AFFINITY=1 in Makefile.rule. But this may cause [the conflict with R parallel](https://stat.ethz.ch/pipermail/r-sig-hpc/2012-April/001348.html).
* On Loongson 3A. make test would be failed because of pthread_create error. The error code is EAGAIN. However, it will be OK when you run the same testcase on shell.

## Contributing
1. [Check for open issues](https://github.com/xianyi/OpenBLAS/issues) or open a fresh issue to start a discussion around a feature idea or a bug.
1. Fork the [OpenBLAS](https://github.com/xianyi/OpenBLAS) repository to start making your changes.
1. Write a test which shows that the bug was fixed or that the feature works as expected.
1. Send a pull request. Make sure to add yourself to `CONTRIBUTORS.md`.

## Donation
Please read [this wiki page](https://github.com/xianyi/OpenBLAS/wiki/Donation).
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`# OpenBLAS`
Added OpenBLAS docs. 2011-01-25 00:05:00 +08:00
Added Gitter badge 2015-08-20 11:21:09 +08:00			`[![Join the chat at https://gitter.im/xianyi/OpenBLAS](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/xianyi/OpenBLAS?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)`

Add AppVeyor badge. 2015-10-27 07:14:41 +08:00			`Travis CI: [![Build Status](https://travis-ci.org/xianyi/OpenBLAS.png?branch=develop)](https://travis-ci.org/xianyi/OpenBLAS)`
Added Travis CI status image. 2013-07-05 15:28:41 +08:00
Add AppVeyor badge. 2015-10-27 07:14:41 +08:00			`AppVeyor: [![Build status](https://ci.appveyor.com/api/projects/status/09sohd35n8nkkx64/branch/develop?svg=true)](https://ci.appveyor.com/project/xianyi/openblas/branch/develop)`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`## Introduction`
Remove all trailing whitespace except lapack-netlib Signed-off-by: Timothy Gu <timothygu99@gmail.com> 2014-06-28 03:05:18 +08:00			`OpenBLAS is an optimized BLAS library based on GotoBLAS2 1.13 BSD version.`
Added OpenBLAS docs. 2011-01-25 00:05:00 +08:00
Modified readme. 2012-06-23 08:34:40 +08:00			`Please read the documents on OpenBLAS wiki pages <http://github.com/xianyi/OpenBLAS/wiki>.`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00
Fixed #254. Added the date of changes in contributors file. 2013-07-20 11:35:27 +08:00			`## Binary Packages`
			`We provide binary packages for the following platform.`

			`* Windows x86/x86_64`

			`You can download them from [file hosting on sourceforge.net](https://sourceforge.net/projects/openblas/files/).`

			`## Installation from Source`
Updated readme file. 2011-02-19 00:18:17 +08:00			`Download from project homepage. http://xianyi.github.com/OpenBLAS/`
Modified readme. 2012-06-23 08:34:40 +08:00
			`Or, check out codes from git://github.com/xianyi/OpenBLAS.git`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`### Normal compile`
			`* type "make" to detect the CPU automatically.`
Added docs for make TARGET=your_cpu_target. 2011-04-22 22:07:46 +08:00			`or`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`* type "make TARGET=xxx" to set target CPU, e.g. "make TARGET=NEHALEM". The full target list is in file TargetList.txt.`
Added OpenBLAS docs. 2011-01-25 00:05:00 +08:00
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`### Cross compile`
Updated readme for cross compiling. 2011-01-25 16:52:36 +08:00			`Please set CC and FC with the cross toolchains. Then, set HOSTCC with your host C compiler. At last, set TARGET explicitly.`

Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`Examples:`

Updated readme for cross compiling. 2011-01-25 16:52:36 +08:00			`On X86 box, compile this library for loongson3a CPU.`

Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`make BINARY=64 CC=mips64el-unknown-linux-gnu-gcc FC=mips64el-unknown-linux-gnu-gfortran HOSTCC=gcc TARGET=LOONGSON3A`

Added the configuration of Loongcc compiler for Loongson 3 CPU. 2013-04-07 15:42:07 +08:00			`On X86 box, compile this library for loongson3a CPU with loongcc (based on Open64) compiler.`

			`make CC=loongcc FC=loongf95 HOSTCC=gcc TARGET=LOONGSON3A CROSS=1 CROSS_SUFFIX=mips64el-st-linux-gnu- NO_LAPACKE=1 NO_SHARED=1 BINARY=32`

Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`### Debug version`

			`make DEBUG=1`

Fix miscellaneous typos 2013-07-01 00:36:13 +08:00			`### Install to the directory (optional)`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00
			`Example:`

			`make install PREFIX=your_installation_directory`
Supported building debug version. 2011-02-22 13:40:40 +08:00
Refs #20. Updated the docs. 2011-06-20 18:36:29 +08:00			`The default directory is /opt/OpenBLAS`

Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`## Support CPU & OS`
Added OpenBLAS docs. 2011-01-25 00:05:00 +08:00			`Please read GotoBLAS_01Readme.txt`

Modified readme. 2012-06-23 08:34:40 +08:00			`### Additional support CPU:`

			`#### x86/x86-64:`
Correct the error in readme 2012-06-23 09:35:19 +08:00			`- Intel Xeon 56xx (Westmere): Used GotoBLAS2 Nehalem codes.`
updated README.md 2014-09-17 22:01:07 +08:00			`- Intel Sandy Bridge: Optimized Level-3 and Level-2 BLAS with AVX on x86-64.`
			`- Intel Haswell: Optimized Level-3 and Level-2 BLAS with AVX2 and FMA on x86-64.`
Correct the error in readme 2012-06-23 09:35:19 +08:00			`- AMD Bobcat: Used GotoBLAS2 Barcelona codes.`
updated README.md 2014-09-17 22:01:07 +08:00			`- AMD Bulldozer: x86-64 ?GEMM FMA4 kernels. (Thank Werner Saar)`
			`- AMD PILEDRIVER: Uses Bulldozer codes with some optimizations.`
added target processor STEAMROLLER 2014-12-28 20:16:46 +08:00			`- AMD STEAMROLLER: Uses Bulldozer codes with some optimizations.`
Correct the error in readme 2012-06-23 09:35:19 +08:00
Modified readme. 2012-06-23 08:34:40 +08:00			`#### MIPS64:`
Correct the error in readme 2012-06-23 09:35:19 +08:00			`- ICT Loongson 3A: Optimized Level-3 BLAS and the part of Level-1,2.`
			`- ICT Loongson 3B: Experimental`

updated README.md 2014-09-17 22:01:07 +08:00			`#### ARM:`
			`- ARMV6: Optimized BLAS for vfpv2 and vfpv3-d16 ( e.g. BCM2835, Cortex M0+ )`
			`- ARMV7: Optimized BLAS for vfpv3-d32 ( e.g. Cortex A8, A9 and A15 )`

			`#### ARM64:`
			`- ARMV8: Experimental`
Update readme. 2016-02-13 00:33:53 +08:00			`- ARM Cortex-A57: Experimental`
updated README.md 2014-09-17 22:01:07 +08:00
Correct the error in readme 2012-06-23 09:35:19 +08:00			`### Support OS:`
			`- GNU/Linux`
Update readme. 2016-02-13 00:33:53 +08:00			`- MingWin or Visual Studio(CMake)/Windows: Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-use-OpenBLAS-in-Microsoft-Visual-Studio>.`
Correct the error in readme 2012-06-23 09:35:19 +08:00			`- Darwin/Mac OS X: Experimental. Although GotoBLAS2 supports Darwin, we are the beginner on Mac OS X.`
Fix miscellaneous typos 2013-07-01 00:36:13 +08:00			`- FreeBSD: Supported by community. We didn't test the library on this OS.`
Added Android as a community-supported OS 2016-04-26 18:14:03 +08:00			`- Android: Supported by community. Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-build-OpenBLAS-for-Android>.`
Updated readme file. 2011-02-19 00:18:17 +08:00
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`## Usages`
Updated readme file. 2011-01-25 02:12:06 +08:00			`Link with libopenblas.a or -lopenblas for shared library.`
Added OpenBLAS docs. 2011-01-25 00:05:00 +08:00
Remove all trailing whitespace except lapack-netlib Signed-off-by: Timothy Gu <timothygu99@gmail.com> 2014-06-28 03:05:18 +08:00			`### Set the number of threads with environment variables.`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00
			`Examples:`
Modified readme. 2012-06-23 08:34:40 +08:00
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`export OPENBLAS_NUM_THREADS=4`

Fixed #10. Supported GOTO_NUM_THREADS & GOTO_THREADS_TIMEOUT environment variables. 2011-02-24 15:16:21 +08:00			`or`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00
			`export GOTO_NUM_THREADS=4`

Remove all trailing whitespace except lapack-netlib Signed-off-by: Timothy Gu <timothygu99@gmail.com> 2014-06-28 03:05:18 +08:00			`or`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00
			`export OMP_NUM_THREADS=4`
Fixed #10. Supported GOTO_NUM_THREADS & GOTO_THREADS_TIMEOUT environment variables. 2011-02-24 15:16:21 +08:00
Fixed #14 the SEGFAULT bug on 64 cores. On SMP server, the number of CPUs or cores should be less than or equal to 64. 2011-03-28 10:58:39 +08:00			`The priorities are OPENBLAS_NUM_THREADS > GOTO_NUM_THREADS > OMP_NUM_THREADS.`

ref #62. Added the user friendly message with USE_OPENMP=1. The users should use OMP_NUM_THREADS. When OpenBLAS is compiled with USE_OPENMP=1, it ignores OPENBLAS_NUM_THREADS and GOTO_NUM_THREADS flags.Therefore, you should use OMP_NUM_THREADS. Without setting OMP_NUM_THREADS, a process will use maximal number of threads on a computing node. Thus, if there are 2 processes on the computing node, the thread will contend against other threads on CPU cores. As a result, the application will hang. 2011-10-09 15:14:48 +08:00			`If you compile this lib with USE_OPENMP=1, you should set OMP_NUM_THREADS environment variable. OpenBLAS ignores OPENBLAS_NUM_THREADS and GOTO_NUM_THREADS with USE_OPENMP=1.`
Fixed #10. Supported GOTO_NUM_THREADS & GOTO_THREADS_TIMEOUT environment variables. 2011-02-24 15:16:21 +08:00
Remove all trailing whitespace except lapack-netlib Signed-off-by: Timothy Gu <timothygu99@gmail.com> 2014-06-28 03:05:18 +08:00			`### Set the number of threads on runtime.`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00
Fix miscellaneous typos 2013-07-01 00:36:13 +08:00			`We provided the below functions to control the number of threads on runtime.`
Modified readme. 2012-06-23 08:34:40 +08:00
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`void goto_set_num_threads(int num_threads);`
Modified readme. 2012-06-23 08:34:40 +08:00
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`void openblas_set_num_threads(int num_threads);`
Updated readme file. 2011-01-25 02:12:06 +08:00
Fixed #14 the SEGFAULT bug on 64 cores. On SMP server, the number of CPUs or cores should be less than or equal to 64. 2011-03-28 10:58:39 +08:00			`If you compile this lib with USE_OPENMP=1, you should use the above functions, too.`

Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`## Report Bugs`
Updated readme file. 2011-01-25 02:12:06 +08:00			`Please add a issue in https://github.com/xianyi/OpenBLAS/issues`
Added OpenBLAS docs. 2011-01-25 00:05:00 +08:00
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`## Contact`
Updated the mailing list for OpenBLAS. 2013-04-25 00:45:42 +08:00			`* OpenBLAS users mailing list: https://groups.google.com/forum/#!forum/openblas-users`
			`* OpenBLAS developers mailing list: https://groups.google.com/forum/#!forum/openblas-dev`
Added Changelog. Fixed #11. 2011-02-26 12:27:56 +08:00
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`## ChangeLog`
Fixed #14 the SEGFAULT bug on 64 cores. On SMP server, the number of CPUs or cores should be less than or equal to 64. 2011-03-28 10:58:39 +08:00			`Please see Changelog.txt to obtain the differences between GotoBLAS2 1.13 BSD version.`

Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`## Troubleshooting`
Don't use xgetbv instruction when NO_AVX=1 2012-10-09 14:52:35 +08:00			`* Please read [Faq](https://github.com/xianyi/OpenBLAS/wiki/Faq) at first.`
Update the docs for 0.2.0 2012-06-23 08:22:53 +08:00			`* Please use gcc version 4.6 and above to compile Sandy Bridge AVX kernels on Linux/MingW/BSD.`
Refs #83. Clang 3.1 works fine on Sandy Bridge Mac OSX. Edit the document. 2012-06-21 08:25:52 +08:00			`* Please use Clang version 3.1 and above to compile the library on Sandy Bridge microarchitecture. The Clang 3.0 will generate the wrong AVX binary code.`
updated README.md 2014-09-17 22:01:07 +08:00			`* The number of CPUs/Cores should less than or equal to 256. On Linux x86_64(amd64), there is experimental support for up to 1024 CPUs/Cores and 128 numa nodes if you build the library with BIGNUMA=1.`
			`* OpenBLAS does not set processor affinity by default. On Linux, you can enable processor affinity by commenting the line NO_AFFINITY=1 in Makefile.rule. But this may cause [the conflict with R parallel](https://stat.ethz.ch/pipermail/r-sig-hpc/2012-April/001348.html).`
Remove all trailing whitespace except lapack-netlib Signed-off-by: Timothy Gu <timothygu99@gmail.com> 2014-06-28 03:05:18 +08:00			`* On Loongson 3A. make test would be failed because of pthread_create error. The error code is EAGAIN. However, it will be OK when you run the same testcase on shell.`
Added the spec of git branches about this project. 2011-05-12 19:05:20 +08:00
Fixed #254. Added the date of changes in contributors file. 2013-07-20 11:35:27 +08:00			`## Contributing`
Remove all trailing whitespace except lapack-netlib Signed-off-by: Timothy Gu <timothygu99@gmail.com> 2014-06-28 03:05:18 +08:00			`1. [Check for open issues](https://github.com/xianyi/OpenBLAS/issues) or open a fresh issue to start a discussion around a feature idea or a bug.`
Fixed #254. Added the date of changes in contributors file. 2013-07-20 11:35:27 +08:00			`1. Fork the [OpenBLAS](https://github.com/xianyi/OpenBLAS) repository to start making your changes.`
			`1. Write a test which shows that the bug was fixed or that the feature works as expected.`
			1. Send a pull request. Make sure to add yourself to `CONTRIBUTORS.md`.

Added backers. 2013-09-05 15:39:45 +08:00			`## Donation`
			`Please read [this wiki page](https://github.com/xianyi/OpenBLAS/wiki/Donation).`