README.md

   1 # NNtrainer
   2
   3 [![Code Coverage](http://nnsuite.mooo.com/nntrainer/ci/badge/codecoverage.svg)](http://nnsuite.mooo.com/nntrainer/ci/gcov_html/index.html)
   4 ![GitHub repo size](https://img.shields.io/github/repo-size/nnstreamer/nntrainer)
   5 ![GitHub issues](https://img.shields.io/github/issues/nnstreamer/nntrainer)
   6 ![GitHub pull requests](https://img.shields.io/github/issues-pr/nnstreamer/nntrainer)
   7
   8 NNtrainer is Software Framework for Training Neural Network Models on Devices.
   9
  10 ## Overview
  11
  12 NNtrainer is an Open Source Project. The aim of the NNtrainer is to develop Software Framework to train neural network model on embedded devices which has relatively limited resources. Rather than training the whole layers, NNtrainer trains only one or a few layers added after the feature extractor.
  13
  14 Even though it trains part of the neural network models, NNtrainer requires quite a lot of functionalities to train from common neural network frameworks. By implementing them, it is good enough to run several examples which can help to understand how it works. There are k-NN, Neural Network, Logistic Regression and Reinforcement Learning with CartPole in Applications directory and some of them use Mobilenet V2 with tensorflow-lite as a feature extractor. All of them tested on Galaxy S8 with Android and PC (Ubuntu 16.04).
  15
  16 ## Maintainer
  17 * [Jijoong Moon](https://github.com/jijoongmoon)
  18 * [MyungJoo Ham](https://github.com/myungjoo)
  19 * [Geunsik Lim](https://github.com/leemgs)
  20
  21 ## Reviewers
  22 * [Sangjung Woo](https://github.com/again4you)
  23 * [Wook Song](https://github.com/wooksong)
  24 * [Jaeyun Jung](https://github.com/jaeyun-jung)
  25 * [Hyoungjoo Ahn](https://github.com/helloahn)
  26 * [Parichay Kapoor](https://github.com/kparichay)
  27 * [Dongju Chae](https://github.com/dongju-chae)
  28 * [Gichan Jang](https://github.com/gichan-jang)
  29 * [Yongjoo Ahn](https://github.com/anyj0527)
  30 * [Jihoon Lee](https://github.com/zhoonit)
  31
  32 ## Components
  33
  34 ### Supported Layers
  35
  36 This component defines Layers which consist of Neural Network Model. Layers has own properties to be set.
  37
  38  | Keyword | Layer Name | Description |
  39  |:-------:|:---:|:---|
  40  |  conv2d | Convolution 2D |Convolution 2-Dimentional Layer |
  41  |  pooling2d | Pooling 2D |Pooling 2-Dimentional Layer. Support average / max / global average / global max pooing |
  42  | flatten | Flatten | Flatten Layer |
  43  | fully_connected | Fully Connected | Fully Connected Layer |
  44  | input | Input | Input Layer.  This is not always requied. |
  45  | batch_normalization | Batch Normalization Layer | Batch Normalization Layer. |
  46  | loss layer | loss layer | hidden from users |
  47  | activation | activaiton layer | set by layer property |
  48
  49 ### Supported Optimizers
  50
  51 NNTrainer Provides
  52
  53  | Keyward | Optimizer Name | Description |
  54  |:-------:|:---:|:---:|
  55  | sgd | Stochastic Gradient Decent | - |
  56  | adam | Adaptive Moment Estimation | - |
  57
  58 ### Supported Loss
  59
  60 NNTrainer provides
  61
  62  | Keyward | Loss Name | Description |
  63  |:-------:|:---:|:---:|
  64  | mse | Mean squared Error | - |
  65  | cross | Cross Entropy - sigmoid | if activation last layer is sigmoid |
  66  | cross | Cross Entropy - softmax | if activation last layer is softmax |
  67
  68 ### Supported Activations
  69
  70 NNTrainer provides
  71
  72  | Keyward | Loss Name | Description |
  73  |:-------:|:---:|:---|
  74  | tanh | tanh function | set as layer property |
  75  | sigmoid | sigmoid function | set as layer property |
  76  | relu | relu function | set as layer propery |
  77  | softmax | softmax function | set as layer propery |
  78  | weight_initializer | Weight Initialization | Xavier(Normal/Uniform), LeCun(Normal/Uniform),  HE(Normal/Unifor) |
  79  | weight_decay | weight decay ( L2Norm only ) | needs set weight_decay_param & type |
  80  | learnig_rate_decay | learning rate decay | need to set step |
  81
  82 ### Tensor
  83
  84 Tensor is responsible for the calculation of Layer. It executes the addition, division, multiplication, dot production, averaging of Data and so on. In order to accelerate the calculation speed, CBLAS (C-Basic Linear Algebra: CPU) and CUBLAS (CUDA: Basic Linear Algebra) for PC (Especially NVIDIA GPU)  for some of the operation. Later, these calculations will be optimized.
  85 Currently we supports lazy calculation mode to reduce copy of tensors during calcuation.
  86
  87  | Keyward | Description |
  88  |:-------:|:---:|
  89  | 4D Tensor | B, C, H, W|
  90  | Add/sub/mul/div | - |
  91  | sum, average, argmax | - |
  92  | Dot, Transpose | - |
  93  | normalization, standardization | - |
  94  | save, read | - |
  95
  96 ### Others
  97
  98 NNTrainer provides
  99
 100  | Keyward | Loss Name | Description |
 101  |:-------:|:---:|:---|
 102  | weight_initializer | Weight Initialization | Xavier(Normal/Uniform), LeCun(Normal/Uniform),  HE(Normal/Unifor) |
 103  | weight_decay | weight decay ( L2Norm only ) | needs set weight_decay_param & type |
 104  | learnig_rate_decay | learning rate decay | need to set step |
 105
 106 ### APIs
 107 Currently we privde [C APIs](https://github.com/nnstreamer/nntrainer/blob/master/api/capi/include/nntrainer.h) for Tizen. C++ API also provides soon.
 108
 109
 110 ### Examples for NNTrainer
 111
 112 #### [Custom Shortcut Application](https://github.com/nnstreamer/nntrainer/tree/master/Applications/Tizen_native/CustomShortcut)
 113
 114
 115 This is demo application which enable user defined custom shortcut on galaxy watch.
 116
 117 #### [MNIST Example](https://github.com/nnstreamer/nntrainer/tree/master/Applications/mnist)
 118
 119 This is example to train mnist dataset. It consists two convolution 2d layer, 2 pooling 2d layer, flatten layer and fully connected layer.
 120
 121 #### [Reinforcement Learning Example](https://github.com/nnstreamer/nntrainer/tree/master/Applications/ReinforcementLearning/DeepQ)
 122
 123 This is reinforcement learning example with cartpole game. It is using deepq alogrightm.
 124
 125 #### [Classification for cifar 10]( https://github.com/nnstreamer/nntrainer/tree/master/Applications/Classification )
 126
 127 This is Transfer learning example with cifar 10 data set. TFlite is used for feature extractor and modify last layer (fully connected layer) of network.
 128
 129 #### [Tizen CAPI Example](https://github.com/nnstreamer/nntrainer/tree/master/Applications/Tizen_CAPI)
 130
 131 This is for demonstrate c api for tizen. It is same transfer learing but written with tizen c api.
 132
 133 #### [KNN Example](https://github.com/nnstreamer/nntrainer/tree/master/Applications/KNN)
 134
 135 This is Transfer learning example with cifar 10 data set. TFlite is used for feature extractor and compared with KNN
 136
 137 #### [Logistic Regression Example](https://github.com/nnstreamer/nntrainer/tree/master/Applications/LogisticRegression)
 138
 139 This is simple logistic regression example using nntrainer.
 140
 141 ## Getting Started
 142
 143 ### Prerequisites
 144
 145 The following dependencies are needed to compile / build / run.
 146
 147 *   gcc/g++ (>= 4.9, std=c++14 is used)
 148 *   meson (>= 0.50.0)
 149 *   blas library (CBLAS) (for CPU Acceleration, libopenblas is used for now)
 150 *   cuda, cudart, cublas (should match the version) (GPU Acceleration on PC)
 151 *   tensorflow-lite (>= 1.4.0)
 152 *   libjsoncpp ( >= 0.6.0) (openAI Environment on PC)
 153 *   libcurl3 (>= 7.47) (openAI Environment on PC)
 154 *   libiniparser
 155 *   libgtest (for testing)
 156
 157
 158 ### Give It a Go Build with Docker
 159
 160 You can use [docker image](https://hub.docker.com/r/lunapocket/nntrainer-build-env) to easily set up and try building.
 161
 162 To run the docker
 163
 164 ```bash
 165 $ docker pull lunapocket/nntrainer-build-env:ubuntu-18.04
 166 $ docker run --rm -it  lunapocket/nntrainer-build-env:ubuntu-18.04
 167 ```
 168
 169 Inside docker...
 170
 171 ```bash
 172 $ cd /root/nntrainer
 173 $ git pull # If you want to build with latest sources.
 174 ```
 175
 176 You can try build from now on without concerning about Prerequisites.
 177
 178 ### How to Build
 179
 180 Download the source file by cloning the github repository.
 181
 182 ```bash
 183 $ git clone https://github.com/nnstreamer/nntrainer
 184 ```
 185
 186 After completing download the sources, you can find the several directories and files as below.
 187
 188 ``` bash
 189 $ cd nntrainer
 190
 191 $ ls -1
 192 api
 193 Applications
 194 debian
 195 doc
 196 jni
 197 LICENSE
 198 meson.build
 199 meson_options.txt
 200 nntrainer
 201 nntrainer.pc.in
 202 packaging
 203 README.md
 204 test
 205
 206 $ git log --oneline
 207 f1a3a05 (HEAD -> master, origin/master, origin/HEAD) Add more badges
 208 37032a1 Add Unit Test Cases for Neural Network Initialization
 209 181a003 lower case for layer type.
 210 1eb399b Update clang-format
 211 87f1de7 Add Unit Test for Neural Network
 212 cd5c36e Add Coverage Test badge for nntrainer
 213 ...
 214 ```
 215
 216 You can find the source code of the core library in nntrainer/src. In order to build them, use [meson](https://mesonbuild.com/)
 217 ```bash
 218 $ meson build
 219 The Meson build system
 220 Version: 0.50.1
 221 Source dir: /home/wook/Work/NNS/nntrainer
 222 Build dir: /home/wook/Work/NNS/nntrainer/build
 223 Build type: native build
 224 Project name: nntrainer
 225 Project version: 0.0.1
 226 Native C compiler: cc (gcc 7.5.0 "cc (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0")
 227 Native C++ compiler: c++ (gcc 7.5.0 "c++ (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0")
 228 Build machine cpu family: x86_64
 229 Build machine cpu: x86_64
 230 ...
 231 Build targets in project: 11
 232 Found ninja-1.8.2 at /usr/bin/ninja
 233
 234 $ ninja -C build
 235 ninja: Entering directory `build'
 236 [41/41] Linking target test/unittest/unittest_nntrainer_internal.
 237 ```
 238
 239 After completion of the build, the shared library, 'libnntrainer.so' and the static library, 'libnntrainer.a' will be placed in build/nntrainer.
 240 ```bash
 241 $ ls build/nntrainer -1
 242 d48ed23@@nntrainer@sha
 243 d48ed23@@nntrainer@sta
 244 libnntrainer.a
 245 libnntrainer.so
 246 ```
 247
 248 In order to install them with related header files to your system, use the 'install' sub-command.
 249 ```bash
 250 $ ninja -C build install
 251 ```
 252 Then, you will find the libnntrainer.so and related .h files in /usr/local/lib and /usr/local/include directories.
 253
 254 By default, the command ```ninja -C build`` generates the five example application binaries (Classification, k-NN, LogisticRegression, ReinforcementLearning, and Training) you could try in build/Applications. For 'Training' as an example case,
 255 ```bash
 256 $ ls build/Applications/Training/jni/ -1
 257 e189c96@@nntrainer_training@exe
 258 nntrainer_training
 259 ```
 260
 261 In order to run such example binaries, Tensorflow-lite is a prerequisite. If you are trying to run on the Android, it will automatically download tensorflow (1.9.0) and compile as static library. Otherwise, you need to install it by yourself.
 262
 263 ### Running Examples
 264
 265
 266 1. [Training](https://github.com/nnstreamer/nntrainer/blob/master/Applications/Training/README.md)
 267
 268 After build, run with following arguments
 269 Make sure to put last '/' for the resources directory.
 270 ```bash
 271 $./path/to/example ./path/to/settings.ini ./path/to/resource/directory/
 272 ```
 273
 274 To run the 'Training', for example, do as follows.
 275
 276 ```bash
 277 $ pwd
 278 ./nntrainer
 279 $ LD_LIBRARY_PATH=./build/nntrainer ./build/Applications/Training/jni/nntrainer_training ./Applications/Training/res/Training.ini ./Applications/Training/res/
 280 ../../res/happy/happy1.bmp
 281 ../../res/happy/happy2.bmp
 282 ../../res/happy/happy3.bmp
 283 ../../res/happy/happy4.bmp
 284 ../../res/happy/happy5.bmp
 285 ../../res/sad/sad1.bmp
 286 ../../res/sad/sad2.bmp
 287
 288 ...
 289
 290 ```
 291
 292 ## Open Source License
 293
 294 The nntrainer is an open source project released under the terms of the Apache License version 2.0.