README.MD

# Intel® MKL-DNN on PaddlePaddle: Design Doc

我们计划将Intel深度神经网络数学库(**MKL-DNN**\[[1](#references)\])集成到PaddlePaddle，充分展现英特尔平台的优势，有效提升PaddlePaddle在英特尔架构上的性能。

我们短期内的基本目标是：

- 完成常用layer的MKLDNN实现。
- 完成常见深度神经网络VGG，GoogLeNet 和 ResNet的MKLDNN实现。


## Contents

- [Overall](#overall)
- [Details](#details)
 	- [Cmake](#cmake)
	- [Layer](#layer)
	- [Activation](#activation)
	- [Unit Test](#unit-test)
	- [Proto](#proto)
	- [Python API](#python-api)
	- [Demo](#demo)
	- [Benchmark](#benchmark)
	- [Others](#others)
- [KeyPoints](#keypoints)

## Overall

我们会把MKLDNN作为第三方库集成进PaddlePaddle，整体框架图
<div align="center">
<img src="image/overview.png" width=350><br/>
Figure 1. PaddlePaddle on IA.
</div>

## Details
我们把集成方案大致分为了如下几个方面。

### Cmake
我们会在`CMakeLists.txt`中会添加`WITH_MKLDNN`的选项，当设置这个值为`ON`的时候会启用编译MKLDNN功能。同时会自动开启`OpenMP`用于提高MKLDNN的性能。

为了让PaddlePaddle更好的发挥MKLDNN的性能，我们还会引入`WITH_MKLML`的选项，用于选择是否用MKLDNN自带的MKLML的安装包。这个安装包可以独立于MKLDNN使用，但是建议在开启MKLDNN的同时也打开MKLML的开关，这样才能发挥最好的性能。

所以，我们会在`cmake\external`新建`MKLDNN.cmake`和`MKLML.cmake`文件，并作为第三方库安装到PaddlePaddle的third party目录中。

**备注**：当`WITH_MKLML=ON`的时候，会优先使用这个包作为PaddlePaddle的Cblas和Lapack库，所以会稍微改动`cmake\cblas.cmake`中的逻辑。

### Layer
所有的layer相关的C++代码，都会在按照PaddlePaddle的目录结构存放在
`paddle\gserver\layers`中，文件名以*Mkldnn*开头。
并且有可能会在Layer.h和Layer.cpp里面添加少量的code，用宏定义`PADDLE_USE_MKLDNN`隔开。

所有MKLDNN的Layer都会继承于一个MKLDNN的父类layer，这个父类mkldnnlayer继承于Paddle的基类layer。

### Activation
由于在PaddlePaddle中，激活函数是独立于layer概念的，所以会在`paddle\gserver\activations`目录下添加一个`MkldnnActivation.h`文件定义一些用于MKLDNN的接口，实现方法还是在`ActivationFunction.cpp`里面

### Unit Test
会在`paddle\gserver\test`目录下添加`test_Mkldnn.cpp`和`MkldnnTester.*`用于mkldnn的测试。

Activation的测试，计划在Paddle原有的测试文件上直接添加测试type。

### Proto
根据具体layer的需求可能会在`proto\ModelConfig.proto`里面添加必要的选项。

### Python API
目前只考虑**v1 API**。

计划在`python/paddle/trainer/config_parser.py`里面添加`use_mkldnn`这个选择，方便user选择使用mkldnn的layers。

具体实现方式比如：


	use_mkldnn = bool(int(g_command_config_args.get("use_mkldnn", 0)))
	if use_mkldnn
            self.layer_type = mkldnn_*

所有mkldnn的type会以"mkldnn_"开头，以示区分。 

并且可能在`python/paddle/trainer_config_helper`目录下的`activations.py `和`layers.py`里面添加必要的mkldnn的接口。

### Demo

会在`v1_api_demo`目录下添加一个`mkldnn`的文件夹，里面放入一些用于mkldnn测试的demo脚本。

### Benchmark
会考虑添加部分逻辑在`benchmark\paddle\image\run.sh`，添加使用mkldnn的测试。

### Others
1. 如果在使用MKLDNN的情况下，会把CPU的Buffer对齐为64。
2. 深入PaddlePaddle，寻找有没有其他可以优化的可能，进一步优化。比如可能会用`OpenMP`改进SGD的更新性能。

## KeyPoints

为了更好的符合PaddlePaddle的代码风格，同时又尽可能少的牺牲MKLDNN的性能。

我们总结出一些特别需要注意的点：

1. 使用**deviceId_**。为了尽可能少的在父类Layer中添加变量或者函数，我们决定使用已有的`deviceId_`变量来区分layer的属性，定义`-2`为**MkldnnLayer**特有的设备ID。
2. 重写父类Layer的**init**函数，修改`deviceId_`为`-2`，代表这个layer是用于跑在MKLDNN的环境下。
3. 创建**MkldnnMatrix**，用于管理MKLDNN会用到的相关memory函数和接口。
4. 创建**MkldnnBase**，定义一些除了layer和memory相关的类和函数。包括MKLDNN会用到Stream和CpuEngine，和未来可能还会用到FPGAEngine等。
5. 在**Argument**里添加两个MkldnnMatrixPtr，取名为mkldnnValue和mkldnnGrad，用于存放MkldnnLayer会用到的memory buffer。 并且添加函数cvt(会修改为一个更加合适的函数名)，用于处理"CPU device"和"MKLDNN device"之间memory的相互转化。
6. 在父类Layer中的**getOutput**函数中添加一段逻辑，用于判断`deviceId`，并针对device在MKLDNN和CPU之间不统一的情况，做一个前期转换。 也就是调用`Argument`的cvt函数把output统一到需要的device上。
7. 在原来的`FLAGS`中添加一个`use_mkldnn`的flag，用于选择是否使用MKLDNN的相关功能。

## References

1. [Intel Math Kernel Library for Deep Neural Networks (Intel MKL-DNN)](https://github.com/01org/mkl-dnn "Intel MKL-DNN")