inference-engine/thirdparty/mkl-dnn/README.md

   1 # Intel(R) Math Kernel Library for Deep Neural Networks (Intel(R) MKL-DNN)
   2 ![v0.18 beta](https://img.shields.io/badge/v0.18-beta-orange.svg)
   3
   4 Intel(R) Math Kernel Library for Deep Neural Networks (Intel(R) MKL-DNN) is
   5 an open-source performance library for deep-learning applications. The library
   6 accelerates deep-learning applications and frameworks on Intel architecture.
   7 Intel MKL-DNN contains vectorized and threaded building blocks that you can
   8 use to implement deep neural networks (DNN) with C and C++ interfaces.
   9
  10 DNN functionality optimized for Intel architecture is also included in
  11 [Intel Math Kernel Library (Intel MKL)](https://software.intel.com/en-us/mkl/features/deep-neural-networks).
  12 The API in that implementation is not compatible with Intel MKL-DNN and does not
  13 include certain new and experimental features.
  14
  15 This release contains performance-critical functions that improve performance of
  16 the following deep learning topologies and variations of these:
  17
  18 | Application                               | Example topology
  19 |:---                                       |:---
  20 | Image recognition                         | AlexNet, VGG, GoogleNet, ResNet, MobileNet
  21 | Image segmentation                        | FCN, SegNet, MaskRCNN, U-Net
  22 | Volumetric segmentation                   | 3D-Unet
  23 | Object detection                          | SSD, Faster R-CNN, Yolo
  24 | Neural machine translation                | GNMT
  25 | Speech recognition                        | DeepSpeech
  26 | Adversarial networks                      | DCGAN, 3DGAN
  27 | Reinforcement learning                    | A3C
  28 | Text-to-speech                            | WaveNet
  29
  30 Intel MKL-DNN is used in the following software products:
  31 * [Caffe\* Optimized for Intel Architecture](https://github.com/intel/caffe)
  32 * [Chainer\*](https://chainer.org)
  33 * [DeepBench](https://github.com/baidu-research/DeepBench)
  34 * [PaddlePaddle\*](http://www.paddlepaddle.org)
  35 * [PyTorch\*](https://pytorch.org/)
  36 * [Tensorflow\*](https://www.tensorflow.org)
  37 * [Microsoft\* Cognitive Toolkit (CNTK)](https://docs.microsoft.com/en-us/cognitive-toolkit)
  38 * [Apache\* MXNet](https://mxnet.apache.org)
  39 * [OpenVINO(TM) toolkit](https://01.org/openvinotoolkit)
  40 * [Intel Nervana Graph](https://github.com/NervanaSystems/ngraph)
  41 * [Menoh\*](https://github.com/pfnet-research/menoh)
  42 * [DeepLearning4J\*](https://deeplearning4j.org)
  43 * [BigDL](https://github.com/intel-analytics/BigDL)
  44
  45 ## License
  46 Intel MKL-DNN is licensed under
  47 [Apache License Version 2.0](http://www.apache.org/licenses/LICENSE-2.0). This
  48 software includes the following third-party components:
  49 * [Xbyak](https://github.com/herumi/xbyak) distributed under [3-clause BSD licence](src/cpu/xbyak/COPYRIGHT)
  50 * [gtest](https://github.com/google/googletest) distributed under [3-clause BSD license](tests/gtests/gtest/LICENSE)
  51
  52 ## Documentation
  53 * [Introduction](https://intel.github.io/mkl-dnn) explains the programming model
  54 and basic concepts
  55 * [Reference manual](https://intel.github.io/mkl-dnn/modules.html) provides
  56 detailed functionality description
  57 * [Examples](https://github.com/intel/mkl-dnn/tree/master/examples)
  58 demonstrates use of C and C++ APIs in simple topologies
  59 * [Tutorial](https://software.intel.com/en-us/articles/intel-mkl-dnn-part-1-library-overview-and-installation)
  60 provides step-by-step installation instructions and an example walkthrough
  61
  62 ## Support
  63 Please submit your questions, feature requests, and bug reports on the
  64 [GitHub issues](https://github.com/intel/mkl-dnn/issues) page.
  65
  66 **WARNING** The following functionality has preview status and might change
  67 without prior notification in future releases:
  68 * Convolutions with `s16` data type in source, weights or destination
  69 * Threading Building Blocks (TBB) support
  70
  71 ## How to Contribute
  72 We welcome community contributions to Intel MKL-DNN. If you have an idea on how to improve the library:
  73
  74 * Share your proposal via
  75  [GitHub issues](https://github.com/intel/mkl-dnn/issues).
  76 * Ensure you can build the product and run all the examples with your patch.
  77 * In the case of a larger feature, create a test.
  78 * Submit a [pull request](https://github.com/intel/mkl-dnn/pulls).
  79
  80 We will review your contribution and, if any additional fixes or modifications
  81 are necessary, may provide feedback to guide you. When accepted, your pull
  82 request will be merged to the repository.
  83
  84 ## System Requirements
  85 Intel MKL-DNN supports Intel 64 architecture and compatible architectures.
  86 The library is optimized for the systems based on
  87 * Intel Atom(R) processor with Intel SSE4.1 support
  88 * 4th, 5th, 6th, 7th, and 8th generation Intel(R) Core(TM) processor
  89 * Intel(R) Xeon(R) processor E5 v3 family (formerly Haswell)
  90 * Intel Xeon processor E5 v4 family (formerly Broadwell)
  91 * Intel Xeon Platinum processor family (formerly Skylake)
  92 * Intel(R) Xeon Phi(TM) processor x200 product family (formerly Knights Landing)
  93 * Intel Xeon Phi processor x205 product family (formerly Knights Mill)
  94
  95 and compatible processors.
  96
  97 The software dependencies are:
  98 * [Cmake](https://cmake.org/download/) 2.8.0 or later
  99 * [Doxygen](http://www.stack.nl/~dimitri/doxygen/download.html#srcbin) 1.8.5 or later
 100 * C++ compiler with C++11 standard support
 101 * Optional dependencies:
 102   * GNU\* OpenMP\*, LLVM OpenMP, or Intel OpenMP
 103   * Threading Building Blocks (TBB) 2017 or later
 104   * Intel MKL 2017 Update 1 or Intel MKL small libraries
 105
 106 > **Note**
 107 > Building Intel MKL-DNN with optional dependencies may introduce additional
 108 > runtime dependencies for the library. For details, refer to the corresponding
 109 > software system requirements.
 110
 111 The software was validated on RedHat\* Enterprise Linux 7 with
 112 * GNU Compiler Collection 4.8, 5.4, 6.1, 7.2, and 8.1
 113 * Clang\* 3.8.0
 114 * [Intel C/C++ Compiler](https://software.intel.com/en-us/intel-parallel-studio-xe)
 115   17.0, 18.0, and 19.0
 116
 117 on Windows Server\* 2012 R2 with
 118 * Microsoft Visual C++ 14.0 (Visual Studio 2015 Update 3)
 119 * [Intel C/C++ Compiler](https://software.intel.com/en-us/intel-parallel-studio-xe)
 120   17.0 and 19.0
 121
 122 on macOS\* 10.13 (High Sierra) with
 123 * Apple LLVM version 9.2 (XCode 9.2)
 124 * [Intel C/C++ Compiler](https://software.intel.com/en-us/intel-parallel-studio-xe)
 125   18.0 and 19.0
 126
 127 The implementation uses OpenMP 4.0 SIMD extensions. We recommend using the
 128 Intel C++ Compiler for the best performance results.
 129
 130 ## Installation
 131
 132 ### Build from source
 133
 134 #### Download source code
 135 Download [Intel MKL-DNN source code](https://github.com/intel/mkl-dnn/archive/master.zip)
 136 or clone [the repository](https://github.com/intel/mkl-dnn.git) to your system.
 137
 138 ```
 139 git clone https://github.com/intel/mkl-dnn.git
 140 ```
 141
 142 #### Configure build
 143 Intel MKL-DNN uses a CMake-based build system. You can use CMake options to control the build.
 144 Along with the standard CMake options such as `CMAKE_INSTALL_PREFIX` and `CMAKE_BUILD_TYPE`,
 145 you can pass Intel MKL-DNN specific options:
 146
 147 |Option                 | Possible Values (defaults in bold)   | Description
 148 |:---                   |:---                                  | :---
 149 |MKLDNN_LIBRARY_TYPE    | **SHARED**, STATIC                   | Defines the resulting library type
 150 |MKLDNN_THREADING       | **OMP**, OMP:INTEL, OMP:COMP, TBB    | Defines the threading type
 151 |WITH_EXAMPLE           | **ON**, OFF                          | Controls building the examples
 152 |WITH_TEST              | **ON**, OFF                          | Controls building the tests
 153 |ARCH_OPT_FLAGS         | *compiler flags*                     | Specifies compiler optimization flags (see warning note below)
 154 |VTUNEROOT              | *path*                               | Enables integration with Intel(R) VTune(TM) Amplifier
 155
 156 > **WARNING**
 157 >
 158 > By default, Intel MKL-DNN is built specifically for the processor type of the
 159 > compiling machine (for example, `-march=native` in the case of GCC). While this option
 160 > gives better performance, the resulting library can be run only on systems
 161 > that are instruction-set compatible with the compiling machine.
 162 >
 163 > Therefore, if Intel MKL-DNN is to be shipped to other platforms (for example, built by
 164 > Linux distribution maintainers), consider setting `ARCH_OPT_FLAGS` to `""`.
 165
 166 For more options and details, check [cmake/options.cmake](cmake/options.cmake).
 167
 168 ##### Using Intel MKL (optional)
 169 Intel MKL-DNN includes an optimized matrix-matrix multiplication (GEMM) implementation for modern platforms.
 170 The library can also take advantage of GEMM functions from Intel MKL to improve performance with older
 171 versions of compilers or on older platforms. This behavior is controlled by the `MKLDNN_USE_MKL` option.
 172
 173 |Option                 | Possible Values (defaults in bold)   | Description
 174 |:---                   |:---                                  | :---
 175 |MKLDNN_USE_MKL         | **DEF**, NONE, ML, FULL, FULL:STATIC | Defines the binary dependency on Intel MKL
 176
 177 The dynamic library with this functionality is included in the repository.
 178 If you choose to build Intel MKL-DNN with the binary dependency, download the Intel MKL small
 179 libraries using the provided script:
 180
 181 *Linux/macOS*
 182 ```
 183 cd scripts && ./prepare_mkl.sh && cd ..
 184 ```
 185
 186 *Windows\**
 187 ```
 188 cd scripts && call prepare_mkl.bat && cd ..
 189 ```
 190
 191 or manually from [GitHub release section](https://github.com/intel/mkl-dnn/releases),
 192 and unpack it to the `external` directory in the repository root. Intel MKL-DNN
 193 can also be built with full Intel MKL if the latter is installed on the system.
 194 You might need to set the `MKLROOT` environment variable to the path where the full
 195 Intel MKL is installed to help `cmake` locate the library.
 196
 197 > **Note**
 198 >
 199 > Using Intel MKL small libraries currently works only for Intel MKL-DNN built with
 200 > OpenMP. Building with Intel TBB requires either the full Intel MKL library
 201 > or a standalone build.
 202 >
 203 > Using Intel MKL or Intel MKL small libraries will introduce additional
 204 > runtime dependencies. For additional information, refer to Intel MKL
 205 > [system requirements](https://software.intel.com/en-us/articles/intel-math-kernel-library-intel-mkl-2019-system-requirements).
 206
 207 ##### Threading
 208 Intel MKL-DNN is parallelized and can use the OpenMP or TBB threading runtime. OpenMP threading is the default build mode
 209 and is recommended for the best performance. TBB support is experimental. This behavior is controlled by the `MKLDNN_THREADING` option.
 210
 211 |Option                 | Possible Values (defaults in bold)   | Description
 212 |:---                   |:---                                  | :---
 213 |MKLDNN_THREADING       | **OMP**, OMP:INTEL, OMP:COMP, TBB    | Defines the threading type
 214
 215 ##### OpenMP
 216 Intel MKL-DNN can use Intel, GNU or CLANG OpenMP runtime. Because different OpenMP runtimes may not be binary compatible,
 217 it's important to ensure that only one OpenMP runtime is used throughout the
 218 application. Having more than one OpenMP runtime initialized may lead to
 219 undefined behavior including incorrect results or crashes.
 220
 221 Intel MKL-DNN library built with the binary dependency will link against the Intel OpenMP
 222 runtime included with the Intel MKL small libraries package. The Intel OpenMP runtime
 223 is binary compatible with the GNU OpenMP and Clang OpenMP runtimes and is
 224 recommended for the best performance results.
 225
 226 Intel MKL-DNN library built standalone will use the OpenMP runtime supplied by
 227 the compiler, so as long as both the library and the application use the
 228 same compiler, the correct OpenMP runtime will be used.
 229
 230 ##### TBB
 231 TBB support is experimental. Intel MKL-DNN has limited optimizations done for Intel TBB and has some functional
 232 limitations if built with Intel TBB.
 233
 234 Functional limitations:
 235 * Convolution with Winograd algorithm is not supported
 236
 237 Performance limitations (mostly less parallelism than in case of OpenMP):
 238 * Batch normalization
 239 * Convolution backward by weights
 240 * mkldnn_sgemm
 241
 242 > **WARNING**
 243 >
 244 > If the library is built with the full Intel MKL, the user is expected to set
 245 > the `MKL_THREADING_LAYER` environment variable to either `tbb` or `sequential` in order
 246 > to force Intel MKL to use Intel TBB for parallelization or to be sequential,
 247 > respectively. Without this setting, Intel MKL (RT library) tries
 248 > to use OpenMP for parallelization by default.
 249
 250 #### Build on Linux/macOS
 251 Ensure that all software dependencies are in place and have at least the minimal
 252 supported version.
 253
 254 Configure CMake and create a makefile:
 255
 256 ```
 257 mkdir -p build && cd build && cmake $CMAKE_OPTIONS ..
 258 ```
 259
 260 Build the application:
 261
 262 ```
 263 make
 264 ```
 265
 266 The build can be validated with the unit-test suite:
 267
 268 ```
 269 ctest
 270 ```
 271
 272 The reference manual is provided inline and can also be generated in HTML format with Doxygen:
 273
 274 ```
 275 make doc
 276 ```
 277
 278 Documentation will reside in the `build/reference/html` folder.
 279
 280 Finally:
 281
 282 ```
 283 make install
 284 ```
 285
 286 will place the header files, libraries, and documentation in `/usr/local`. To change
 287 the installation path, use the option `-DCMAKE_INSTALL_PREFIX=<prefix>` when invoking CMake.
 288
 289 #### Build on Windows
 290 Ensure that all software dependencies are in place and have at least the minimal
 291 supported version.
 292
 293 > **NOTE**
 294 >
 295 > Building Intel MKL-DNN from a terminal requires using either the Intel Parallel Studio command prompt
 296 > or the Microsoft\* Visual Studio\* developer command prompt instead of the default Windows command prompt.
 297 >
 298 > The Intel(R) Parallel Studio command prompt is an item in the **Start** menu in the **Intel Parallel Studio
 299 > \<version\>** folder that has a Windows Command Prompt icon and a name like **Compiler 18.0 Update 5…**.
 300 >
 301 > The default for building the project for the Intel C++ Compiler is to use the Intel
 302 > Parallel Studio developer command prompt.
 303
 304 Configure CMake and create a Microsoft Visual Studio solution:
 305
 306 ```
 307 mkdir build & cd build && cmake -G "Visual Studio 15 2017 Win64" ..
 308 ```
 309
 310 For the solution to use Intel C++ Compiler:
 311
 312 ```
 313 cmake -G "Visual Studio 15 2017 Win64" -T "Intel C++ Compiler 18.0" ..
 314 ```
 315
 316 After you have built the initial project using CMake, you can then open the project with
 317 Microsoft Visual Studio and build from there. You can also use msbuild command-line tool
 318 to build from the command line:
 319
 320 ```
 321 msbuild "Intel(R) MKL-DNN.sln" /p:Configuration=Release [/t:rebuild] /m
 322 ```
 323 where the optional argument `/t:rebuild` rebuilds the project.
 324
 325 The build can be validated with the unit-test suite:
 326
 327 ```
 328 ctest
 329 ```
 330
 331 ## Linking Your Application
 332
 333 ### Linux/macOS
 334 Intel MKL-DNN includes several header files providing C and C++ APIs for
 335 the functionality and one or several dynamic libraries depending on how
 336 Intel MKL-DNN was built.
 337
 338 **Linux**
 339
 340 |File                   | Description
 341 |:---                   |:---
 342 |include/mkldnn.h       | C header
 343 |include/mkldnn.hpp     | C++ header
 344 |include/mkldnn_types.h | Auxiliary C header
 345 |lib/libmkldnn.so       | Intel MKL-DNN dynamic library
 346 |lib/libmkldnn.a        | Intel MKL-DNN static library (if built with `MKLDNN_LIBRARY_TYPE=STATIC`)
 347 |lib/libiomp5.so        | Intel OpenMP\* runtime library (if built with `MKLDNN_USE_MKL=ML`)
 348 |lib/libmklml_gnu.so    | Intel MKL small library for GNU OpenMP runtime (if built with `MKLDNN_USE_MKL=ML`)
 349 |lib/libmklml_intel.so  | Intel MKL small library for Intel OpenMP runtime (if built with `MKLDNN_USE_MKL=ML`)
 350
 351 **macOS**
 352
 353 |File                     | Description
 354 |:---                     |:---
 355 |include/mkldnn.h         | C header
 356 |include/mkldnn.hpp       | C++ header
 357 |include/mkldnn_types.h   | Auxiliary C header
 358 |lib/libmkldnn.dylib      | Intel MKL-DNN dynamic library
 359 |lib/libmkldnn.a          | Intel MKL-DNN static library (if built with `MKLDNN_LIBRARY_TYPE=STATIC`)
 360 |lib/libiomp5.dylib       | Intel OpenMP\* runtime library (if built with `MKLDNN_USE_MKL=ML`)
 361 |lib/libmklml_gnu.dylib   | Intel MKL small library for GNU OpenMP runtime (if built with `MKLDNN_USE_MKL=ML`)
 362 |lib/libmklml_intel.dylib | Intel MKL small library for Intel OpenMP runtime (if built with `MKLDNN_USE_MKL=ML`)
 363
 364 Linkline examples below assume that Intel MKL-DNN is installed in the directory
 365 defined in the MKLDNNROOT environment variable.
 366
 367 ```
 368 g++ -std=c++11 -I${MKLDNNROOT}/include -L${MKLDNNROOT}/lib simple_net.cpp -lmkldnn
 369 clang -std=c++11 -I${MKLDNNROOT}/include -L${MKLDNNROOT}/lib simple_net.cpp -lmkldnn
 370 icpc -std=c++11 -I${MKLDNNROOT}/include -L${MKLDNNROOT}/lib simple_net.cpp -lmkldnn
 371 ```
 372
 373 > **WARNING**
 374 >
 375 > Using the GNU compiler with the `-fopenmp` and `-liomp5` options will link the
 376 > application with both the Intel and GNU OpenMP runtime libraries. This will lead
 377 > to undefined behavior in the application.
 378
 379 > **NOTE**
 380 >
 381 > Applications linked dynamically will resolve the dependencies at runtime.
 382 > Make sure that the dependencies are available in the standard locations
 383 > defined by the operating system, in the locatons listed in `LD_LIBRARY_PATH` (Linux),
 384 > `DYLD_LIBRARY_PATH` (macOS) environment variables, or `rpath` mechanism.
 385
 386 ### Windows
 387 Intel MKL-DNN includes several header files providing C and C++ APIs for
 388 the functionality and one or several dynamic libraries depending on how
 389 Intel MKL-DNN was built.
 390
 391 |File                   | Description
 392 |:---                   |:---
 393 |bin\libmkldnn.dll      | Intel MKL-DNN dynamic library
 394 |bin\libiomp5.dll       | Intel OpenMP\* runtime library (if built with `MKLDNN_USE_MKL=ML`)
 395 |bin\libmklml.dll       | Intel MKL small library (if built with `MKLDNN_USE_MKL=ML`)
 396 |include\mkldnn.h       | C header
 397 |include\mkldnn.hpp     | C++ header
 398 |include\mkldnn_types.h | Auxiliary C header
 399 |lib\libmkldnn.lib      | Intel MKL-DNN import library
 400 |lib\libiomp5.lib       | Intel OpenMP\* runtime import library (if built with `MKLDNN_USE_MKL=ML`)
 401 |lib\libmklml.lib       | Intel MKL small library import library (if built with `MKLDNN_USE_MKL=ML`)
 402
 403 To link the application from the command line, set up the `LIB` and `INCLUDE` environment variables to point to the locations of
 404 the Intel MKL-DNN headers and libraries. The Linkline examples below assume that Intel MKL-DNN is installed in the directory
 405 defined in the MKLDNNROOT environment variable.
 406
 407 ```
 408 set INCLUDE=%MKLDNNROOT%\include;%INCLUDE%
 409 set LIB=%MKLDNNROOT%\lib;%LIB%
 410 icl /Qstd=c++11 /qopenmp simple_net.cpp mkldnn.lib
 411 cl simple_net.cpp mkldnn.lib
 412 ```
 413
 414 Refer to [Microsoft Visual Studio documentation](https://docs.microsoft.com/en-us/cpp/build/walkthrough-creating-and-using-a-dynamic-link-library-cpp?view=vs-2017)
 415 on linking the application using MSVS solutions.
 416
 417 > **NOTE**
 418 > Applications linked dynamically will resolve the dependencies at runtime.
 419 > Make sure that the dependencies are available in the standard locations
 420 > defined by the operating system or in the locatons listed in the `PATH` environment variable.
 421
 422 --------
 423
 424 [Legal Information](doc/legal_information.md)