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.com/xianyi/OpenBLAS.svg?branch=develop)](https://travis-ci.com/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 Drone CI: [![Build Status](https://cloud.drone.io/api/badges/xianyi/OpenBLAS/status.svg?branch=develop)](https://cloud.drone.io/xianyi/OpenBLAS/)
  10
  11 [![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)
  12
  13
  14 ## Introduction
  15
  16 OpenBLAS is an optimized BLAS (Basic Linear Algebra Subprograms) library based on GotoBLAS2 1.13 BSD version.
  17
  18 Please read the documentation on the OpenBLAS wiki pages: <https://github.com/xianyi/OpenBLAS/wiki>.
  19
  20 For a general introduction to the BLAS routines, please refer to the extensive documentation of their reference implementation hosted at netlib:
  21 <https://www.netlib.org/blas>. On that site you will likewise find documentation for the reference implementation of the higher-level library LAPACK - the **L**inear **A**lgebra **Pack**age that comes included with OpenBLAS. If you are looking for a general primer or refresher on Linear Algebra, the set of six
  22 20-minute lecture videos by Prof. Gilbert Strang on either MIT OpenCourseWare <https://ocw.mit.edu/resources/res-18-010-a-2020-vision-of-linear-algebra-spring-2020/> or Youtube <https://www.youtube.com/playlist?list=PLUl4u3cNGP61iQEFiWLE21EJCxwmWvvek> may be helpful.
  23
  24 ## Binary Packages
  25
  26 We provide official binary packages for the following platform:
  27
  28   * Windows x86/x86_64
  29
  30 You can download them from [file hosting on sourceforge.net](https://sourceforge.net/projects/openblas/files/) or from the Releases section of the github project page, [https://github.com/xianyi/OpenBLAS/releases](https://github.com/xianyi/OpenBLAS/releases).
  31
  32 ## Installation from Source
  33
  34 Download from project homepage, https://xianyi.github.com/OpenBLAS/, or check out the code
  35 using Git from https://github.com/xianyi/OpenBLAS.git. (If you want the most up to date version, be
  36 sure to use the develop branch - master is several years out of date due to a change of maintainership.)
  37 Buildtime parameters can be chosen in Makefile.rule, see there for a short description of each option.
  38 Most can also be given directly on the make or cmake command line.
  39
  40 ### Dependencies
  41
  42 Building OpenBLAS requires the following to be installed:
  43
  44 * GNU Make
  45 * A C compiler, e.g. GCC or Clang
  46 * A Fortran compiler (optional, for LAPACK)
  47 * IBM MASS (optional, see below)
  48
  49 ### Normal compile
  50
  51 Simply invoking `make` (or `gmake` on BSD) will detect the CPU automatically.
  52 To set a specific target CPU, use `make TARGET=xxx`, e.g. `make TARGET=NEHALEM`.
  53 The full target list is in the file `TargetList.txt`. For building with `cmake`, the
  54 usual conventions apply, i.e. create a build directory either underneath the toplevel
  55 OpenBLAS source directory or separate from it, and invoke `cmake` there with the path
  56 to the source tree and any build options you plan to set.
  57
  58 ### Cross compile
  59
  60 Set `CC` and `FC` to point to the cross toolchains, and set `HOSTCC` to your host C compiler.
  61 The target must be specified explicitly when cross compiling.
  62
  63 Examples:
  64
  65 * On an x86 box, compile this library for a loongson3a CPU:
  66   ```sh
  67   make BINARY=64 CC=mips64el-unknown-linux-gnu-gcc FC=mips64el-unknown-linux-gnu-gfortran HOSTCC=gcc TARGET=LOONGSON3A
  68   ```
  69   or same with the newer mips-crosscompiler put out by Loongson that defaults to the 32bit ABI:
  70   ```sh
  71   make HOSTCC=gcc CC='/opt/mips-loongson-gcc7.3-linux-gnu/2019.06-29/bin/mips-linux-gnu-gcc -mabi=64' FC='/opt/mips-loongson-gcc7.3-linux-gnu/2019.06-29/bin/mips-linux-gnu-gfortran -mabi=64' TARGET=LOONGSON3A
  72   ```
  73
  74 * On an x86 box, compile this library for a loongson3a CPU with loongcc (based on Open64) compiler:
  75   ```sh
  76   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
  77   ```
  78
  79 ### Debug version
  80
  81 A debug version can be built using `make DEBUG=1`.
  82
  83 ### Compile with MASS support on Power CPU (optional)
  84
  85 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.
  86 OpenBLAS with MASS requires a 64-bit, little-endian OS on POWER.
  87 The library can be installed as shown:
  88
  89 * On Ubuntu:
  90   ```sh
  91   wget -q http://public.dhe.ibm.com/software/server/POWER/Linux/xl-compiler/eval/ppc64le/ubuntu/public.gpg -O- | sudo apt-key add -
  92   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
  93   sudo apt-get update
  94   sudo apt-get install libxlmass-devel.8.1.5
  95   ```
  96
  97 * On RHEL/CentOS:
  98   ```sh
  99   wget http://public.dhe.ibm.com/software/server/POWER/Linux/xl-compiler/eval/ppc64le/rhel7/repodata/repomd.xml.key
 100   sudo rpm --import repomd.xml.key
 101   wget http://public.dhe.ibm.com/software/server/POWER/Linux/xl-compiler/eval/ppc64le/rhel7/ibm-xl-compiler-eval.repo
 102   sudo cp ibm-xl-compiler-eval.repo /etc/yum.repos.d/
 103   sudo yum install libxlmass-devel.8.1.5
 104   ```
 105
 106 After installing the MASS library, compile OpenBLAS with `USE_MASS=1`.
 107 For example, to compile on Power8 with MASS support: `make USE_MASS=1 TARGET=POWER8`.
 108
 109 ### Install to a specific directory (optional)
 110
 111 Use `PREFIX=` when invoking `make`, for example
 112
 113 ```sh
 114 make install PREFIX=your_installation_directory
 115 ```
 116
 117 The default installation directory is `/opt/OpenBLAS`.
 118
 119 ## Supported CPUs and Operating Systems
 120
 121 Please read `GotoBLAS_01Readme.txt` for older CPU models already supported by the 2010 GotoBLAS.
 122
 123 ### Additional supported CPUs
 124
 125 #### x86/x86-64
 126
 127 - **Intel Xeon 56xx (Westmere)**: Used GotoBLAS2 Nehalem codes.
 128 - **Intel Sandy Bridge**: Optimized Level-3 and Level-2 BLAS with AVX on x86-64.
 129 - **Intel Haswell**: Optimized Level-3 and Level-2 BLAS with AVX2 and FMA on x86-64.
 130 - **Intel Skylake-X**: Optimized Level-3 and Level-2 BLAS with AVX512 and FMA on x86-64.
 131 - **Intel Cooper Lake**: as Skylake-X with improved BFLOAT16 support.
 132 - **AMD Bobcat**: Used GotoBLAS2 Barcelona codes.
 133 - **AMD Bulldozer**: x86-64 ?GEMM FMA4 kernels. (Thanks to Werner Saar)
 134 - **AMD PILEDRIVER**: Uses Bulldozer codes with some optimizations.
 135 - **AMD STEAMROLLER**: Uses Bulldozer codes with some optimizations.
 136 - **AMD ZEN**: Uses Haswell codes with some optimizations.
 137
 138 #### MIPS32
 139
 140 - **MIPS 1004K**: uses P5600 codes
 141 - **MIPS 24K**: uses P5600 codes
 142
 143 #### MIPS64
 144
 145 - **ICT Loongson 3A**: Optimized Level-3 BLAS and the part of Level-1,2.
 146 - **ICT Loongson 3B**: Experimental
 147
 148 #### ARM
 149
 150 - **ARMv6**: Optimized BLAS for vfpv2 and vfpv3-d16 (e.g. BCM2835, Cortex M0+)
 151 - **ARMv7**: Optimized BLAS for vfpv3-d32 (e.g. Cortex A8, A9 and A15)
 152
 153 #### ARM64
 154
 155 - **ARMv8**: Basic ARMV8 with small caches, optimized Level-3 and Level-2 BLAS
 156 - **Cortex-A53**: same as ARMV8 (different cpu specifications)
 157 - **Cortex-A55**: same as ARMV8 (different cpu specifications)
 158 - **Cortex A57**: Optimized Level-3 and Level-2 functions
 159 - **Cortex A72**: same as A57 ( different cpu specifications)
 160 - **Cortex A73**: same as A57 (different cpu specifications)
 161 - **Falkor**: same as A57 (different cpu specifications)
 162 - **ThunderX**: Optimized some Level-1 functions
 163 - **ThunderX2T99**: Optimized Level-3 BLAS and parts of Levels 1 and 2
 164 - **ThunderX3T110**
 165 - **TSV110**: Optimized some Level-3 helper functions
 166 - **EMAG 8180**: preliminary support based on A57
 167 - **Neoverse N1**: (AWS Graviton2) preliminary support
 168 - **Apple Vortex**: preliminary support based on ARMV8
 169
 170 #### PPC/PPC64
 171
 172 - **POWER8**: Optimized BLAS, only for PPC64LE (Little Endian), only with `USE_OPENMP=1`
 173 - **POWER9**: Optimized Level-3 BLAS (real) and some Level-1,2. PPC64LE with OpenMP only.
 174 - **POWER10**:
 175
 176 #### IBM zEnterprise System
 177
 178 - **Z13**: Optimized Level-3 BLAS and Level-1,2
 179 - **Z14**: Optimized Level-3 BLAS and (single precision) Level-1,2
 180
 181 #### RISC-V
 182
 183 - **C910V**: Optimized Level-3 BLAS (real) and Level-1,2 by RISC-V Vector extension 0.7.1.
 184   ```sh
 185   make HOSTCC=gcc TARGET=C910V CC=riscv64-unknown-linux-gnu-gcc FC=riscv64-unknown-linux-gnu-gfortran
 186   ```
 187   (also known to work on C906)
 188
 189 ### Support for multiple targets in a single library
 190
 191 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.
 192
 193 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.
 194
 195 `DYNAMIC_ARCH` is also supported on **x86**, where it translates to Katmai, Coppermine, Northwood, Prescott, Banias,
 196 Core2, Penryn, Dunnington, Nehalem, Athlon, Opteron, Opteron_SSE3, Barcelona, Bobcat, Atom and Nano.
 197
 198 On **ARMV8**, it enables support for CortexA53, CortexA57, CortexA72, CortexA73, Falkor, ThunderX, ThunderX2T99, TSV110 as well as generic ARMV8 cpus.
 199
 200 For **POWER**, the list encompasses POWER6, POWER8 and POWER9, on **ZARCH** it comprises Z13 and Z14.
 201
 202 The `TARGET` option can be used in conjunction with `DYNAMIC_ARCH=1` to specify which cpu model should be assumed for all the
 203 common code in the library, usually you will want to set this to the oldest model you expect to encounter.
 204 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.
 205
 206 ### Supported OS
 207
 208 - **GNU/Linux**
 209 - **MinGW or Visual Studio (CMake)/Windows**: Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-use-OpenBLAS-in-Microsoft-Visual-Studio>.
 210 - **Darwin/macOS/OSX/iOS**: Experimental. Although GotoBLAS2 already supports Darwin, we are not OSX/iOS experts.
 211 - **FreeBSD**: Supported by the community. We don't actively test the library on this OS.
 212 - **OpenBSD**: Supported by the community. We don't actively test the library on this OS.
 213 - **NetBSD**: Supported by the community. We don't actively test the library on this OS.
 214 - **DragonFly BSD**: Supported by the community. We don't actively test the library on this OS.
 215 - **Android**: Supported by the community. Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-build-OpenBLAS-for-Android>.
 216 - **AIX**: Supported on PPC up to POWER8
 217 - **Haiku**: Supported by the community. We don't actively test the library on this OS.
 218 - **SunOS**: Supported by the community. We don't actively test the library on this OS.
 219 - **Cortex-M**: Supported by the community. Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-use-OpenBLAS-on-Cortex-M>.
 220
 221 ## Usage
 222
 223 Statically link with `libopenblas.a` or dynamically link with `-lopenblas` if OpenBLAS was
 224 compiled as a shared library.
 225
 226 ### Setting the number of threads using environment variables
 227
 228 Environment variables are used to specify a maximum number of threads.
 229 For example,
 230
 231 ```sh
 232 export OPENBLAS_NUM_THREADS=4
 233 export GOTO_NUM_THREADS=4
 234 export OMP_NUM_THREADS=4
 235 ```
 236
 237 The priorities are `OPENBLAS_NUM_THREADS` > `GOTO_NUM_THREADS` > `OMP_NUM_THREADS`.
 238
 239 If you compile this library with `USE_OPENMP=1`, you should set the `OMP_NUM_THREADS`
 240 environment variable; OpenBLAS ignores `OPENBLAS_NUM_THREADS` and `GOTO_NUM_THREADS` when
 241 compiled with `USE_OPENMP=1`.
 242
 243 ### Setting the number of threads at runtime
 244
 245 We provide the following functions to control the number of threads at runtime:
 246
 247 ```c
 248 void goto_set_num_threads(int num_threads);
 249 void openblas_set_num_threads(int num_threads);
 250 ```
 251 Note that these are only used once at library initialization, and are not available for
 252 fine-tuning thread numbers in individual BLAS calls.
 253 If you compile this library with `USE_OPENMP=1`, you should use the above functions too.
 254
 255 ## Reporting bugs
 256
 257 Please submit an issue in https://github.com/xianyi/OpenBLAS/issues.
 258
 259 ## Contact
 260
 261 * OpenBLAS users mailing list: https://groups.google.com/forum/#!forum/openblas-users
 262 * OpenBLAS developers mailing list: https://groups.google.com/forum/#!forum/openblas-dev
 263
 264 ## Change log
 265
 266 Please see Changelog.txt to view the differences between OpenBLAS and GotoBLAS2 1.13 BSD version.
 267
 268 ## Troubleshooting
 269
 270 * Please read the [FAQ](https://github.com/xianyi/OpenBLAS/wiki/Faq) first.
 271 * Please use GCC version 4.6 and above to compile Sandy Bridge AVX kernels on Linux/MinGW/BSD.
 272 * Please use Clang version 3.1 and above to compile the library on Sandy Bridge microarchitecture.
 273   Clang 3.0 will generate the wrong AVX binary code.
 274 * Please use GCC version 6 or LLVM version 6 and above to compile Skylake AVX512 kernels.
 275 * The number of CPUs/cores should be less than or equal to 256. On Linux `x86_64` (`amd64`),
 276   there is experimental support for up to 1024 CPUs/cores and 128 numa nodes if you build
 277   the library with `BIGNUMA=1`.
 278 * OpenBLAS does not set processor affinity by default.
 279   On Linux, you can enable processor affinity by commenting out the line `NO_AFFINITY=1` in
 280   Makefile.rule. However, note that this may cause
 281   [a conflict with R parallel](https://stat.ethz.ch/pipermail/r-sig-hpc/2012-April/001348.html).
 282 * On Loongson 3A, `make test` may fail with a `pthread_create` error (`EAGAIN`).
 283   However, it will be okay when you run the same test case on the shell.
 284
 285 ## Contributing
 286
 287 1. [Check for open issues](https://github.com/xianyi/OpenBLAS/issues) or open a fresh issue
 288    to start a discussion around a feature idea or a bug.
 289 2. Fork the [OpenBLAS](https://github.com/xianyi/OpenBLAS) repository to start making your changes.
 290 3. Write a test which shows that the bug was fixed or that the feature works as expected.
 291 4. Send a pull request. Make sure to add yourself to `CONTRIBUTORS.md`.
 292
 293 ## Donation
 294
 295 Please read [this wiki page](https://github.com/xianyi/OpenBLAS/wiki/Donation).