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
   5 NNtrainer is Software Framework for Training Neural Network Models on Devices.
   6
   7 ## Overview
   8
   9 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.
  10
  11 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).
  12
  13 ## Maintainer
  14 * [Jijoong Moon](https://github.com/jijoongmoon)
  15 * [MyungJoo Ham](https://github.com/myungjoo)
  16 * [Geunsik Lim](https://github.com/leemgs)
  17
  18 ## Reviewers
  19 * [Sangjung Woo](https://github.com/again4you)
  20 * [Wook Song](https://github.com/wooksong)
  21 * [Jaeyun Jung](https://github.com/jaeyun-jung)
  22 * [Hyoungjoo Ahn](https://github.com/helloahn)
  23 * [Parichay Kapoor](https://github.com/kparichay)
  24 * [Dongju Chae](https://github.com/dongju-chae)
  25 * [Gichan Jang](https://github.com/gichan-jang)
  26 * [Yongjoo Ahn](https://github.com/anyj0527)
  27
  28 ## Components
  29
  30 ### NeuralNetwork
  31
  32 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.
  33 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:
  34
  35 - **_Type:_** Network Type - Regression, KNN, NeuralNetwork
  36 - **_Layers:_** Name of Layers of Network Model
  37 - **_Learning\_rate:_** Learning rate which is used for all Layers
  38 - **_Decay\_rate:_** Rate for Exponentially Decayed Learning Rate
  39 - **_Epoch:_** Max Number of Training Iteration.
  40 - **_Optimizer:_** Optimizer for the Network Model - sgd, adam
  41 - **_Activation:_** Activation Function - sigmoid , tanh
  42 - **_Cost:_** Cost Function -
  43       msr(mean square root error), categorical (for logistic regression), cross (cross entropy)
  44 - **_Model:_** Name of Model. Weight Data is saved in the name of this.
  45 - **_minibach:_** mini batch size
  46 - **_beta1,beta2,epsilon:_** hyper parameters for the adam optimizer
  47
  48
  49 ### Layers
  50
  51 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.)
  52
  53 - **_Type:_** InputLayer, OutputLayer, FullyConnectedLayer
  54 - **_Id:_** Index of Layer
  55 - **_Height:_** Height of Weight Data (Input Dimension)
  56 - **_Width:_** Width of Weight Data ( Hidden Layer Dimension)
  57 - **_Bias\_zero:_** Boolean for Enable/Disable Bias
  58
  59
  60 ### Tensor
  61
  62 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.
  63
  64 ## Getting Started
  65
  66 ### Prerequisites
  67
  68 The following dependencies are needed to compile / build / run.
  69
  70 *       gcc/g++
  71 *       CMake ( >= 2.8.3)
  72 *       blas library ( CBLAS ) (for CPU Acceleration)
  73 *       cuda, cudart, cublas (should match the version) (GPU Acceleration on PC)
  74 *       tensorflow-lite (>=1.4.0)
  75 *       jsoncpp ( >=0.6.0) (openAI Environment on PC)
  76 *       libcurl3 (>= 7.47 ) (openAI Environment on PC)
  77
  78 ### How to Build
  79
  80 Download the source file by clone the github repository.
  81
  82 ```bash
  83 $ git clone https://github.com/nnsuite/nntrainer
  84 ```
  85
  86 After completing download the sources, you can find the several directories as below.
  87
  88 ``` bash
  89 $ ls
  90 Applications  CMakeLists.txt  external  include  jni  LICENSE  package.pc.in
  91 ```
  92
  93 There are four applications tested on the Android and Ubuntu (16.04). All of them include the code in NeuralNet directory and has their own CMake file to compile. This is the draft version of the code and need more tailoring.
  94 Just for the example, let\'s compile Training application. Once it is compiled and installed you will find the libnntrainer.so and related .h in /usr/local/lib and /usr/local/include directories.
  95
  96 ``` bash
  97 $ mkdir build
  98 $ cd build
  99 $ cmake  ..
 100 $ make
 101 $ sudo make install
 102 ```
 103
 104 And you could test the nntrainer with Examples in Applications. There are several examples you could try and you can compile with cmake(Ubuntu) and ndk-build (Android). Tensorflow-lite is pre-requite for this example, so you have to install it by your self. If you are trying to run on the Android, it will automatically download tensorflow (1.9.0) and compile as static library.
 105 For the Training Examples, you can do like this:
 106
 107 ```bash
 108 $ cd Application/Training/jni
 109 $ mkdir build
 110 $ cd build
 111 $ cmake  ..
 112 $ make
 113 $ ls
 114 CMakeCache.txt  CMakeFiles  cmake_install.cmake  Makefile  TransferLearning
 115 $ ./Transfer_learning ../../res/Training.ini ../../res/
 116 ../../res/happy/happy1.bmp
 117 ../../res/happy/happy2.bmp
 118 ../../res/happy/happy3.bmp
 119 ../../res/happy/happy4.bmp
 120 ../../res/happy/happy5.bmp
 121 ../../res/sad/sad1.bmp
 122 ../../res/sad/sad2.bmp
 123
 124 ...
 125
 126 ```
 127
 128 ## Open Source License
 129
 130 The nntrainer is an open source project released under the terms of the Apache License version 2.0.