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.png?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 ## Introduction
   9 OpenBLAS is an optimized BLAS library based on GotoBLAS2 1.13 BSD version.
  10
  11 Please read the documents on OpenBLAS wiki pages <http://github.com/xianyi/OpenBLAS/wiki>.
  12
  13 ## Binary Packages
  14 We provide binary packages for the following platform.
  15
  16   * Windows x86/x86_64
  17
  18 You can download them from [file hosting on sourceforge.net](https://sourceforge.net/projects/openblas/files/).
  19
  20 ## Installation from Source
  21 Download from project homepage. http://xianyi.github.com/OpenBLAS/
  22
  23 Or, check out codes from git://github.com/xianyi/OpenBLAS.git
  24 ### Normal compile
  25   * type "make" to detect the CPU automatically.
  26   or
  27   * type "make TARGET=xxx" to set target CPU, e.g. "make TARGET=NEHALEM". The full target list is in file TargetList.txt.
  28
  29 ### Cross compile
  30 Please set CC and FC with the cross toolchains. Then, set HOSTCC with your host C compiler. At last, set TARGET explicitly.
  31
  32 Examples:
  33
  34 On X86 box, compile this library for loongson3a CPU.
  35
  36     make BINARY=64 CC=mips64el-unknown-linux-gnu-gcc FC=mips64el-unknown-linux-gnu-gfortran HOSTCC=gcc TARGET=LOONGSON3A
  37
  38 On X86 box, compile this library for loongson3a CPU with loongcc (based on Open64) compiler.
  39
  40     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
  41
  42 ### Debug version
  43
  44     make DEBUG=1
  45
  46 ### Install to the directory (optional)
  47
  48 Example:
  49
  50     make install PREFIX=your_installation_directory
  51
  52 The default directory is /opt/OpenBLAS
  53
  54 ## Support CPU & OS
  55 Please read GotoBLAS_01Readme.txt
  56
  57 ### Additional support CPU:
  58
  59 #### x86/x86-64:
  60 - **Intel Xeon 56xx (Westmere)**: Used GotoBLAS2 Nehalem codes.
  61 - **Intel Sandy Bridge**: Optimized Level-3 and Level-2 BLAS with AVX on x86-64.
  62 - **Intel Haswell**: Optimized Level-3 and Level-2 BLAS with AVX2 and FMA  on x86-64.
  63 - **AMD Bobcat**: Used GotoBLAS2 Barcelona codes.
  64 - **AMD Bulldozer**: x86-64 ?GEMM FMA4 kernels. (Thank Werner Saar)
  65 - **AMD PILEDRIVER**: Uses Bulldozer codes with some optimizations.
  66 - **AMD STEAMROLLER**: Uses Bulldozer codes with some optimizations.
  67
  68 #### MIPS64:
  69 - **ICT Loongson 3A**: Optimized Level-3 BLAS and the part of Level-1,2.
  70 - **ICT Loongson 3B**: Experimental
  71
  72 #### ARM:
  73 - **ARMV6**: Optimized BLAS for vfpv2 and vfpv3-d16 ( e.g. BCM2835, Cortex M0+ )
  74 - **ARMV7**: Optimized BLAS for vfpv3-d32 ( e.g. Cortex A8, A9 and A15 )
  75
  76 #### ARM64:
  77 - **ARMV8**: Experimental
  78 - **ARM Cortex-A57**: Experimental
  79
  80 ### Support OS:
  81 - **GNU/Linux**
  82 - **MingWin or Visual Studio(CMake)/Windows**: Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-use-OpenBLAS-in-Microsoft-Visual-Studio>.
  83 - **Darwin/Mac OS X**: Experimental. Although GotoBLAS2 supports Darwin, we are the beginner on Mac OS X.
  84 - **FreeBSD**: Supported by community. We didn't test the library on this OS.
  85
  86 ## Usages
  87 Link with libopenblas.a or -lopenblas for shared library.
  88
  89 ### Set the number of threads with environment variables.
  90
  91 Examples:
  92
  93     export OPENBLAS_NUM_THREADS=4
  94
  95  or
  96
  97     export GOTO_NUM_THREADS=4
  98
  99  or
 100
 101     export OMP_NUM_THREADS=4
 102
 103 The priorities are OPENBLAS_NUM_THREADS > GOTO_NUM_THREADS > OMP_NUM_THREADS.
 104
 105 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.
 106
 107 ### Set the number of threads on runtime.
 108
 109 We provided the below functions to control the number of threads on runtime.
 110
 111     void goto_set_num_threads(int num_threads);
 112
 113     void openblas_set_num_threads(int num_threads);
 114
 115 If you compile this lib with USE_OPENMP=1, you should use the above functions, too.
 116
 117 ## Report Bugs
 118 Please add a issue in https://github.com/xianyi/OpenBLAS/issues
 119
 120 ## Contact
 121 * OpenBLAS users mailing list: https://groups.google.com/forum/#!forum/openblas-users
 122 * OpenBLAS developers mailing list: https://groups.google.com/forum/#!forum/openblas-dev
 123
 124 ## ChangeLog
 125 Please see Changelog.txt to obtain the differences between GotoBLAS2 1.13 BSD version.
 126
 127 ## Troubleshooting
 128 * Please read [Faq](https://github.com/xianyi/OpenBLAS/wiki/Faq) at first.
 129 * Please use gcc version 4.6 and above to compile Sandy Bridge AVX kernels on Linux/MingW/BSD.
 130 * 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.
 131 * 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.
 132 * 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).
 133 * 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.
 134
 135 ## Contributing
 136 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.
 137 1. Fork the [OpenBLAS](https://github.com/xianyi/OpenBLAS) repository to start making your changes.
 138 1. Write a test which shows that the bug was fixed or that the feature works as expected.
 139 1. Send a pull request. Make sure to add yourself to `CONTRIBUTORS.md`.
 140
 141 ## Donation
 142 Please read [this wiki page](https://github.com/xianyi/OpenBLAS/wiki/Donation).