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 <a href="https://scan.coverity.com/projects/nnstreamer-nntrainer">
   8   <img alt="Coverity Scan Build Status"
   9        src="https://scan.coverity.com/projects/22512/badge.svg"/>
  10 </a>
  11
  12 NNtrainer is a Software Framework for training Neural Network models on devices.
  13
  14 ## Overview
  15
  16 NNtrainer is an Open Source Project. The aim of the NNtrainer is to develop a Software Framework to train neural network models on embedded devices which have relatively limited resources. Rather than training whole layers of a network, NNtrainer trains only one or a few layers of the layers added after a feature extractor.
  17
  18 Even though NNTrainer can be used to train sub-models, it requires implementation of additional functionalities to train models obtained from other machine learning and deep learning libraries. In the current version, various machine learning algorithms such as k-Nearest Neighbor (k-NN), Neural Networks, Logistic Regression and Reinforcement Learning algorithms are implemented. We also provide examples for various tasks such as transfer learning of models. In some of these examples, deep learning models such as Mobilenet V2 trained with Tensorflow-lite, are used as feature extractors. All of these were tested on Galaxy S8 with Android and PC (Ubuntu 16.04).
  19
  20 ## Maintainer
  21 * [Jijoong Moon](https://github.com/jijoongmoon)
  22 * [MyungJoo Ham](https://github.com/myungjoo)
  23 * [Geunsik Lim](https://github.com/leemgs)
  24
  25 ## Reviewers
  26 * [Sangjung Woo](https://github.com/again4you)
  27 * [Wook Song](https://github.com/wooksong)
  28 * [Jaeyun Jung](https://github.com/jaeyun-jung)
  29 * [Hyoungjoo Ahn](https://github.com/helloahn)
  30 * [Parichay Kapoor](https://github.com/kparichay)
  31 * [Dongju Chae](https://github.com/dongju-chae)
  32 * [Gichan Jang](https://github.com/gichan-jang)
  33 * [Yongjoo Ahn](https://github.com/anyj0527)
  34 * [Jihoon Lee](https://github.com/zhoonit)
  35 * [Hyeonseok Lee](https://github.com/lhs8928)
  36 * [Mete Ozay](https://github.com/meteozay)
  37
  38 ## Components
  39
  40 ### Supported Layers
  41
  42 This component defines layers which consist of a neural network model. Layers have their own properties to be set.
  43
  44  | Keyword | Layer Name | Description |
  45  |:-------:|:---:|:---|
  46  |  conv2d | Convolution 2D |Convolution 2-Dimentional Layer |
  47  |  pooling2d | Pooling 2D |Pooling 2-Dimentional Layer. Support average / max / global average / global max pooing |
  48  | flatten | Flatten | Flatten Layer |
  49  | fully_connected | Fully Connected | Fully Connected Layer |
  50  | input | Input | Input Layer.  This is not always requied. |
  51  | batch_normalization | Batch Normalization Layer | Batch Normalization Layer. |
  52  | loss layer | loss layer | hidden from users |
  53  | activation | activaiton layer | set by layer property |
  54
  55 ### Supported Optimizers
  56
  57 NNTrainer Provides
  58
  59  | Keyword | Optimizer Name | Description |
  60  |:-------:|:---:|:---:|
  61  | sgd | Stochastic Gradient Decent | - |
  62  | adam | Adaptive Moment Estimation | - |
  63
  64 ### Supported Loss Functions
  65
  66 NNTrainer provides
  67
  68  | Keyword | Loss Name | Description |
  69  |:-------:|:---:|:---:|
  70  | mse | Mean squared Error | - |
  71  | cross | Cross Entropy - sigmoid | if activation last layer is sigmoid |
  72  | cross | Cross Entropy - softmax | if activation last layer is softmax |
  73
  74 ### Supported Activation Functions
  75
  76 NNTrainer provides
  77
  78  | Keyword | Loss Name | Description |
  79  |:-------:|:---:|:---|
  80  | tanh | tanh function | set as layer property |
  81  | sigmoid | sigmoid function | set as layer property |
  82  | relu | relu function | set as layer propery |
  83  | softmax | softmax function | set as layer propery |
  84  | weight_initializer | Weight Initialization | Xavier(Normal/Uniform), LeCun(Normal/Uniform),  HE(Normal/Unifor) |
  85  | weight_regularizer | weight decay ( L2Norm only ) | needs set weight_regularizer_param & type |
  86  | learnig_rate_decay | learning rate decay | need to set step |
  87
  88 ### Tensor
  89
  90 Tensor is responsible for calculation of a layer. It executes several operations such as addition, division, multiplication, dot production, data averaging and so on. In order to accelerate  calculation speed, CBLAS (C-Basic Linear Algebra: CPU) and CUBLAS (CUDA: Basic Linear Algebra) for PC (Especially NVIDIA GPU) are implemented for some of the operations. Later, these calculations will be optimized.
  91 Currently, we supports lazy calculation mode to reduce complexity for copying tensors during calculations.
  92
  93  | Keyword | Description |
  94  |:-------:|:---:|
  95  | 4D Tensor | B, C, H, W|
  96  | Add/sub/mul/div | - |
  97  | sum, average, argmax | - |
  98  | Dot, Transpose | - |
  99  | normalization, standardization | - |
 100  | save, read | - |
 101
 102 ### Others
 103
 104 NNTrainer provides
 105
 106  | Keyword | Loss Name | Description |
 107  |:-------:|:---:|:---|
 108  | weight_initializer | Weight Initialization | Xavier(Normal/Uniform), LeCun(Normal/Uniform),  HE(Normal/Unifor) |
 109  | weight_regularizer | weight decay ( L2Norm only ) | needs set weight_regularizer_constant & type |
 110  | learnig_rate_decay | learning rate decay | need to set step |
 111
 112 ### APIs
 113 Currently, we provide [C APIs](https://github.com/nnstreamer/nntrainer/blob/master/api/capi/include/nntrainer.h) for Tizen. C++ API will be also provided soon.
 114
 115
 116 ### Examples for NNTrainer
 117
 118 #### [Custom Shortcut Application](https://github.com/nnstreamer/nntrainer/tree/main/Applications/Tizen_native/CustomShortcut)
 119
 120
 121 A demo application which enable user defined custom shortcut on galaxy watch.
 122
 123 #### [MNIST Example](https://github.com/nnstreamer/nntrainer/tree/main/Applications/MNIST)
 124
 125 An example to train mnist dataset. It consists two convolution 2d layer, 2 pooling 2d layer, flatten layer and fully connected layer.
 126
 127 #### [Reinforcement Learning Example](https://github.com/nnstreamer/nntrainer/tree/main/Applications/ReinforcementLearning/DeepQ)
 128
 129 A reinforcement learning example with cartpole game. It is using DeepQ algorithm.
 130
 131 #### [Transfer Learning Examples](https://github.com/nnstreamer/nntrainer/tree/main/Applications/TransferLearning)
 132
 133 Transfer learning examples with for image classification using the Cifar 10 dataset and for OCR. TFlite is used for feature extractor and modify last layer (fully connected layer) of network.
 134
 135 #### ~Tizen CAPI Example~
 136
 137 An example to demonstrate c api for Tizen. It is same transfer learing but written with tizen c api.~
 138 Deleted instead moved to a [test](https://github.com/nnstreamer/nntrainer/blob/master/test/tizen_capi/unittest_tizen_capi.cpp)
 139
 140 #### [KNN Example](https://github.com/nnstreamer/nntrainer/tree/main/Applications/KNN)
 141
 142 A transfer learning example with for image classification using the Cifar 10 dataset. TFlite is used for feature extractor and compared with KNN.
 143
 144 #### [Logistic Regression Example](https://github.com/nnstreamer/nntrainer/tree/main/Applications/LogisticRegression)
 145
 146 A logistic regression example using NNTrainer.
 147
 148 ## [Getting Started](https://github.com/nnstreamer/nntrainer/blob/main/docs/getting-started.md)
 149
 150 Instructions for installing NNTrainer.
 151
 152 ### [Running Examples](https://github.com/nnstreamer/nntrainer/blob/main/docs/how-to-run-examples.md)
 153
 154 Instructions for preparing NNTrainer for execution
 155
 156 ## Open Source License
 157
 158 The nntrainer is an open source project released under the terms of the Apache License version 2.0.
 159
 160 ## Contributing
 161
 162 Contributions are welcome! Please see our [Contributing](https://github.com/nnstreamer/nntrainer/blob/main/docs/contributing.md) Guide for more details.
 163
 164 [![](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/images/0)](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/links/0)[![](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/images/1)](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/links/1)[![](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/images/2)](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/links/2)[![](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/images/3)](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/links/3)[![](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/images/4)](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/links/4)[![](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/images/5)](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/links/5)[![](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/images/6)](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/links/6)[![](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/images/7)](https://sourcerer.io/fame/dongju-chae/nnstreamer/nntrainer/links/7)