README.md

   1 # OpenBLAS
   2
   3 ## Introduction
   4 OpenBLAS is an optimized BLAS library based on GotoBLAS2 1.13 BSD version. OpenBLAS is an open source project supported by Lab of Parallel Software and Computational Science, ISCAS <http://www.rdcps.ac.cn>.
   5
   6 Please read the documents on OpenBLAS wiki pages <http://github.com/xianyi/OpenBLAS/wiki>.
   7
   8 ## Installation
   9 Download from project homepage. http://xianyi.github.com/OpenBLAS/
  10
  11 Or, check out codes from git://github.com/xianyi/OpenBLAS.git
  12 ### Normal compile
  13   * type "make" to detect the CPU automatically.
  14   or
  15   * type "make TARGET=xxx" to set target CPU, e.g. "make TARGET=NEHALEM". The full target list is in file TargetList.txt.
  16
  17 ### Cross compile
  18 Please set CC and FC with the cross toolchains. Then, set HOSTCC with your host C compiler. At last, set TARGET explicitly.
  19
  20 Examples:
  21
  22 On X86 box, compile this library for loongson3a CPU.
  23
  24     make BINARY=64 CC=mips64el-unknown-linux-gnu-gcc FC=mips64el-unknown-linux-gnu-gfortran HOSTCC=gcc TARGET=LOONGSON3A
  25
  26 On X86 box, compile this library for loongson3a CPU with loongcc (based on Open64) compiler.
  27
  28     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
  29
  30 ### Debug version
  31
  32     make DEBUG=1
  33
  34 ### Install to the directory (Optional)
  35
  36 Example:
  37
  38     make install PREFIX=your_installation_directory
  39
  40 The default directory is /opt/OpenBLAS
  41
  42 ## Support CPU & OS
  43 Please read GotoBLAS_01Readme.txt
  44
  45 ### Additional support CPU:
  46
  47 #### x86/x86-64:
  48 - **Intel Xeon 56xx (Westmere)**: Used GotoBLAS2 Nehalem codes.
  49 - **Intel Sandy Bridge**: Optimized Level-3 BLAS with AVX on x86-64.
  50 - **AMD Bobcat**: Used GotoBLAS2 Barcelona codes.
  51 - **AMD Bulldozer**: x86-64 S/DGEMM AVX kernels. (Thank Werner Saar)
  52
  53 #### MIPS64:
  54 - **ICT Loongson 3A**: Optimized Level-3 BLAS and the part of Level-1,2.
  55 - **ICT Loongson 3B**: Experimental
  56
  57 ### Support OS:
  58 - **GNU/Linux**
  59 - **MingWin/Windows**: Please read <https://github.com/xianyi/OpenBLAS/wiki/How-to-use-OpenBLAS-in-Microsoft-Visual-Studio>.
  60 - **Darwin/Mac OS X**: Experimental. Although GotoBLAS2 supports Darwin, we are the beginner on Mac OS X.
  61 - **FreeBSD**: Supportted by community. We didn't test the library on this OS.
  62
  63 ## Usages
  64 Link with libopenblas.a or -lopenblas for shared library.
  65
  66 ### Set the number of threads with environment variables.
  67
  68 Examples:
  69
  70     export OPENBLAS_NUM_THREADS=4
  71
  72  or
  73
  74     export GOTO_NUM_THREADS=4
  75
  76  or
  77
  78     export OMP_NUM_THREADS=4
  79
  80 The priorities are OPENBLAS_NUM_THREADS > GOTO_NUM_THREADS > OMP_NUM_THREADS.
  81
  82 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.
  83
  84 ### Set the number of threads on runtime.
  85
  86 We provided the below functions to controll the number of threads on runtime.
  87
  88     void goto_set_num_threads(int num_threads);
  89
  90     void openblas_set_num_threads(int num_threads);
  91
  92 If you compile this lib with USE_OPENMP=1, you should use the above functions, too.
  93
  94 ## Report Bugs
  95 Please add a issue in https://github.com/xianyi/OpenBLAS/issues
  96
  97 ## Contact
  98 OpenBLAS users mailing list: http://list.rdcps.ac.cn/mailman/listinfo/openblas
  99
 100 ## ChangeLog
 101 Please see Changelog.txt to obtain the differences between GotoBLAS2 1.13 BSD version.
 102
 103 ## Troubleshooting
 104 * Please read [Faq](https://github.com/xianyi/OpenBLAS/wiki/Faq) at first.
 105 * Please use gcc version 4.6 and above to compile Sandy Bridge AVX kernels on Linux/MingW/BSD.
 106 * 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.
 107 * The number of CPUs/Cores should less than or equal to 256.
 108 * On Linux, OpenBLAS sets the processor affinity by default. This may cause [the conflict with R parallel](https://stat.ethz.ch/pipermail/r-sig-hpc/2012-April/001348.html). You can build the library with NO_AFFINITY=1.
 109 * 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.
 110
 111 ## Specification of Git Branches
 112 We used the git branching model in this article (http://nvie.com/posts/a-successful-git-branching-model/).
 113 Now, there are 4 branches in github.com.
 114   * The master branch. This a main branch to reflect a production-ready state.
 115   * The develop branch. This a main branch to reflect a state with the latest delivered development changes for the next release.
 116   * The loongson3a branch. This is a feature branch. We develop Loongson3A codes on this branch. We will merge this feature to develop branch in future.
 117   * The gh-pages branch. This is for web pages