README.md

   1 # OpenBLAS
   2
   3 [![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)
   4
   5 Travis CI: [![Build Status](https://travis-ci.org/xianyi/OpenBLAS.svg?branch=develop)](https://travis-ci.org/xianyi/OpenBLAS)
   6
   7 AppVeyor: [![Build status](https://ci.appveyor.com/api/projects/status/09sohd35n8nkkx64/branch/develop?svg=true)](https://ci.appveyor.com/project/xianyi/openblas/branch/develop)
   8
   9 [![Build Status](https://dev.azure.com/xianyi/OpenBLAS/_apis/build/status/xianyi.OpenBLAS?branchName=develop)](https://dev.azure.com/xianyi/OpenBLAS/_build/latest?definitionId=1&branchName=develop)
  10
  11 ## Introduction
  12
  13 OpenBLAS is an optimized BLAS library based on GotoBLAS2 1.13 BSD version.
  14
  15 Please read the documentation on the OpenBLAS wiki pages: <https://github.com/xianyi/OpenBLAS/wiki>.
  16
  17 ## Binary Packages
  18
  19 We provide official binary packages for the following platform:
  20
  21   * Windows x86/x86_64
  22
  23 You can download them from [file hosting on sourceforge.net](https://sourceforge.net/projects/openblas/files/).
  24
  25 ## Installation from Source
  26
  27 Download from project homepage, https://xianyi.github.com/OpenBLAS/, or check out the code
  28 using Git from https://github.com/xianyi/OpenBLAS.git.
  29 Buildtime parameters can be chosen in Makefile.rule, see there for a short description of each option.
  30 Most can also be given directly on the make or cmake command line.
  31
  32 ### Dependencies
  33
  34 Building OpenBLAS requires the following to be installed:
  35
  36 * GNU Make
  37 * A C compiler, e.g. GCC or Clang
  38 * A Fortran compiler (optional, for LAPACK)
  39 * IBM MASS (optional, see below)
  40
  41 ### Normal compile
  42
  43 Simply invoking `make` (or `gmake` on BSD) will detect the CPU automatically.
  44 To set a specific target CPU, use `make TARGET=xxx`, e.g. `make TARGET=NEHALEM`.
  45 The full target list is in the file `TargetList.txt`.
  46
  47 ### Cross compile
  48
  49 Set `CC` and `FC` to point to the cross toolchains, and set `HOSTCC` to your host C compiler.
  50 The target must be specified explicitly when cross compiling.
  51
  52 Examples:
  53
  54 * On an x86 box, compile this library for a loongson3a CPU:
  55   ```sh
  56   make BINARY=64 CC=mips64el-unknown-linux-gnu-gcc FC=mips64el-unknown-linux-gnu-gfortran HOSTCC=gcc TARGET=LOONGSON3A
  57   ```
  58
  59 * On an x86 box, compile this library for a loongson3a CPU with loongcc (based on Open64) compiler:
  60   ```sh
  61   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
  62   ```
  63
  64 ### Debug version
  65
  66 A debug version can be built using `make DEBUG=1`.
  67
  68 ### Compile with MASS support on Power CPU (optional)
  69
  70 The [IBM MASS](https://www.ibm.com/support/home/product/W511326D80541V01/other_software/mathematical_acceleration_subsystem) library consists of a set of mathematical functions for C, C++, and Fortran applications that are tuned for optimum performance on POWER architectures.
  71 OpenBLAS with MASS requires a 64-bit, little-endian OS on POWER.
  72 The library can be installed as shown:
  73
  74 * On Ubuntu:
  75   ```sh
  76   wget -q http://public.dhe.ibm.com/software/server/POWER/Linux/xl-compiler/eval/ppc64le/ubuntu/public.gpg -O- | sudo apt-key add -
  77   echo "deb http://public.dhe.ibm.com/software/server/POWER/Linux/xl-compiler/eval/ppc64le/ubuntu/ trusty main" | sudo tee /etc/apt/sources.list.d/ibm-xl-compiler-eval.list
  78   sudo apt-get update
  79   sudo apt-get install libxlmass-devel.8.1.5
  80   ```
  81
  82 * On RHEL/CentOS:
  83   ```sh
  84   wget http://public.dhe.ibm.com/software/server/POWER/Linux/xl-compiler/eval/ppc64le/rhel7/repodata/repomd.xml.key
  85   sudo rpm --import repomd.xml.key
  86   wget http://public.dhe.ibm.com/software/server/POWER/Linux/xl-compiler/eval/ppc64le/rhel7/ibm-xl-compiler-eval.repo
  87   sudo cp ibm-xl-compiler-eval.repo /etc/yum.repos.d/
  88   sudo yum install libxlmass-devel.8.1.5
  89   ```
  90
  91 After installing the MASS library, compile OpenBLAS with `USE_MASS=1`.
  92 For example, to compile on Power8 with MASS support: `make USE_MASS=1 TARGET=POWER8`.
  93
  94 ### Install to a specific directory (optional)
  95
  96 Use `PREFIX=` when invoking `make`, for example
  97
  98 ```sh
  99 make install PREFIX=your_installation_directory
 100 ```
 101
 102 The default installation directory is `/opt/OpenBLAS`.
 103
 104 ## Supported CPUs and Operating Systems
 105
 106 Please read `GotoBLAS_01Readme.txt` for older CPU models already supported by the 2010 GotoBLAS.
 107
 108 ### Additional supported CPUs
 109
 110 #### x86/x86-64
 111
 112 - **Intel Xeon 56xx (Westmere)**: Used GotoBLAS2 Nehalem codes.
 113 - **Intel Sandy Bridge**: Optimized Level-3 and Level-2 BLAS with AVX on x86-64.
 114 - **Intel Haswell**: Optimized Level-3 and Level-2 BLAS with AVX2 and FMA on x86-64.
 115 - **Intel Skylake-X**: Optimized Level-3 and Level-2 BLAS with AVX512 and FMA on x86-64.
 116 - **AMD Bobcat**: Used GotoBLAS2 Barcelona codes.
 117 - **AMD Bulldozer**: x86-64 ?GEMM FMA4 kernels. (Thanks to Werner Saar)
 118 - **AMD PILEDRIVER**: Uses Bulldozer codes with some optimizations.
 119 - **AMD STEAMROLLER**: Uses Bulldozer codes with some optimizations.
 120 - **AMD ZEN**: Uses Haswell codes with some optimizations.
 121
 122 #### MIPS64
 123
 124 - **ICT Loongson 3A**: Optimized Level-3 BLAS and the part of Level-1,2.
 125 - **ICT Loongson 3B**: Experimental
 126
 127 #### ARM
 128
 129 - **ARMv6**: Optimized BLAS for vfpv2 and vfpv3-d16 (e.g. BCM2835, Cortex M0+)
 130 - **ARMv7**: Optimized BLAS for vfpv3-d32 (e.g. Cortex A8, A9 and A15)
 131
 132 #### ARM64
 133
 134 - **ARMv8**: Basic ARMV8 with small caches, optimized Level-3 and Level-2 BLAS
 135 - **Cortex-A53**: same as ARMV8 (different cpu specifications)
 136 - **Cortex A57**: Optimized Level-3 and Level-2 functions
 137 - **Cortex A72**: same as A57 ( different cpu specifications)
 138 - **Cortex A73**: same as A57 (different cpu specifications)
 139 - **Falkor**: same as A57 (different cpu specifications)
 140 - **ThunderX**: Optimized some Level-1 functions
 141 - **ThunderX2T99**: Optimized Level-3 BLAS and parts of Levels 1 and 2
 142 - **TSV110**: Optimized some Level-3 helper functions
 143
 144 #### PPC/PPC64
 145
 146 - **POWER8**: Optimized BLAS, only for PPC64LE (Little Endian), only with `USE_OPENMP=1`
 147 - **POWER9**: Optimized Level-3 BLAS (real) and some Level-1,2. PPC64LE with OpenMP only.
 148
 149 #### IBM zEnterprise System
 150
 151 - **Z13**: Optimized Level-3 BLAS and Level-1,2
 152 - **Z14**: Optimized Level-3 BLAS and (single precision) Level-1,2
 153
 154 ### Support for multiple targets in a single library
 155
 156 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.
 157 For **x86_64**, the list of targets this activates contains Prescott, Core2, Nehalem, Barcelona, Sandybridge, Bulldozer, Piledriver, Steamroller, Excavator, Haswell, Zen, SkylakeX. 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.
 158 DYNAMIC_ARCH is also supported on **x86**, where it translates to Katmai, Coppermine, Northwood, Prescott, Banias,
 159 Core2, Penryn, Dunnington, Nehalem, Athlon, Opteron, Opteron_SSE3, Barcelona, Bobcat, Atom and Nano.
 160 On **ARMV8**, it enables support for CortexA53, CortexA57, CortexA72, CortexA73, Falkor, ThunderX, ThunderX2T99, TSV110 as well as generic ARMV8 cpus.
 161 For **POWER**, the list encompasses POWER6, POWER8 and POWER9, on **ZARCH** it comprises Z13 and Z14.
 162 The TARGET option can be used in conjunction with DYNAMIC_ARCH=1 to specify which cpu model should be assumed for all the
 163 common code in the library, usually you will want to set this to the oldest model you expect to encounter.
 164 Please not 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.
 165
 166 ### Supported OS
 167
 168 - **GNU/Linux**
 169 - **MinGW or Visual Studio (CMake)/Windows**: Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-use-OpenBLAS-in-Microsoft-Visual-Studio>.
 170 - **Darwin/macOS/OSX/iOS**: Experimental. Although GotoBLAS2 already supports Darwin, we are not OSX/iOS experts.
 171 - **FreeBSD**: Supported by the community. We don't actively test the library on this OS.
 172 - **OpenBSD**: Supported by the community. We don't actively test the library on this OS.
 173 - **NetBSD**: Supported by the community. We don't actively test the library on this OS.
 174 - **DragonFly BSD**: Supported by the community. We don't actively test the library on this OS.
 175 - **Android**: Supported by the community. Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-build-OpenBLAS-for-Android>.
 176 - **AIX**: Supported on PPC up to POWER8
 177 - **Haiku**: Supported by the community. We don't actively test the library on this OS.
 178 - **SunOS**: Supported by the community. We don't actively test the library on this OS:
 179
 180 ## Usage
 181
 182 Statically link with `libopenblas.a` or dynamically link with `-lopenblas` if OpenBLAS was
 183 compiled as a shared library.
 184
 185 ### Setting the number of threads using environment variables
 186
 187 Environment variables are used to specify a maximum number of threads.
 188 For example,
 189
 190 ```sh
 191 export OPENBLAS_NUM_THREADS=4
 192 export GOTO_NUM_THREADS=4
 193 export OMP_NUM_THREADS=4
 194 ```
 195
 196 The priorities are `OPENBLAS_NUM_THREADS` > `GOTO_NUM_THREADS` > `OMP_NUM_THREADS`.
 197
 198 If you compile this library with `USE_OPENMP=1`, you should set the `OMP_NUM_THREADS`
 199 environment variable; OpenBLAS ignores `OPENBLAS_NUM_THREADS` and `GOTO_NUM_THREADS` when
 200 compiled with `USE_OPENMP=1`.
 201
 202 ### Setting the number of threads at runtime
 203
 204 We provide the following functions to control the number of threads at runtime:
 205
 206 ```c
 207 void goto_set_num_threads(int num_threads);
 208 void openblas_set_num_threads(int num_threads);
 209 ```
 210
 211 If you compile this library with `USE_OPENMP=1`, you should use the above functions too.
 212
 213 ## Reporting bugs
 214
 215 Please submit an issue in https://github.com/xianyi/OpenBLAS/issues.
 216
 217 ## Contact
 218
 219 * OpenBLAS users mailing list: https://groups.google.com/forum/#!forum/openblas-users
 220 * OpenBLAS developers mailing list: https://groups.google.com/forum/#!forum/openblas-dev
 221
 222 ## Change log
 223
 224 Please see Changelog.txt to view the differences between OpenBLAS and GotoBLAS2 1.13 BSD version.
 225
 226 ## Troubleshooting
 227
 228 * Please read the [FAQ](https://github.com/xianyi/OpenBLAS/wiki/Faq) first.
 229 * Please use GCC version 4.6 and above to compile Sandy Bridge AVX kernels on Linux/MinGW/BSD.
 230 * Please use Clang version 3.1 and above to compile the library on Sandy Bridge microarchitecture.
 231   Clang 3.0 will generate the wrong AVX binary code.
 232 * Please use GCC version 6 or LLVM version 6 and above to compile Skylake AVX512 kernels.
 233 * The number of CPUs/cores should less than or equal to 256. On Linux `x86_64` (`amd64`),
 234   there is experimental support for up to 1024 CPUs/cores and 128 numa nodes if you build
 235   the library with `BIGNUMA=1`.
 236 * OpenBLAS does not set processor affinity by default.
 237   On Linux, you can enable processor affinity by commenting out the line `NO_AFFINITY=1` in
 238   Makefile.rule. However, note that this may cause
 239   [a conflict with R parallel](https://stat.ethz.ch/pipermail/r-sig-hpc/2012-April/001348.html).
 240 * On Loongson 3A, `make test` may fail with a `pthread_create` error (`EAGAIN`).
 241   However, it will be okay when you run the same test case on the shell.
 242
 243 ## Contributing
 244
 245 1. [Check for open issues](https://github.com/xianyi/OpenBLAS/issues) or open a fresh issue
 246    to start a discussion around a feature idea or a bug.
 247 2. Fork the [OpenBLAS](https://github.com/xianyi/OpenBLAS) repository to start making your changes.
 248 3. Write a test which shows that the bug was fixed or that the feature works as expected.
 249 4. Send a pull request. Make sure to add yourself to `CONTRIBUTORS.md`.
 250
 251 ## Donation
 252
 253 Please read [this wiki page](https://github.com/xianyi/OpenBLAS/wiki/Donation).