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