README.md

   1 # NNtrainer
   2
   3 [![Code Coverage](http://ec2-54-180-96-14.ap-northeast-2.compute.amazonaws.com/nntrainer/ci/badge/codecoverage.svg)](http://ec2-54-180-96-14.ap-northeast-2.compute.amazonaws.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
  31 ## Components
  32
  33 ### NeuralNetwork
  34
  35 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.
  36 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:
  37
  38 - **_Type:_** Network Type - Regression, KNN, NeuralNetwork
  39 - **_Layers:_** Name of Layers of Network Model
  40 - **_Learning\_rate:_** Learning rate which is used for all Layers
  41 - **_Decay\_rate:_** Rate for Exponentially Decayed Learning Rate
  42 - **_Epoch:_** Max Number of Training Iteration.
  43 - **_Optimizer:_** Optimizer for the Network Model - sgd, adam
  44 - **_Activation:_** Activation Function - sigmoid , tanh
  45 - **_Cost:_** Cost Function -
  46       msr(mean square root error), categorical (for logistic regression), cross (cross entropy)
  47 - **_Model:_** Name of Model. Weight Data is saved in the name of this.
  48 - **_minibach:_** mini batch size
  49 - **_beta1,beta2,epsilon:_** hyper parameters for the adam optimizer
  50
  51
  52 ### Layers
  53
  54 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.)
  55
  56 - **_Type:_** InputLayer, OutputLayer, FullyConnectedLayer
  57 - **_Id:_** Index of Layer
  58 - **_Height:_** Height of Weight Data (Input Dimension)
  59 - **_Width:_** Width of Weight Data ( Hidden Layer Dimension)
  60 - **_Bias\_zero:_** Boolean for Enable/Disable Bias
  61
  62
  63 ### Tensor
  64
  65 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.
  66
  67 ## Getting Started
  68
  69 ### Prerequisites
  70
  71 The following dependencies are needed to compile / build / run.
  72
  73 *   gcc/g++
  74 *   meson (>=0.50.0)
  75 *   blas library ( CBLAS ) (for CPU Acceleration)
  76 *   cuda, cudart, cublas (should match the version) (GPU Acceleration on PC)
  77 *   tensorflow-lite (>=1.4.0)
  78 *   jsoncpp ( >=0.6.0) (openAI Environment on PC)
  79 *   libcurl3 (>= 7.47 ) (openAI Environment on PC)
  80
  81 ### How to Build
  82
  83 Download the source file by cloning the github repository.
  84
  85 ```bash
  86 $ git clone https://github.com/nnstreamer/nntrainer
  87 ```
  88
  89 After completing download the sources, you can find the several directories and files as below.
  90
  91 ``` bash
  92 $ cd nntrainer
  93
  94 $ ls -1
  95 api
  96 Applications
  97 debian
  98 doc
  99 jni
 100 LICENSE
 101 meson.build
 102 meson_options.txt
 103 nntrainer
 104 nntrainer.pc.in
 105 packaging
 106 README.md
 107 test
 108
 109 $ git log --oneline
 110 f1a3a05 (HEAD -> master, origin/master, origin/HEAD) Add more badges
 111 37032a1 Add Unit Test Cases for Neural Network Initialization
 112 181a003 lower case for layer type.
 113 1eb399b Update clang-format
 114 87f1de7 Add Unit Test for Neural Network
 115 cd5c36e Add Coverage Test badge for nntrainer
 116 ...
 117 ```
 118
 119 You can find the source code of the core library in nntrainer/src. In order to build them, use [meson](https://mesonbuild.com/)
 120 ```bash
 121 $ meson build
 122 The Meson build system
 123 Version: 0.50.1
 124 Source dir: /home/wook/Work/NNS/nntrainer
 125 Build dir: /home/wook/Work/NNS/nntrainer/build
 126 Build type: native build
 127 Project name: nntrainer
 128 Project version: 0.0.1
 129 Native C compiler: cc (gcc 7.5.0 "cc (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0")
 130 Native C++ compiler: c++ (gcc 7.5.0 "c++ (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0")
 131 Build machine cpu family: x86_64
 132 Build machine cpu: x86_64
 133 ...
 134 Build targets in project: 11
 135 Found ninja-1.8.2 at /usr/bin/ninja
 136
 137 $ ninja -C build
 138 ninja: Entering directory `build'
 139 [41/41] Linking target test/unittest/unittest_nntrainer_internal.
 140 ```
 141
 142 After completion of the build, the shared library, 'libnntrainer.so' and the static library, 'libnntrainer.a' will be placed in build/nntrainer.
 143 ```bash
 144 $ ls build/nntrainer -1
 145 d48ed23@@nntrainer@sha
 146 d48ed23@@nntrainer@sta
 147 libnntrainer.a
 148 libnntrainer.so
 149 ```
 150
 151 In order to install them with related header files to your system, use the 'install' sub-command.
 152 ```bash
 153 $ ninja -C build install
 154 ```
 155 Then, you will find the libnntrainer.so and related .h files in /usr/local/lib and /usr/local/include directories.
 156
 157 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,
 158 ```bash
 159 $ ls build/Applications/Training/jni/ -1
 160 e189c96@@nntrainer_training@exe
 161 nntrainer_training
 162 ```
 163
 164 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.
 165
 166 To run the 'Training' example, do as follows
 167 ```bash
 168 $ pwd
 169 ./nntrainer
 170 $ LD_LIBRARY_PATH=./build/nntrainer ./build/Applications/Training/jni/nntrainer_training ./Applications/Training/res/Training.ini ./Applications/Training/res/
 171 ../../res/happy/happy1.bmp
 172 ../../res/happy/happy2.bmp
 173 ../../res/happy/happy3.bmp
 174 ../../res/happy/happy4.bmp
 175 ../../res/happy/happy5.bmp
 176 ../../res/sad/sad1.bmp
 177 ../../res/sad/sad2.bmp
 178
 179 ...
 180
 181 ```
 182
 183 ## Open Source License
 184
 185 The nntrainer is an open source project released under the terms of the Apache License version 2.0.