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_regularizer | weight decay ( L2Norm only ) | needs set weight_regularizer_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_regularizer | weight decay ( L2Norm only ) | needs set weight_regularizer_constant & 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/TransferLearning/CIFAR_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~
 130
 131 ~This is for demonstrate c api for tizen. It is same transfer learing but written with tizen c api.~
 132 Deleted instead moved to a [test](https://github.com/nnstreamer/nntrainer/blob/master/test/tizen_capi/unittest_tizen_capi.cpp)
 133
 134 #### [KNN Example](https://github.com/nnstreamer/nntrainer/tree/master/Applications/KNN)
 135
 136 This is Transfer learning example with cifar 10 data set. TFlite is used for feature extractor and compared with KNN
 137
 138 #### [Logistic Regression Example](https://github.com/nnstreamer/nntrainer/tree/master/Applications/LogisticRegression)
 139
 140 This is simple logistic regression example using nntrainer.
 141
 142 ## Getting Started
 143
 144 ### Prerequisites
 145
 146 The following dependencies are needed to compile / build / run.
 147
 148 *   gcc/g++ (>= 4.9, std=c++14 is used)
 149 *   meson (>= 0.50.0)
 150 *   blas library (CBLAS) (for CPU Acceleration, libopenblas is used for now)
 151 *   cuda, cudart, cublas (should match the version) (GPU Acceleration on PC)
 152 *   tensorflow-lite (>= 1.4.0)
 153 *   libjsoncpp ( >= 0.6.0) (openAI Environment on PC)
 154 *   libcurl3 (>= 7.47) (openAI Environment on PC)
 155 *   libiniparser
 156 *   libgtest (for testing)
 157
 158 ### How to Build
 159
 160 Download the source file by cloning the github repository.
 161
 162 ```bash
 163 $ git clone https://github.com/nnstreamer/nntrainer
 164 ```
 165
 166 After completing download the sources, you can find the several directories and files as below.
 167
 168 ``` bash
 169 $ cd nntrainer
 170
 171 $ ls -1
 172 api
 173 Applications
 174 debian
 175 doc
 176 jni
 177 LICENSE
 178 meson.build
 179 meson_options.txt
 180 nntrainer
 181 nntrainer.pc.in
 182 packaging
 183 README.md
 184 test
 185
 186 $ git log --oneline
 187 f1a3a05 (HEAD -> master, origin/master, origin/HEAD) Add more badges
 188 37032a1 Add Unit Test Cases for Neural Network Initialization
 189 181a003 lower case for layer type.
 190 1eb399b Update clang-format
 191 87f1de7 Add Unit Test for Neural Network
 192 cd5c36e Add Coverage Test badge for nntrainer
 193 ...
 194 ```
 195
 196 You can find the source code of the core library in nntrainer/src. In order to build them, use [meson](https://mesonbuild.com/)
 197 ```bash
 198 $ meson build
 199 The Meson build system
 200 Version: 0.50.1
 201 Source dir: /home/wook/Work/NNS/nntrainer
 202 Build dir: /home/wook/Work/NNS/nntrainer/build
 203 Build type: native build
 204 Project name: nntrainer
 205 Project version: 0.0.1
 206 Native C compiler: cc (gcc 7.5.0 "cc (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0")
 207 Native C++ compiler: c++ (gcc 7.5.0 "c++ (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0")
 208 Build machine cpu family: x86_64
 209 Build machine cpu: x86_64
 210 ...
 211 Build targets in project: 11
 212 Found ninja-1.8.2 at /usr/bin/ninja
 213
 214 $ ninja -C build
 215 ninja: Entering directory `build'
 216 [41/41] Linking target test/unittest/unittest_nntrainer_internal.
 217 ```
 218
 219 After completion of the build, the shared library, 'libnntrainer.so' and the static library, 'libnntrainer.a' will be placed in build/nntrainer.
 220 ```bash
 221 $ ls build/nntrainer -1
 222 d48ed23@@nntrainer@sha
 223 d48ed23@@nntrainer@sta
 224 libnntrainer.a
 225 libnntrainer.so
 226 ```
 227
 228 In order to install them with related header files to your system, use the 'install' sub-command.
 229 ```bash
 230 $ ninja -C build install
 231 ```
 232 Then, you will find the libnntrainer.so and related .h files in /usr/local/lib and /usr/local/include directories.
 233
 234 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,
 235 ```bash
 236 $ ls build/Applications/Training/jni/ -1
 237 e189c96@@nntrainer_training@exe
 238 nntrainer_training
 239 ```
 240
 241 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.
 242
 243 ### How to Test
 244
 245 1. Unittest
 246 Meson build `enable-test` set to true
 247
 248 ```bash
 249 $ echo $(pwd)
 250 (project root)
 251
 252 $ meson build -Denable-test=true
 253 The Meson build system
 254 Version: 0.54.3
 255 ...
 256 Configuring capi-nntrainer.pc using configuration
 257 Run-time dependency GTest found: YES (building self)
 258 Build targets in project: 17
 259
 260 Found ninja-1.10.0.git.kitware.jobserver-1 at /home/jlee/.local/bin/ninja
 261
 262 $ ninja -C build test
 263 [79/79] Running all tests.
 264  1/12 unittest_tizen_capi            OK             8.86s
 265  2/12 unittest_tizen_capi_layer      OK             0.05s
 266  3/12 unittest_tizen_capi_optimizer  OK             0.01s
 267  4/12 unittest_tizen_capi_dataset    OK             0.03s
 268  5/12 unittest_nntrainer_activations OK             0.03s
 269  6/12 unittest_nntrainer_internal    OK             0.23s
 270  7/12 unittest_nntrainer_layers      OK             0.22s
 271  8/12 unittest_nntrainer_lazy_tensor OK             0.04s
 272  9/12 unittest_nntrainer_tensor      OK             0.04s
 273 10/12 unittest_util_func             OK             0.05s
 274 11/12 unittest_databuffer_file       OK             0.12s
 275 12/12 unittest_nntrainer_modelfile   OK             2.22s
 276
 277 Ok:                 12
 278 Expected Fail:      0
 279 Fail:               0
 280 Unexpected Pass:    0
 281 Skipped:            0
 282 Timeout:            0
 283 ```
 284
 285 if you want to run particular test
 286
 287 ```bash
 288 $ meson -C build test $(test name)
 289 ```
 290
 291 2. Sample app test
 292 NNTrainer provides extensive sample app running test.
 293
 294 Meson build with `enable-app` set to true
 295 ```bash
 296 $ echo $(pwd)
 297 (project root)
 298
 299 $ meson build -Denable-app=true
 300 The Meson build system
 301 Version: 0.54.3
 302 ...
 303 Configuring capi-nntrainer.pc using configuration
 304 Run-time dependency GTest found: YES (building self)
 305 Build targets in project: 17
 306
 307 Found ninja-1.10.0.git.kitware.jobserver-1 at /home/jlee/.local/bin/ninja
 308
 309 $ ninja -C build test
 310 ...
 311  1/21 app_classification             OK             3.59s
 312  2/21 app_classification_func        OK             42.77s
 313  3/21 app_knn                        OK             4.81s
 314  4/21 app_logistic                   OK             14.11s
 315  5/21 app_DeepQ                      OK             30.30s
 316  6/21 app_training                   OK             38.36s
 317  7/21 app_classification_capi_ini    OK             32.65s
 318  8/21 app_classification_capi_file   OK             32.04s
 319  9/21 app_classification_capi_func   OK             29.13s
 320  ...
 321 ```
 322
 323 if you want to run particular example only
 324
 325 ```bash
 326 $ meson -C build test $(test name) #app_classification_capi_func
 327 ```
 328
 329 ### Running Examples
 330
 331 1. [Training](https://github.com/nnstreamer/nntrainer/blob/master/Applications/Training/README.md)
 332
 333 After build, run with following arguments
 334 Make sure to put last '/' for the resources directory.
 335 ```bash
 336 $./path/to/example ./path/to/settings.ini ./path/to/resource/directory/
 337 ```
 338
 339 To run the 'Training', for example, do as follows.
 340
 341 ```bash
 342 $ pwd
 343 ./nntrainer
 344 $ LD_LIBRARY_PATH=./build/nntrainer ./build/Applications/Training/jni/nntrainer_training ./Applications/Training/res/Training.ini ./Applications/Training/res/
 345 ../../res/happy/happy1.bmp
 346 ../../res/happy/happy2.bmp
 347 ../../res/happy/happy3.bmp
 348 ../../res/happy/happy4.bmp
 349 ../../res/happy/happy5.bmp
 350 ../../res/sad/sad1.bmp
 351 ../../res/sad/sad2.bmp
 352
 353 ...
 354
 355 ```
 356
 357 ## Open Source License
 358
 359 The nntrainer is an open source project released under the terms of the Apache License version 2.0.