-
Notifications
You must be signed in to change notification settings - Fork 4
Getting Started
This page provides all the necessary information for you to get started using and developing the Neural-Network-Translator.
The following software components and dependencies are needed:
- GIT: https://www.git-scm.com
- Anaconda Python 2019.07 or later: https://www.anaconda.com/download
- Arduino IDE (If you want to run the Arduino sample): https://www.arduino.cc/en/Main/Software
- Navigate to the desired target directory
- Open Git Bash:
git clone https://github.com/pg020196/Neural-Network-Translator.git
There are multiple ways to set up the python environment, either with the provided requirements.txt file or with the conda-environment.yml files. The whole project is based on Python 3.7. Unfortunately, some components, in specific the Microsoft CNTK framework, are only available for Python 3.6. Therefore, the proof of concept for the CNTK framework requires a special environment, which is also provided. The environments can be set up as follows:
-
Start Anaconda Prompt and execute the following commands:
conda create -n nnt pip python=3.7activate nnt -
Open Anaconda Navigator and install Jupyter Notebook in version 6.0.3
-
In Anaconda Prompt, navigate to
setup\ -
Install NNT-Requirements:
pip install -r nnt_requirements.txt -
Install PyTorch following the pip installation instructions on the PyTorch website
- Open Anaconda Prompt and execute the following command:
conda env create -f nnt_environment.yml - Activate new environment:
activate nnt - Install PyTorch following the pip installation instructions on the PyTorch website
Note: This is only required if you want to run the PoC CNTK Jupyter Notebook from the samples. Running other code of this repository in this environment is not intended.
- Open Anaconda Prompt and execute the following command:
conda env create -f nnt_36_cntk_environment.yml - Activate new environment:
activate nnt_36_cntk
The repository's structure is as follows:
This folder contains all files for the backend-plug-ins as well as additional required files, such as template or helper files.
This folder contains code files which allow changing code between the frontend or the backend. For instance: Let's suppose a neural network framework only provides networks that work with floats but the microcontroller can only handle integers. To solve this issue, one could develop a conversion plugin that translates float values, e.g. weight or bias values, to integer values.
This folder contains all files for the frontend-plugins as well as additional required files, such as template- or helper-files.
This folder contains multiple files that can be used to get first impressions of the project or to quickly verify translation results. Currently, the following samples are available:
- arduino: In this folder, an exemplary code snippet is provided which processes data from the serial port (input values) and calls the predict-function. Together with the output of the GCC-backend, this file .ino can be flashed on an Arduino Nano microcontroller to execute neural network predictions on an Arduino. For detailed instructions on how to use this file, see How to Run. In addition to that, an integration test is provided which allows automated testing of the flashed neural network. This is also explained in How to Run.
- cntk: In this folder, a Jupyter Notebook provides a proof of concept on how to extract data from a given CNTK-model. This notebook forms the basis for the development of a frontend plugin for the CNTK-framework. Note: This Jupyter Notebook must be executed in the nnt_36_cntk environment!
- keras: In this folder, a Jupyter Notebook provides several implementations to create simple neural networks with Keras which can then be translated by the Neural Network Translator. In addition to that, a CSV-file with some training and test data is provided.
- torch: In this folder, a Jupyter Notebook provides a proof of concept on how to extract data from a given PyTorch-model. This notebook forms the basis for the development of a frontend plugin for the PyTorch-framework.
The setup folder provides the needed environment configurations to execute the neural network translator and/or the Jupyter Notebooks.
The test folder provides exemplary implementations of unit tests for the backend utils, the GCC backend, as well as a complete test suite that combines multiple single-unit tests. In addition to that, multiple exemplary models in the intermediate JSON-file format are provided.
This section briefly covers how to work with the Neural-Network-Translator. A step-by-step guide on how to run the translator can be found in the How to Run section.
For the project's start, we decided to build a translator for neural networks made with Keras (TensorFlow) to an Arduino microcontroller. To prove the concept of being able to translate models created with different frameworks, we then created Jupyter Notebooks which cover the information extraction from CNTK and PyTorch neural networks. Since the latter two are only proof of concepts, a good way to start is to look at the Jupyter Notebook "keras example networks" which explains how simple neural networks can be created with Keras. If you are already familiar with training neural networks with Keras, you can jump to the next section which covers a sample translation of a neural network to an Arduino backend.
With a created neural network at hand, you can start the translation process. Therefore, simply run the neural network translator. The available arguments are described in the NN Translator wiki page.
Please feel free to contribute to the project according to the provided license. A good way to get to know the project's structure is to follow the steps in Section 3 to perform a simple translation. In addition to that, this wiki contains further information about the software structure and how to add new plugins.