quantize-py 0.3.2__cp314-cp314t-win_amd64.whl

quantize/__init__.py

@@ -0,0 +1,41 @@
+"""Python bindings for quantize."""
+
+from quantize._native import (
+    InvalidBitsError,
+    InvalidBlockError,
+    InvalidToleranceError,
+    LengthMismatchError,
+    NotAMatrixError,
+    QuantizeError,
+    Quantized,
+    Scale,
+    ScaleOutOfRangeError,
+    Scheme,
+    ShapeMismatchError,
+    ToleranceTooTightError,
+    __version__,
+)
+
+from . import adaptive, asymmetric, learned, symmetric
+from .symmetric import quantize, quantize_tensor
+
+__all__ = [
+    "Scale",
+    "Scheme",
+    "Quantized",
+    "QuantizeError",
+    "InvalidBitsError",
+    "InvalidBlockError",
+    "InvalidToleranceError",
+    "ToleranceTooTightError",
+    "ScaleOutOfRangeError",
+    "LengthMismatchError",
+    "ShapeMismatchError",
+    "NotAMatrixError",
+    "quantize",
+    "quantize_tensor",
+    "symmetric",
+    "asymmetric",
+    "adaptive",
+    "learned",
+]

quantize/adaptive.py

@@ -0,0 +1,3 @@
+"""Adaptive quantization."""
+
+from quantize._native import adaptive_quantize as quantize

quantize/asymmetric.py

@@ -0,0 +1,4 @@
+"""Asymmetric quantization."""
+
+from quantize._native import asymmetric_quantize as quantize
+from quantize._native import asymmetric_quantize_tensor as quantize_tensor

quantize/learned.py

@@ -0,0 +1,3 @@
+"""Learned quantization helpers."""
+
+from quantize._native import alternate, fit_scale_and_zero_point, refine

quantize/symmetric.py

@@ -0,0 +1,3 @@
+"""Symmetric quantization."""
+
+from quantize._native import quantize, quantize_tensor

quantize_py-0.3.2.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: quantize-py
+Version: 0.3.2
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: numpy>=1.26
+License-File: LICENSE
+Summary: Python bindings for the quantize crate.
+Keywords: quantization,machine-learning,numpy
+Author: Akshey Deokule
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://github.com/aksheyd/quantize/tree/main/python
+Project-URL: Homepage, https://github.com/aksheyd/quantize
+Project-URL: Repository, https://github.com/aksheyd/quantize
+
+# quantize-py
+
+python bindings for [quantize](https://github.com/aksheyd/quantize), a simple, fast quantization library written in rust. quantization stores numbers in fewer bits, trading a little accuracy for a lot less memory.
+
+```
+pip install quantize-py
+```
+
+requires python 3.12 or newer, or 3.14 or newer for free-threaded python. numpy is installed with it. where no wheel fits, like alpine linux, pip builds it from source, which needs rust 1.88 or newer.
+
+```python
+from quantize import Scale, quantize
+
+weights = [0.42, -0.10, 0.70, -0.50]
+
+q = quantize(weights, bits=8, block=32, scale=Scale.F16)
+back = q.dequantize()  # [0.421, -0.098, 0.700, -0.498]
+dot = q.dot(weights)  # 0.926
+```
+
+`bits` is the width of each code, from 2 to 16. `block` is how many values share one scale, and `scale` is how that scale is stored: `Scale.F32` (the default), `Scale.F16`, or `Scale.BF16`. values can be a list, a numpy array, or anything else `np.asarray` reads, like a pytorch tensor. a 2-d array keeps its shape, so `q.dequantize()` gives back a matrix and `q.matmul(x)` computes `x @ W.T`, like a linear layer. both can write into a float32 numpy array or pytorch tensor you pass, like `q.matmul(x, out=y)`, so a loop can reuse it. `q.shape` gives its rows and columns, and `len(q)` the number of values, as in rust.
+
+the scales count toward the size: 4-bit codes with one f16 scale per 32 values cost 4.5 bits per value, or 5 with the default f32 scale. `q.bits_per_element` reports it. above about 10 bits, use f32 scales with `asymmetric.quantize`, since f16 and bf16 zero-points cap its accuracy.
+
+the other schemes return the same `Quantized` type:
+
+- `asymmetric.quantize(weights, bits=8, block=32)` adds a zero-point per block, for values that aren't centered on zero
+- `adaptive.quantize(weights, tolerance=0.1 * weights.std())` gives each block the fewest bits, from 2 to 8, that round every weight within `tolerance`, in the weights' own units. a tenth of their standard deviation gives about 5 bits a block. for a list, use `np.std(weights)`
+- `learned.refine(q, weights)` refits each block's scale, and its zero-point if it has one, to lower the mean squared error. it changes `q` in place, so call `q.copy()` first to keep the original. it lets other threads run while it works, so threads can refit several layers at once
+- `learned.alternate(q, weights)` refits too, then rounds each value to the nearest code on its block's new line, and repeats until no code moves. it also changes `q` in place and lets other threads run. both can raise the worst error past an adaptive tensor's tolerance, and lowering the error of the weights doesn't always lower the error of a model's outputs, so check those too
+- `Scheme.Q4_32.quantize(weights)` picks a scheme at run time, and `Scheme("symmetric(bits=4)")` reads one from text, like a config value, which `str(scheme)` writes
+
+a block with outliers can need more than 8 bits, which raises `ToleranceTooTightError`. retrying with its `smallest_tolerance` works, but loosens every block, not just that one:
+
+```python
+import numpy as np
+from quantize import ToleranceTooTightError, adaptive
+
+weights = np.array(weights)  # a list has no .std(). skip this line for a pytorch tensor
+try:
+    q = adaptive.quantize(weights, tolerance=0.1 * weights.std())
+except ToleranceTooTightError as error:
+    q = adaptive.quantize(weights, tolerance=error.smallest_tolerance)
+```
+
+quantized values can be pickled, and compared with `==`. `q.to_bytes()` saves one as bytes, in the same format as the rust crate, and `Quantized.from_bytes(data)` loads it back. to keep it in an `np.savez` or safetensors file, store `np.frombuffer(q.to_bytes(), np.uint8)`.
+
+to save its parts as plain arrays instead, like with `np.savez`, pass them back by name to `Quantized.from_parts`. leave out the one that's `None`: `bits` for an adaptive tensor, or `block_bits` for the others:
+
+```python
+parts = dict(kind=q.kind, shape=q.shape, block=q.block, bits=q.bits, block_bits=q.block_bits,
+             codes=q.codes, scales=q.scales, zero_points=q.zero_points, scale=q.scale.name)
+np.savez("layer.npz", **{name: part for name, part in parts.items() if part is not None})
+q = Quantized.from_parts(**np.load("layer.npz"))
+```
+
+to keep quantized values in a `torch.save` checkpoint, store `torch.frombuffer(bytearray(q.to_bytes()), dtype=torch.uint8)`, and load each back with `Quantized(t)`. the checkpoint is then as small as the bytes, and `torch.load` reads it without `add_safe_globals`. pickling `q` itself makes the checkpoint about 1.5 times larger, since `torch.save` stores bytes as text, and needs `torch.serialization.add_safe_globals([Quantized])` before `torch.load`.
+
+`q.matmul` runs on one core, but it lets other threads run while it multiplies, so threads can share out a batch. on an 8-core intel xeon, this multiplies a batch of 512 by a 4-bit 1536 × 576 matrix in 6 ms instead of 33 ms, with the same result, bit for bit:
+
+```python
+import os
+from concurrent.futures import ThreadPoolExecutor
+
+pool = ThreadPoolExecutor()  # make it once, and reuse it for every layer
+
+def linear(q, x):  # x has shape (batch, columns)
+    # a piece per core, or pieces of 64 rows for a big batch, which stay in a core's cache
+    pieces = np.array_split(x, max(os.cpu_count(), len(x) // 64))
+    return np.concatenate(list(pool.map(q.matmul, pieces)))
+
+out = linear(q, x)
+```
+
+with a gil, while another thread keeps running python, each piece can wait up to `sys.getswitchinterval()`, 5 ms by default, to get the gil back, so splitting pays off only while your other threads are idle or in native code, or on free-threaded python. `dequantize`, `dot`, and `matmul` on 65,536 values or fewer, like one vector times a 256 × 256 matrix, keep the gil, so they don't wait. quantizing and refitting keep it only up to 4,096 values, so threads can quantize a model's layers in parallel.
+
+each value decodes as `code * scale`, or `(code - zero_point) * scale` with zero-points, using the scale and zero-point of its block. codes are signed and `bits` wide, and `q.codes` packs them low bits first. scales can be negative, since a symmetric block puts its value farthest from zero on the most negative code. `help(Quantized)` has the details.
+
+to build and test from a clone of the repo, with rust 1.88 or newer and [just](https://github.com/casey/just):
+
+```
+just setup
+just python
+```
+
+on debian or ubuntu, run `sudo apt install python3-venv` first.
+

quantize_py-0.3.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+quantize/__init__.py,sha256=KlP4rPPdqK2gOUWvc7vUvigj7nAeg63fLVvfk5D_LMA,883
+quantize/_native.cp314t-win_amd64.pyd,sha256=5qB4daeLSNzB4hrhm3XRyXoXe20izArFMIBirUaJ_KA,771584
+quantize/adaptive.py,sha256=B_VjnT5qedjJPOgTBNb21PG0py6gv1CmEwJzQ8ZR9R4,92
+quantize/asymmetric.py,sha256=Wv25ZTOXFiSEwgiwuQwgtrv5Zz3nImDNBlt3YM5LUFw,172
+quantize/learned.py,sha256=9CYixc3Beo6_w3so-j4g-FexdO6oKuBQbisX-osJQ7I,113
+quantize/symmetric.py,sha256=qioEFBtQtaSHJSWzfL-0ZWGETnhazUvuCh-JLPK8qHs,89
+quantize_py-0.3.2.dist-info/METADATA,sha256=b93PcIsSAILUu_uXo23Ub8fBmTdK4uo6pWxzfGwrLOI,7389
+quantize_py-0.3.2.dist-info/WHEEL,sha256=kZsxXhvuxY5k9M6Ytk-lN_-XjHM99LBuWSI_qRbPktY,98
+quantize_py-0.3.2.dist-info/licenses/LICENSE,sha256=4fE7Sr6YkE7fFrmdBRIK8N1sqjCdBnOuWlxxzEIWYh8,1092
+quantize_py-0.3.2.dist-info/sboms/quantize-py.cyclonedx.json,sha256=9ztFhY2nHcO6LrIt6GSjSzzjUy9O9_uDpa8HlSJYqqI,44736
+quantize_py-0.3.2.dist-info/RECORD,,

quantize_py-0.3.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: cp314-cp314t-win_amd64

quantize_py-0.3.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Akshey Deokule
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.