Some things to document

[analog-cbarber]

The documentation for the various Q* operators omits many details. Some points that should be described include:

• QActivation in 1-bit mode quantizes to the values +1/-1, but in higher-bit modes quantizes to range [0,1].

• QFullyConnected quantizes inputs according to QActivation, and quantizes weights to range [-1,1] prior to computing matrix-vector product.

• QFullyConnected in the case of 1-bit activation and weights actually returns a scaled and offset version of the matrix product so that the output values are in the range [0,#inputs]. For other bit settings it computes a regular matrix product with outputs in range [-#inputs,+#inputs].

I assume similar considerations apply to QConvolution.

[yanghaojin]

yes, this implementation is according to the 3 reference paper: "BNN-Net", "DoReFa-Net" and "XNOR-Net", so the quantization for > 1bit we follow the DoReFa-Net solution, the detailed description like value ranges of each case can be found in their paper. But for the 1-bit binarization we put some our own idea into the design of QConv and Qfc layers, for example the reason why we scale the output value from [-#inputs,+#inputs] to [0,#inputs] when both input and weights are in 1 bit. We describe those details in our paper . However I understand not every developer would like to take time to read research papers before they try out the code, it would be nice to get those insights directily by reading the documentation. We will try to optimize this in the souce code and the docu. Thanks for pointing out this.

[analog-cbarber]

I have read all three of those papers and it even so it would not be at all clear how exactly these details would manifest themselves in the API. It is always good practice to document all behavior in the API documentation - the rationale for the design can remain in the papers or in other high-level documentation. (BTW, the mainline MXNet documentation is itself overly sparse. I would not use their documentation as a model for good practice.)

[yanghaojin]

agree with u