prepare release

.gitmodules

@@ -31,4 +31,4 @@
 	url = https://github.com/onnx/onnx-tensorrt.git
 [submodule "example/bmxnet-examples"]
 	path = example/bmxnet-examples
-	url = git@gitlab.hpi.de:joseph.bethge/bmxnet-examples.git
+	url = https://github.com/hpi-xnor/BMXNet-v2-examples

CHANGELOG.md

@@ -1,10 +1,40 @@
 # BMXNet Change Log
+
 Note, that this is not the official mxnet changelog, but rather only the additions we made to mxnet to implement binary layers and examples for BMXNet.
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/) 
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.2.0] - 2018-12-04
+
+First beta version.
+Note that binary (and quantized) examples are *maintained separately in a submodule*:
+[example/bmxnet-examples](https://github.com/hpi-xnor/BMXNet-v2-examples)
+
+### Added
+
+- 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))
+    - `approx_sign`
+- New operator:
+    - `contrib.gradcancel` (see [src/operator/contrib/gradient_cancel[-inl.h|.cc|.cu]](src/operator/contrib))
+    - allows to cancel gradients (element-wise) if absolute value of input is larger than a threshold
+- 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
+- Tests are in [tests/python/unittest/test_binary.py](tests/python/unittest/test_binary.py)
+- Layers are in [python/mxnet/gluon/nn/binary_layers.py](python/mxnet/gluon/nn/binary_layers.py)
+
+### Changed
+
+- Code in [python/mxnet/visualization.py](python/mxnet/visualization.py) changed:
+    - `plot_network` skips certain layers which clutter binary network graphs
+    - `print_summary` calculates compressed model size and prints number of binarized/quantized and full-precision weights
+
 ## [0.1.0] - 2018-09-05
 
 Version of BMXNet started (coincides with adapting our code to Gluon).

README.md

@@ -1,20 +1,18 @@
-# binary neural nets with mxnet // Hasso Plattner Institute
+# BMXNet v2 // Hasso Plattner Institute
 
 A fork of the deep learning framework [mxnet](http://mxnet.io) to study and implement quantization and binarization in neural networks.
 
-Our current efforts are focused on binarizing the inputs and weights of convolutional layers, enabling the use of performant bit operations instead of expensive matrix multiplications as described in, however this related to an older version of BMXNet:
-
-- [BMXNet: An Open-Source Binary Neural Network Implementation Based on MXNet](https://arxiv.org/abs/1705.09864)
+This 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.
+This aim was to have only minimal changes to C++ code to get better maintainability with future versions of mxnet.
 
 ## News
 
 - **Sep 01, 2018** - MXNet v1.3.0
     - We are currently rebuilding 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](#usage)):
     - Changes are now documented in the [Changelog](CHANGELOG.md)
-- **Dec 22, 2017** - MXNet v1.0.0 and cuDNN
-    - We are updating the underlying MXNet to version 1.0.0, see changes and release notes [here](https://github.com/apache/incubator-mxnet/releases/tag/1.0.0).
-    - cuDNN is now supported in the training of binary networks, speeding up the training process by about 2x
+    - Note that this project is still in beta and changes might be frequent
+    - We do not yet support deployment and inference with binary operations and models (please use the [first version of BMXNet](https://github.com/hpi-xnor/BMXNet) instead if you need this).
 
 # Setup
 
@@ -42,11 +40,10 @@ 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
-# optionally create a virtualenv before this step
-pip2 install nose cpplint==1.3.0 pylint==1.9.3 'numpy<=1.15.2,>=1.8.2' nose-timer 'requests<2.19.0,>=2.18.4' h5py==2.8.0rc1 scipy==1.0.1 boto3
-pip3 install nose cpplint==1.3.0 pylint==2.1.1 'numpy<=1.15.2,>=1.8.2' nose-timer 'requests<2.19.0,>=2.18.4' h5py==2.8.0rc1 scipy==1.0.1 boto3
 ```
 
+Step 1b (Optional) Create or activate a [virtualenv](https://virtualenv.pypa.io/).
+
 Step 2 Install the MXNet Python binding.
 ```bash
 cd <mxnet-root>/python
@@ -68,7 +65,7 @@ git checkout master
 git pull
 ```
 
-The best hyperparameters are documented in the [Wiki](https://gitlab.hpi.de/joseph.bethge/bmxnet/wikis/hyperparameters).
+Examples for hyperparameters are documented in the [Wiki](https://github.com/hpi-xnor/BMXNet-v2/wikis/hyperparameters).
 
 ## Tests
 
@@ -92,36 +89,26 @@ We added binary versions of the following layers of the gluon API:
 
 ## Overview of Changes
 
-We added three functions `det_sign` ([ada4ea1d](https://gitlab.hpi.de/joseph.bethge/bmxnet/commit/ada4ea1d4418cfdd6cbc6d0159e1a716cb01cd85)), `round_ste` ([044f81f0](https://gitlab.hpi.de/joseph.bethge/bmxnet/commit/044f81f028887b9842070df28b28de394bd07516)) and `contrib.gradcancel` to MXNet (see [src/operator/contrib/gradient_cancel[-inl.h|.cc|.cu]](src/operator/contrib)).
+We 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)).
 
 The rest of our code resides in the following folders/files:
-- Examples are in a submodule in [example/bmxnet-examples](https://gitlab.hpi.de/joseph.bethge/bmxnet-examples)
+- Examples are in a submodule in [example/bmxnet-examples](https://github.com/hpi-xnor/BMXNet-v2-examples)
 - Tests are in [tests/python/unittest/test_binary.py](tests/python/unittest/test_binary.py)
 - Layers are in [python/mxnet/gluon/nn/binary_layers.py](python/mxnet/gluon/nn/binary_layers.py)
 
+For more details see the [Changelog](CHANGELOG.md).
+
 ### Citing BMXNet
 
-Please cite BMXNet in your publications if it helps your research work:
+Please cite our paper about BMXNet v2 in your publications if it helps your research work:
 
 ```text
-@inproceedings{bmxnet,
- author = {Yang, Haojin and Fritzsche, Martin and Bartz, Christian and Meinel, Christoph},
- title = {BMXNet: An Open-Source Binary Neural Network Implementation Based on MXNet},
- booktitle = {Proceedings of the 2017 ACM on Multimedia Conference},
- series = {MM '17},
- year = {2017},
- isbn = {978-1-4503-4906-2},
- location = {Mountain View, California, USA},
- pages = {1209--1212},
- numpages = {4},
- url = {http://doi.acm.org/10.1145/3123266.3129393},
- doi = {10.1145/3123266.3129393},
- acmid = {3129393},
- publisher = {ACM},
- address = {New York, NY, USA},
- keywords = {binary neural networks, computer vision, machine learning, open source},
-} 
-
+@article{bmxnetv2,
+  title={...},
+  author={...},
+  journal={...},
+  year={...}
+}
 ```
 
 ### References