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 KNN, 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 ### NeuralNetwork
  35
  36 This is the component which controls neural network layers. Read the configuration file ([Iniparser](https://github.com/ndevilla/iniparser) is used to parse the configuration file.) and constructs Layers including Input and Output Layer, according to configured information by the user.
  37 The most important role of this component is to activate forward / backward propagation. It activates inferencing and training of each layer while handling the data properly among them. There are properties to describe network model as below:
  38
  39 - **_Type:_** Network Type - Regression, KNN, NeuralNetwork
  40 - **_Layers:_** Name of Layers of Network Model
  41 - **_Learning\_rate:_** Learning rate which is used for all Layers
  42 - **_Decay\_rate:_** Rate for Exponentially Decayed Learning Rate
  43 - **_Epoch:_** Max Number of Training Iteration.
  44 - **_Optimizer:_** Optimizer for the Network Model - sgd, adam
  45 - **_Activation:_** Activation Function - sigmoid , tanh
  46 - **_Cost:_** Cost Function -
  47       msr(mean square root error), categorical (for logistic regression), cross (cross entropy)
  48 - **_Model:_** Name of Model. Weight Data is saved in the name of this.
  49 - **_minibach:_** mini batch size
  50 - **_beta1,beta2,epsilon:_** hyper parameters for the adam optimizer
  51
  52
  53 ### Layers
  54
  55 This component defines Layers which consist of Neural Network Model. Every neural network model must have one Input & Output Layer and other layers such as Fully Connected or Convolution can be added between them. (For now, supports Input & Output Layer, Fully Connected Layer.)
  56
  57 - **_Type:_** InputLayer, OutputLayer, FullyConnectedLayer
  58 - **_Id:_** Index of Layer
  59 - **_Height:_** Height of Weight Data (Input Dimension)
  60 - **_Width:_** Width of Weight Data ( Hidden Layer Dimension)
  61 - **_Bias\_zero:_** Boolean for Enable/Disable Bias
  62
  63
  64 ### Tensor
  65
  66 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.
  67
  68 ## Getting Started
  69
  70 ### Prerequisites
  71
  72 The following dependencies are needed to compile / build / run.
  73
  74 *   gcc/g++
  75 *   meson (>=0.50.0)
  76 *   blas library ( CBLAS ) (for CPU Acceleration, libopenblas is used for now)
  77 *   cuda, cudart, cublas (should match the version) (GPU Acceleration on PC)
  78 *   tensorflow-lite (>=1.4.0)
  79 *   libjsoncpp ( >=0.6.0) (openAI Environment on PC)
  80 *   libcurl3 (>= 7.47 ) (openAI Environment on PC)
  81 *   libiniparser
  82 *   libgtest (for testing)
  83
  84
  85 ### Give It a Go Build with Docker
  86
  87 You can use [docker image](https://hub.docker.com/r/lunapocket/nntrainer-build-env) to easily set up and try building.
  88
  89 To run the docker
  90
  91 ```bash
  92 $ docker pull lunapocket/nntrainer-build-env:ubuntu-18.04
  93 $ docker run --rm -it  lunapocket/nntrainer-build-env:ubuntu-18.04
  94 ```
  95
  96 Inside docker...
  97
  98 ```bash
  99 $ cd /root/nntrainer
 100 $ git pull # If you want to build with latest sources.
 101 ```
 102
 103 You can try build from now on without concerning about Prerequisites.
 104
 105 ### How to Build
 106
 107 Download the source file by cloning the github repository.
 108
 109 ```bash
 110 $ git clone https://github.com/nnstreamer/nntrainer
 111 ```
 112
 113 After completing download the sources, you can find the several directories and files as below.
 114
 115 ``` bash
 116 $ cd nntrainer
 117
 118 $ ls -1
 119 api
 120 Applications
 121 debian
 122 doc
 123 jni
 124 LICENSE
 125 meson.build
 126 meson_options.txt
 127 nntrainer
 128 nntrainer.pc.in
 129 packaging
 130 README.md
 131 test
 132
 133 $ git log --oneline
 134 f1a3a05 (HEAD -> master, origin/master, origin/HEAD) Add more badges
 135 37032a1 Add Unit Test Cases for Neural Network Initialization
 136 181a003 lower case for layer type.
 137 1eb399b Update clang-format
 138 87f1de7 Add Unit Test for Neural Network
 139 cd5c36e Add Coverage Test badge for nntrainer
 140 ...
 141 ```
 142
 143 You can find the source code of the core library in nntrainer/src. In order to build them, use [meson](https://mesonbuild.com/)
 144 ```bash
 145 $ meson build
 146 The Meson build system
 147 Version: 0.50.1
 148 Source dir: /home/wook/Work/NNS/nntrainer
 149 Build dir: /home/wook/Work/NNS/nntrainer/build
 150 Build type: native build
 151 Project name: nntrainer
 152 Project version: 0.0.1
 153 Native C compiler: cc (gcc 7.5.0 "cc (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0")
 154 Native C++ compiler: c++ (gcc 7.5.0 "c++ (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0")
 155 Build machine cpu family: x86_64
 156 Build machine cpu: x86_64
 157 ...
 158 Build targets in project: 11
 159 Found ninja-1.8.2 at /usr/bin/ninja
 160
 161 $ ninja -C build
 162 ninja: Entering directory `build'
 163 [41/41] Linking target test/unittest/unittest_nntrainer_internal.
 164 ```
 165
 166 After completion of the build, the shared library, 'libnntrainer.so' and the static library, 'libnntrainer.a' will be placed in build/nntrainer.
 167 ```bash
 168 $ ls build/nntrainer -1
 169 d48ed23@@nntrainer@sha
 170 d48ed23@@nntrainer@sta
 171 libnntrainer.a
 172 libnntrainer.so
 173 ```
 174
 175 In order to install them with related header files to your system, use the 'install' sub-command.
 176 ```bash
 177 $ ninja -C build install
 178 ```
 179 Then, you will find the libnntrainer.so and related .h files in /usr/local/lib and /usr/local/include directories.
 180
 181 By default, the command ```ninja -C build`` generates the five example application binaries (Classification, KNN, LogisticRegression, ReinforcementLearning, and Training) you could try in build/Applications. For 'Training' as an example case,
 182 ```bash
 183 $ ls build/Applications/Training/jni/ -1
 184 e189c96@@nntrainer_training@exe
 185 nntrainer_training
 186 ```
 187
 188 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.
 189
 190 ### Running Examples
 191
 192
 193 1. [Training](https://github.com/nnstreamer/nntrainer/blob/master/Applications/Training/README.md)
 194
 195 After build, run with following arguments
 196 Make sure to put last '/' for the resources directory.
 197 ```bash
 198 $./path/to/example ./path/to/settings.ini ./path/to/resource/directory/
 199 ```
 200
 201 To run the 'Training', for example, do as follows.
 202
 203 ```bash
 204 $ pwd
 205 ./nntrainer
 206 $ LD_LIBRARY_PATH=./build/nntrainer ./build/Applications/Training/jni/nntrainer_training ./Applications/Training/res/Training.ini ./Applications/Training/res/
 207 ../../res/happy/happy1.bmp
 208 ../../res/happy/happy2.bmp
 209 ../../res/happy/happy3.bmp
 210 ../../res/happy/happy4.bmp
 211 ../../res/happy/happy5.bmp
 212 ../../res/sad/sad1.bmp
 213 ../../res/sad/sad2.bmp
 214
 215 ...
 216
 217 ```
 218
 219 ## Open Source License
 220
 221 The nntrainer is an open source project released under the terms of the Apache License version 2.0.