# Quantizers
[](https://badge.fury.io/py/quantizers)
[](LICENSE)
[](https://github.com/calad0i/quantizers/actions/workflows/python-test.yml)
[](https://app.codecov.io/gh/calad0i/quantizers)
Hardware-oriented numerical quantizers for deep learning models, implemented in Keras v3 and NumPy. Provides bit-accurate precision matching with Vivado/Vitis HLS implementations.
## Features
- Bit-accurate to the HLS implementation up to 32/64-bit floating point precision
- Support for fixed-point and minifloat number formats
- Differentiable Keras v3 implementations with gradients on inputs
- With surrogate gradients for bit-width optimization as described in *[Gradient-based Automatic Mixed Precision Quantization for Neural Networks On-Chip](https://arxiv.org/abs/2405.00645)*
- Supports stochastic rounding for training
## Supported Quantizers
### Fixed-Point Quantizer
Parameters:
- `k` (keep_negative): Enable negative numbers
- `i` (integer_bits): Number of bits before decimal point (excludes sign bit)
- `f` (fractional_bits): Number of bits after decimal point
- For C++: `W = k + i + f`, `I = k + i`, `S = k`
Supported modes:
- Rounding: `TRN`, `RND`, `RND_CONV`, `TRN_ZERO`, `RND_ZERO`, `RND_MIN_INF`, `RND_INF`
- `S_RND` and `S_RND_CONV` for stochastic rounding; Not available in NumPy implementation as it is for training only
- Overflow: `WRAP`, `SAT`, `SAT_SYM`, `WRAP_SM`
Limitations:
- `WRAP_SM` only works with `RND` or `RND_CONV` rounding
- `WRAP*` modes don't provide surrogate gradients for integer bits
- Saturation bit forced to zero for `WRAP` and `WRAP_SM`
### Minifloat Quantizer
Parameters:
- `m` (mantissa_bits): Mantissa width
- `e` (exponent_bits): Exponent width
- `e0` (exponent_zero): Exponent bias (default: 0)
- Range: `[-2^(e-1) + e0, 2^(e-1) - 1 + e0]`
Features:
- Supports subnormal numbers
- Uses `RND_CONV` rounding and `SAT` overflow
- HLS-synthesizable implementation in `test/cpp_source/ap_types/ap_float.h`
### Simplified Quantizers
- **Binary**: Maps to {-1,1} with 0 to -1. (preliminary implementation)
- **Ternary**: Shorthand for fixed-point `fixed<2, 1, RND_CONV, SAT_SYM>`
## Installation
**requires python>=3.10**
```bash
pip install quantizers
```
`keras>=3.0` and at least one compatible backend (`pytorch`, `jax`, or `tensorflow`) is required for training.
## Usage
### Stateless Quantizers
```python
from quantizers import (
float_quantize(_np), # add _np for NumPy implementation
get_fixed_quantizer(_np),
binary_quantize(_np),
ternary_quantize(_np),
)
# Fixed-point quantizer
fixed_quantizer = get_fixed_quantizer(round_mode, overflow_mode)
fixedp_qtensor = fixed_quantizer(
x,
integer_bits,
fractional_bits,
keep_negative,
training, # For stochastic rounding, and WRAP does not happen during training
seed, # For stochastic rounding only
)
# Minifloat quantizer
floatp_qtensor = float_quantize(x, mantissa_bits, exponent_bits, exponent_zero)
# Simplified quantizers
binary_qtensor = binary_quantize(x)
ternary_qtensor = ternary_quantize(x)
```
### Stateful Quantizers
```python
# Can be used for, but not intended for training
fixed_q = FixedQ(
width,
integer_bits, # including the sign bit)
keep_negative,
fixed_round_mode, # No stochastic rounding
fixed_overflow_mode
)
quantized = fixed_q(x)
mfloat_q = MinifloatQ(mantissa_bits, exponent_bits, exponent_zero)
quantized = mfloat_q(x)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "quantizers",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "quantization",
"author": null,
"author_email": "Chang Sun <chsun@cern.ch>",
"download_url": "https://files.pythonhosted.org/packages/33/56/ce9e7462a0b168e407b985b579c55efd554bb24a64caf205bd61774e864e/quantizers-1.1.0.tar.gz",
"platform": null,
"description": "# Quantizers\n[](https://badge.fury.io/py/quantizers)\n[](LICENSE)\n[](https://github.com/calad0i/quantizers/actions/workflows/python-test.yml)\n[](https://app.codecov.io/gh/calad0i/quantizers)\n\n\nHardware-oriented numerical quantizers for deep learning models, implemented in Keras v3 and NumPy. Provides bit-accurate precision matching with Vivado/Vitis HLS implementations.\n\n## Features\n\n- Bit-accurate to the HLS implementation up to 32/64-bit floating point precision\n- Support for fixed-point and minifloat number formats\n- Differentiable Keras v3 implementations with gradients on inputs\n - With surrogate gradients for bit-width optimization as described in *[Gradient-based Automatic Mixed Precision Quantization for Neural Networks On-Chip](https://arxiv.org/abs/2405.00645)*\n- Supports stochastic rounding for training\n\n## Supported Quantizers\n\n### Fixed-Point Quantizer\n\nParameters:\n- `k` (keep_negative): Enable negative numbers\n- `i` (integer_bits): Number of bits before decimal point (excludes sign bit)\n- `f` (fractional_bits): Number of bits after decimal point\n- For C++: `W = k + i + f`, `I = k + i`, `S = k`\n\nSupported modes:\n- Rounding: `TRN`, `RND`, `RND_CONV`, `TRN_ZERO`, `RND_ZERO`, `RND_MIN_INF`, `RND_INF`\n - `S_RND` and `S_RND_CONV` for stochastic rounding; Not available in NumPy implementation as it is for training only\n- Overflow: `WRAP`, `SAT`, `SAT_SYM`, `WRAP_SM`\n\nLimitations:\n- `WRAP_SM` only works with `RND` or `RND_CONV` rounding\n- `WRAP*` modes don't provide surrogate gradients for integer bits\n- Saturation bit forced to zero for `WRAP` and `WRAP_SM`\n\n### Minifloat Quantizer\n\nParameters:\n- `m` (mantissa_bits): Mantissa width\n- `e` (exponent_bits): Exponent width\n- `e0` (exponent_zero): Exponent bias (default: 0)\n- Range: `[-2^(e-1) + e0, 2^(e-1) - 1 + e0]`\n\nFeatures:\n- Supports subnormal numbers\n- Uses `RND_CONV` rounding and `SAT` overflow\n- HLS-synthesizable implementation in `test/cpp_source/ap_types/ap_float.h`\n\n### Simplified Quantizers\n\n- **Binary**: Maps to {-1,1} with 0 to -1. (preliminary implementation)\n- **Ternary**: Shorthand for fixed-point `fixed<2, 1, RND_CONV, SAT_SYM>`\n\n\n## Installation\n\n**requires python>=3.10**\n\n```bash\npip install quantizers\n```\n`keras>=3.0` and at least one compatible backend (`pytorch`, `jax`, or `tensorflow`) is required for training.\n\n## Usage\n\n### Stateless Quantizers\n```python\nfrom quantizers import (\n float_quantize(_np), # add _np for NumPy implementation\n get_fixed_quantizer(_np),\n binary_quantize(_np),\n ternary_quantize(_np),\n)\n\n# Fixed-point quantizer\nfixed_quantizer = get_fixed_quantizer(round_mode, overflow_mode)\nfixedp_qtensor = fixed_quantizer(\n x,\n integer_bits,\n fractional_bits,\n keep_negative,\n training, # For stochastic rounding, and WRAP does not happen during training\n seed, # For stochastic rounding only\n)\n\n# Minifloat quantizer\nfloatp_qtensor = float_quantize(x, mantissa_bits, exponent_bits, exponent_zero)\n\n# Simplified quantizers\nbinary_qtensor = binary_quantize(x)\nternary_qtensor = ternary_quantize(x)\n```\n\n### Stateful Quantizers\n```python\n# Can be used for, but not intended for training\nfixed_q = FixedQ(\n width,\n integer_bits, # including the sign bit)\n keep_negative,\n fixed_round_mode, # No stochastic rounding\n fixed_overflow_mode\n)\nquantized = fixed_q(x)\n\nmfloat_q = MinifloatQ(mantissa_bits, exponent_bits, exponent_zero)\nquantized = mfloat_q(x)\n```\n",
"bugtrack_url": null,
"license": "GNU Lesser General Public License v3 (LGPLv3)",
"summary": null,
"version": "1.1.0",
"project_urls": {
"repository": "https://github.com/calad0i/quantizers"
},
"split_keywords": [
"quantization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "83206d81e2262dab842edcce77d434e310938356bd449ed3a41532ce05ce3960",
"md5": "d18c3f5b304b871ba8b950ef58ac4be1",
"sha256": "d633104d6a41bed78f2cbfa65af60525eae81ec1291a3f936ff810a3d7e80428"
},
"downloads": -1,
"filename": "quantizers-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d18c3f5b304b871ba8b950ef58ac4be1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16037,
"upload_time": "2024-12-09T23:12:01",
"upload_time_iso_8601": "2024-12-09T23:12:01.231376Z",
"url": "https://files.pythonhosted.org/packages/83/20/6d81e2262dab842edcce77d434e310938356bd449ed3a41532ce05ce3960/quantizers-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3356ce9e7462a0b168e407b985b579c55efd554bb24a64caf205bd61774e864e",
"md5": "af76c0d749371f53c01e43be5cdff5fa",
"sha256": "fa8ab0ef58bf7d1c41b4c04e18a3405df43968bbb52aef749284ee9934f7cdf6"
},
"downloads": -1,
"filename": "quantizers-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "af76c0d749371f53c01e43be5cdff5fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 118093,
"upload_time": "2024-12-09T23:12:02",
"upload_time_iso_8601": "2024-12-09T23:12:02.274966Z",
"url": "https://files.pythonhosted.org/packages/33/56/ce9e7462a0b168e407b985b579c55efd554bb24a64caf205bd61774e864e/quantizers-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-09 23:12:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "calad0i",
"github_project": "quantizers",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "quantizers"
}
JSON
