{"id":13437720,"url":"https://github.com/hpi-xnor/BMXNet-v2","last_synced_at":"2025-03-19T18:30:39.593Z","repository":{"id":33750447,"uuid":"160341516","full_name":"hpi-xnor/BMXNet-v2","owner":"hpi-xnor","description":"BMXNet 2: An Open-Source Binary Neural Network Implementation Based on MXNet","archived":false,"fork":false,"pushed_at":"2022-05-20T21:49:09.000Z","size":49820,"stargazers_count":231,"open_issues_count":11,"forks_count":33,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-10-27T23:23:30.176Z","etag":null,"topics":["binary-neural-networks","bmxnet-v2","deep-learning","mxnet","xnor-convolutions"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hpi-xnor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2018-12-04T10:41:16.000Z","updated_at":"2024-10-01T19:52:18.000Z","dependencies_parsed_at":"2022-08-25T08:51:13.009Z","dependency_job_id":null,"html_url":"https://github.com/hpi-xnor/BMXNet-v2","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpi-xnor%2FBMXNet-v2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpi-xnor%2FBMXNet-v2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpi-xnor%2FBMXNet-v2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpi-xnor%2FBMXNet-v2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hpi-xnor","download_url":"https://codeload.github.com/hpi-xnor/BMXNet-v2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244483106,"owners_count":20460056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-neural-networks","bmxnet-v2","deep-learning","mxnet","xnor-convolutions"],"created_at":"2024-07-31T03:00:59.648Z","updated_at":"2025-03-19T18:30:37.145Z","avatar_url":"https://github.com/hpi-xnor.png","language":"C++","funding_links":[],"categories":["C++","\u003ca name=\"Vision\"\u003e\u003c/a\u003e2. Vision","Software and Repositories"],"sub_categories":["2.1 Image Classification"],"readme":"# BMXNet 2 // Hasso Plattner Institute\n\nA fork of the deep learning framework [mxnet](http://mxnet.io) to study and implement quantization and binarization in neural networks.\n\nThis project is based on the [first version of BMXNet](https://github.com/hpi-xnor/BMXNet), but is different in that it reuses more of the original MXNet operators.\nThis aim was to have only minimal changes to C++ code to get better maintainability with future versions of mxnet.\n\n## mxnet version\n\nThis version of BMXNet 2 is based on: *mxnet v1.5.1*\n\n## News\n\nSee all BMXNet changes: [Changelog](CHANGELOG.md).\n\n- **May 21, 2019**\n    - Model converter for deployment released ([Test \u0026 Example](tests/binary/test_converter.py))\n- **Sep 01, 2018**\n    - We rebuilt BMXNet to utilize the new Gluon API for better maintainability\n    - To build binary neural networks, you can use drop in replacements of convolution and dense layers (see [Usage](#usage)):\n    - Note that this project is still in beta and changes might be frequent\n\n# Setup\n\nIf you only want to test the basics, you can also look at our [docker setup](#docker-setup).\n\nWe use [CMake](https://cmake.org/download/) to build the project.\nMake sure to [install all the dependencies described here](docs/install/build_from_source.md#prerequisites).\nIf you install CUDA 10, you will need CMake \u003e=3.12.2\n\nAdjust settings in cmake (build-type ``Release`` or ``Debug``, configure CUDA, OpenBLAS or Atlas, OpenCV, OpenMP etc.).\n\nFurther, we recommend [Ninja](https://ninja-build.org/) as a build system for faster builds (Ubuntu: `sudo apt-get install ninja-build`).\n\n```bash\ngit clone --recursive https://github.com/hpi-xnor/BMXNet-v2.git # remember to include the --recursive\ncd BMXNet-v2\nmkdir build \u0026\u0026 cd build\ncmake .. -G Ninja # if any error occurs, apply ccmake or cmake-gui to adjust the cmake config.\nccmake . # or GUI cmake\nninja\n```\n\n#### Build the MXNet Python binding\n\nStep 1 Install prerequisites - python, setup-tools, python-pip and numpy.\n```bash\nsudo apt-get install -y python-dev python3-dev virtualenv\nwget -nv https://bootstrap.pypa.io/get-pip.py\npython3 get-pip.py\npython2 get-pip.py\n```\n\nStep 1b (Optional) Create or activate a [virtualenv](https://virtualenv.pypa.io/).\n\nStep 2 Install the MXNet Python binding.\n```bash\ncd \u003cmxnet-root\u003e/python\npip install -e .\n```\n\nIf 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``:\n```bash\n$ export LD_LIBRARY_PATH=\u003cmxnet-root\u003e/build/Release\n$ export PYTHONPATH=\u003cmxnet-root\u003e/python\n```\n\n## Training\n\nMake sure that you have a new version of our example submodule [example/bmxnet-examples](https://github.com/hpi-xnor/BMXNet-v2-examples/):\n```bash\ncd example/bmxnet-examples\ngit checkout master\ngit pull\n```\n\nExamples for hyperparameters are documented in the [Wiki](https://github.com/hpi-xnor/BMXNet-v2-wiki/blob/master/hyperparameters.md).\n\n## Inference\n\nTo 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.\nPlease check the corresponding [test case](tests/binary/test_converter.py).\n```bash\nbuild/tools/binary_converter/model-converter model-0000.params\n```\n\n## Tests\n\nTo run BMXNet specific tests install `pytest`:\n```bash\npip install pytest\n```\n\nThen simply run:\n```bash\npytest tests/binary\n```\n\n## Usage\n\nWe added binary versions of the following layers of the gluon API:\n- gluon.nn.Dense -\u003e gluon.nn.QDense\n- gluon.nn.Conv1D -\u003e gluon.nn.QConv1D\n- gluon.nn.Conv2D -\u003e gluon.nn.QConv2D\n- gluon.nn.Conv3D -\u003e gluon.nn.QConv3D\n\n## Overview of Changes\n\nWe added three functions `det_sign` ([ada4ea1d](https://github.com/hpi-xnor/BMXNet-v2/commit/ada4ea1d4418cfdd6cbc6d0159e1a716cb01cd85)), `round_ste` ([044f81f0](https://github.com/hpi-xnor/BMXNet-v2/commit/044f81f028887b9842070df28b28de394bd07516)) and `contrib.gradcancel` to MXNet (see [src/operator/contrib/gradient_cancel[-inl.h|.cc|.cu]](src/operator/contrib)).\n\nThe rest of our code resides in the following folders/files:\n- Examples are in a submodule in [example/bmxnet-examples](https://github.com/hpi-xnor/BMXNet-v2-examples)\n- Tests are in [tests/binary](tests/binary)\n- Layers are in [python/mxnet/gluon/nn/binary_layers.py](python/mxnet/gluon/nn/binary_layers.py)\n- Converter is in [tools/binary_converter](tools/binary_converter)\n\nFor more details see the [Changelog](CHANGELOG.md).\n\n## Docker setup\n\nA docker image for testing of BMXNet can be build similar to our CI script at [.gitlab-ci.yml](.gitlab-ci.yml), however it only supports CPU, so actual training might be tedious.\n\n```bash\ncd ci\ndocker 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\n```\n\nThen you can enter the container (and automatically delete it)\n```bash\ndocker run --rm -it bmxnet2-base/build.ubuntu_cpu # deletes the container after running\ndocker run -it bmxnet2-base/build.ubuntu_cpu # keeps the container after running (it needs to be removed manually later)\n```\n\nInside the container you can now clone, build and test BMXNet 2\n```bash\n# clone\nmkdir -p /builds/\ncd /builds/\ngit clone https://github.com/hpi-xnor/BMXNet-v2.git bmxnet --recursive\ncd bmxnet\n# build\nmkdir build\ncd build\ncmake -DBINARY_WORD_TYPE=uint32 -DUSE_CUDA=OFF -DUSE_MKL_IF_AVAILABLE=OFF -GNinja ..\ncd ..\ncmake --build build\nexport PYTHONPATH=/builds/bmxnet/python # add python binding\n# run the tests (we need to upgrade pytest first via pip3)\npip3 install pytest --upgrade\npytest tests/binary\n```\n\nYou 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).\n```bash\ncd example/bmxnet-examples/mnist/\ngit checkout master\npip3 install mxboard\npython3 mnist-lenet.py --bits 1 # trains a binary lenet model with 1 bit activations and 1 bit weights on MNIST\n```\n\n### Citing BMXNet 2\n\nPlease cite [our paper](https://arxiv.org/abs/1812.01965) about BMXNet 2 in your publications if it helps your research work:\n\n```text\n@article{bmxnetv2,\n  title = {Training Competitive Binary Neural Networks from Scratch},\n  author = {Joseph Bethge and Marvin Bornstein and Adrian Loy and Haojin Yang and Christoph Meinel},\n  journal = {ArXiv e-prints},\n  archivePrefix = \"arXiv\",\n  eprint = {1812.01965},\n  Year = {2018}\n}\n```\n\n### References\n\n- [XNOR-Net: ImageNet Classification Using Binary Convolutional Neural Networks](https://arxiv.org/abs/1603.05279)\n- [Binarized Neural Networks: Training Deep Neural Networks with Weights and Activations Constrained to +1 or -1](https://arxiv.org/abs/1602.02830)\n- [DoReFa-Net: Training Low Bitwidth Convolutional Neural Networks with Low Bitwidth Gradients](https://arxiv.org/abs/1606.06160)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpi-xnor%2FBMXNet-v2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhpi-xnor%2FBMXNet-v2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpi-xnor%2FBMXNet-v2/lists"}