Awesome
BMXNet 2 // Hasso Plattner Institute
A fork of the deep learning framework mxnet to study and implement quantization and binarization in neural networks.
This project is based on the first version of BMXNet, but is different in that it reuses more of the original MXNet operators. This aim was to have only minimal changes to C++ code to get better maintainability with future versions of mxnet.
mxnet version
This version of BMXNet 2 is based on: mxnet v1.5.1
News
See all BMXNet changes: Changelog.
- May 21, 2019
- Model converter for deployment released (Test & Example)
- Sep 01, 2018
- We rebuilt BMXNet to utilize the new Gluon API for better maintainability
- To build binary neural networks, you can use drop in replacements of convolution and dense layers (see Usage):
- Note that this project is still in beta and changes might be frequent
Setup
If you only want to test the basics, you can also look at our docker setup.
We use CMake to build the project. Make sure to install all the dependencies described here. If you install CUDA 10, you will need CMake >=3.12.2
Adjust settings in cmake (build-type Release
or Debug
, configure CUDA, OpenBLAS or Atlas, OpenCV, OpenMP etc.).
Further, we recommend Ninja as a build system for faster builds (Ubuntu: sudo apt-get install ninja-build
).
git clone --recursive https://github.com/hpi-xnor/BMXNet-v2.git # remember to include the --recursive
cd BMXNet-v2
mkdir build && cd build
cmake .. -G Ninja # if any error occurs, apply ccmake or cmake-gui to adjust the cmake config.
ccmake . # or GUI cmake
ninja
Build the MXNet Python binding
Step 1 Install prerequisites - python, setup-tools, python-pip and numpy.
sudo apt-get install -y python-dev python3-dev virtualenv
wget -nv https://bootstrap.pypa.io/get-pip.py
python3 get-pip.py
python2 get-pip.py
Step 1b (Optional) Create or activate a virtualenv.
Step 2 Install the MXNet Python binding.
cd <mxnet-root>/python
pip install -e .
If your mxnet python binding still not works, you can add the location of the libray to your LD_LIBRARY_PATH
as well as the mxnet python folder to your PYTHONPATH
:
$ export LD_LIBRARY_PATH=<mxnet-root>/build/Release
$ export PYTHONPATH=<mxnet-root>/python
Training
Make sure that you have a new version of our example submodule example/bmxnet-examples:
cd example/bmxnet-examples
git checkout master
git pull
Examples for hyperparameters are documented in the Wiki.
Inference
To speed up inference and compress your model, you need to save it as a symbol (not with gluon) and afterwards convert it with the model-converter. Please check the corresponding test case.
build/tools/binary_converter/model-converter model-0000.params
Tests
To run BMXNet specific tests install pytest
:
pip install pytest
Then simply run:
pytest tests/binary
Usage
We added binary versions of the following layers of the gluon API:
- gluon.nn.Dense -> gluon.nn.QDense
- gluon.nn.Conv1D -> gluon.nn.QConv1D
- gluon.nn.Conv2D -> gluon.nn.QConv2D
- gluon.nn.Conv3D -> gluon.nn.QConv3D
Overview of Changes
We added three functions det_sign
(ada4ea1d), round_ste
(044f81f0) and contrib.gradcancel
to MXNet (see src/operator/contrib/gradient_cancel[-inl.h|.cc|.cu]).
The rest of our code resides in the following folders/files:
- Examples are in a submodule in example/bmxnet-examples
- Tests are in tests/binary
- Layers are in python/mxnet/gluon/nn/binary_layers.py
- Converter is in tools/binary_converter
For more details see the Changelog.
Docker setup
A docker image for testing of BMXNet can be build similar to our CI script at .gitlab-ci.yml, however it only supports CPU, so actual training might be tedious.
cd ci
docker build -f docker/Dockerfile.build.ubuntu_cpu --build-arg USER_ID=1000 --build-arg GROUP_ID=1000 --cache-from bmxnet2-base/build.ubuntu_cpu -t bmxnet2-base/build.ubuntu_cpu docker
Then you can enter the container (and automatically delete it)
docker run --rm -it bmxnet2-base/build.ubuntu_cpu # deletes the container after running
docker run -it bmxnet2-base/build.ubuntu_cpu # keeps the container after running (it needs to be removed manually later)
Inside the container you can now clone, build and test BMXNet 2
# clone
mkdir -p /builds/
cd /builds/
git clone https://github.com/hpi-xnor/BMXNet-v2.git bmxnet --recursive
cd bmxnet
# build
mkdir build
cd build
cmake -DBINARY_WORD_TYPE=uint32 -DUSE_CUDA=OFF -DUSE_MKL_IF_AVAILABLE=OFF -GNinja ..
cd ..
cmake --build build
export PYTHONPATH=/builds/bmxnet/python # add python binding
# run the tests (we need to upgrade pytest first via pip3)
pip3 install pytest --upgrade
pytest tests/binary
You can even train a simple binary MNIST model, but you might need to update the examples to the newest version first (checkout the master branch).
cd example/bmxnet-examples/mnist/
git checkout master
pip3 install mxboard
python3 mnist-lenet.py --bits 1 # trains a binary lenet model with 1 bit activations and 1 bit weights on MNIST
Citing BMXNet 2
Please cite our paper about BMXNet 2 in your publications if it helps your research work:
@article{bmxnetv2,
title = {Training Competitive Binary Neural Networks from Scratch},
author = {Joseph Bethge and Marvin Bornstein and Adrian Loy and Haojin Yang and Christoph Meinel},
journal = {ArXiv e-prints},
archivePrefix = "arXiv",
eprint = {1812.01965},
Year = {2018}
}