Skip to content
BMXNet 2: An Open-Source Binary Neural Network Implementation Based on MXNet
C++ Python Jupyter Notebook Perl Scala Cuda Other
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update PR Template (#9919) Mar 17, 2018
3rdparty merge up to 1.4.0 Apr 3, 2019
R-package Bump version number (#14841) Apr 30, 2019
amalgamation V1.4.x RAT check fix (#14156) Feb 14, 2019
benchmark/python Add more models to benchmark_score (#12780) Oct 21, 2018
ci v1.4.x: Backport of Windows CI Fixes (#14420) Mar 14, 2019
cmake Merge branch 'master_1.4.0' into feature/binary_forward_gpu Apr 4, 2019
contrib/clojure-package Bump version number (#14841) Apr 30, 2019
cpp-package Fixes for data links (#14526) Mar 26, 2019
docker V1.4.x RAT check fix (#14156) Feb 14, 2019
docs Bump version number (#14841) Apr 30, 2019
example test 32 and 64 bit May 15, 2019
include/mxnet Bump version number (#14841) Apr 30, 2019
julia Fixes for data links (#14526) Mar 26, 2019
make Fix Jetson compilation (#13547) Dec 5, 2018
matlab Fixes for data links (#14526) Mar 26, 2019
perl-package V1.4.x RAT check fix (#14156) Feb 14, 2019
plugin V1.4.x RAT check fix (#14156) Feb 14, 2019
python Merge tag '1.4.1' into master_1.4.1 May 22, 2019
scala-package Bump version number (#14841) Apr 30, 2019
setup-utils Update expected result in osx python install script (#10842) May 10, 2018
src Merge tag '1.4.1' into master_1.4.1 May 22, 2019
tests Merge tag '1.4.1' into master_1.4.1 May 22, 2019
tools improve code formatting May 21, 2019
.clang-tidy [MXNET-860] Remove std::moves that have no affect (#12730) Oct 4, 2018
.codecov.yml Enable C++ coverage (#12642) Sep 24, 2018
.gitattributes [R] To ignore R-pkg when releasing on github (#7007) Jul 13, 2017
.gitignore merge up to 1.4.0 Apr 3, 2019
.gitlab-ci.yml disable ci for 64 bit May 20, 2019
.gitmodules prepare release Dec 5, 2018
.mxnet_root CI docker revamp; Add Jetson, Raspberry and CentOS 7 build [MXNET-42]… Mar 9, 2018
.travis.yml Disable travis tests (#13137) Nov 6, 2018
CHANGELOG.md update changelog and readme May 28, 2019
CMakeLists.txt Merge branch 'master_1.4.0' into feature/binary_forward_gpu Apr 4, 2019
CODEOWNERS add gigasquid (Carin Meier) to the Clojure language binding (#12198) Aug 21, 2018
CONTRIBUTORS.md V1.4.x RAT check fix (#14156) Feb 14, 2019
DISCLAIMER Add DISCLAIMER and lxn2 GPG keys (#7344) Aug 5, 2017
Jenkinsfile v1.4.x: Backport of Windows CI Fixes (#14420) Mar 14, 2019
KEYS upload key (#12301) Aug 23, 2018
LICENSE License fixed with copyrights on 1.4.x release branch (#13856) Jan 16, 2019
MKLDNN_README.md V1.4.x RAT check fix (#14156) Feb 14, 2019
Makefile add Volta and Turing arch (#13069) Nov 21, 2018
NEWS.md V1.4.x RAT check fix (#14156) Feb 14, 2019
NOTICE Update NOTICE (#9706) Feb 6, 2018
README.md update changelog and readme May 28, 2019
appveyor.yml License Adds - some more (#9559) Jan 26, 2018
dev_menu.py Add ARMv7 builds to dev_menu.py (#13432) Nov 28, 2018
mkldnn.mk Implement mkldnn convolution fusion and quantization. (#12530) Oct 9, 2018
readthedocs.yml License fixed with copyrights on 1.4.x release branch (#13856) Jan 16, 2019
snap.python Add snapcraft packaging (#4852) Mar 23, 2017
snapcraft.yaml Bump version number (#14841) Apr 30, 2019

README.md

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.4.1

News

See all BMXNet changes: Changelog.

  • May 21, 2019
  • 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

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:

For more details see the Changelog.

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}
}

References

You can’t perform that action at this time.