sparsepixels 0.3.2__tar.gz → 0.3.3__tar.gz

{sparsepixels-0.3.2/sparsepixels.egg-info → sparsepixels-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sparsepixels
-Version: 0.3.2
+Version: 0.3.3
 Summary: Efficient convolution for sparse data on FPGAs
 Home-page: https://github.com/hftsoi/sparse-pixels
 Author: Ho Fung Tsoi
@@ -14,6 +14,7 @@ License-File: LICENSE
 Requires-Dist: tensorflow
 Requires-Dist: keras>=3.0
 Requires-Dist: HGQ2>=0.1.8
+Requires-Dist: quantizers<2
 Requires-Dist: matplotlib
 Dynamic: license-file
 
@@ -32,6 +33,7 @@ Dynamic: license-file
 
 # SparsePixels: Efficient convolution for sparse data on FPGAs
 
+[![Docs](https://img.shields.io/badge/docs-site-informational?color=blue&style=flat-square)](https://hftsoi.github.io/sparse-pixels)
 [![arXiv](https://img.shields.io/badge/arXiv-2512.06208-b31b1b.svg?style=flat-square)](https://arxiv.org/abs/2512.06208)
 [![PyPI - Version](https://img.shields.io/pypi/v/sparsepixels?color=orange&style=flat-square)](https://pypi.org/project/sparsepixels)
 
@@ -59,24 +61,24 @@ active_pixels_vs_threshold(x_train)
 plot_reduced_examples(x_train, n=20, threshold=0.1, n_examples=3)
 ```
 
-Build an example sparse CNN within HGQ2 quantization scopes. A custom input quantizer config with
-higher initial fractional bits (e.g., `f0=8`) prevents the lower default (`f0=2`) from aggressively zeroing out sparse signals
-in early training epochs. `InputReduce` keeps the first `n` active pixels (based on the first channel above
-`threshold`) in a row-major order.
+Build an example sparse CNN within HGQ2 quantization scopes. Set generous initial bit-widths at the
+scope level: sparse signals are small (and get diluted further by pooling), so the low HGQ2 defaults
+(4-bit weights, 2 fractional bits on activations) can quantize them, or entire low-magnitude
+kernels, to exact zeros at initialization and block training. Starting wide (e.g. `b0=8` for
+weights, `f0=8` for activations) keeps everything alive, and the EBOPS regularizer trims the
+bit-widths back down during training. `InputReduce` keeps the first `n` active pixels (based on the
+first channel above `threshold`) in a row-major order.
 By default `n` and `threshold` are trainable hyperparameters: `beta_n` controls how aggressively `n` is driven smaller for a lower hardware footprint, and `beta_maskedE` penalizes over-masking pixel intensity.
 
 ```python
 import keras
 from hgq.layers import QDense
 from hgq.config import QuantizerConfigScope, LayerConfigScope
-from hgq.quantizer.config import QuantizerConfig
 from sparsepixels.layers import InputReduce, QConv2DSparse, AveragePooling2DSparse, MaxPooling2DSparse
 
-iq_conf = QuantizerConfig(place='datalane', q_type='kif', i0=4, f0=8, overflow_mode='WRAP')
-
 with (
-    QuantizerConfigScope(place='all', default_q_type='kbi', overflow_mode='SAT_SYM'),
-    QuantizerConfigScope(place='datalane', default_q_type='kif', overflow_mode='WRAP'),
+    QuantizerConfigScope(place='all', default_q_type='kbi', overflow_mode='SAT_SYM', b0=8, i0=0),
+    QuantizerConfigScope(place='datalane', default_q_type='kif', overflow_mode='WRAP', i0=4, f0=8),
     LayerConfigScope(enable_ebops=True, enable_iq=True, beta0=1e-5),
 ):
     x_in = keras.Input(shape=(28, 28, 1), name='x_in')
@@ -91,14 +93,16 @@ with (
         name='input_reduce',
     )(x_in)
     x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
-                      activation='relu', iq_conf=iq_conf)([x, keep_mask])
+                      activation='relu')([x, keep_mask])
     x, keep_mask = AveragePooling2DSparse(2, name='pool1')([x, keep_mask])
 
     x = keras.layers.Flatten(name='flatten')(x)
-    x = QDense(10, name='dense1', activation='relu', iq_conf=iq_conf)(x)
+    x = QDense(10, name='dense1', activation='relu')(x)
     x = keras.layers.Activation('softmax', name='softmax')(x)
 
 model = keras.Model(x_in, x)
+model.compile(optimizer=keras.optimizers.Adam(1e-3),
+              loss='categorical_crossentropy', metrics=['accuracy'])
 ```
 
 Train the model with `SparseTrainingMonitor`. It records the loss breakdown, the learned
@@ -108,13 +112,11 @@ budget/threshold, the EBOPS and the masked-intensity penalty each epoch, and it
 ```python
 from sparsepixels.utils import SparseTrainingMonitor
 
-early_stop = keras.callbacks.EarlyStopping(monitor='val_accuracy', mode='max', patience=20, restore_best_weights=True)
-model.compile(
-    optimizer=keras.optimizers.Adam(1e-3),
-    loss='categorical_crossentropy', metrics=['accuracy'],
-)
+early_stop = keras.callbacks.EarlyStopping(monitor='val_accuracy', mode='max',
+                                           patience=20, restore_best_weights=True)
 history = model.fit(x_train, y_train, validation_data=(x_val, y_val),
-                    epochs=100, batch_size=128, callbacks=[early_stop, SparseTrainingMonitor()])
+                    epochs=100, batch_size=128,
+                    callbacks=[early_stop, SparseTrainingMonitor()])
 ```
 
 After training, plot the diagnostics from the monitoring tool. The final pixel budget and threshold values are stored in `InputReduce`: `layer.n_max_pixels` and `layer.threshold` (hls4ml converter will auto-parse these from the model).
@@ -132,10 +134,10 @@ print(f"n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}")
 
 ## Converting a trained model to HLS with hls4ml
 
-> **Note:** A [PR](https://github.com/fastmachinelearning/hls4ml/pull/1468) adding `sparsepixels` support to the official [hls4ml](https://github.com/fastmachinelearning/hls4ml) repo has been submitted but is not yet merged. In the meantime you can install hls4ml from the PR branch on this fork to use the converter:
+> **Note:** `sparsepixels` support is part of the official [hls4ml](https://github.com/fastmachinelearning/hls4ml) repo ([PR #1468](https://github.com/fastmachinelearning/hls4ml/pull/1468), merged). It is not in a tagged release yet, so install hls4ml from the main branch:
 >
 > ```bash
-> pip install "git+https://github.com/hftsoi/hls4ml.git@sparsepixels"
+> pip install "git+https://github.com/fastmachinelearning/hls4ml.git"
 > ```
 
 Once installed, pull a config from the trained model, optionally set the per-layer parallelization
@@ -174,7 +176,7 @@ y_hls = hls_model.predict(x_test)
 
 ## Documentation
 
-Coming soon!
+See [here](https://hftsoi.github.io/sparse-pixels/) for documentation with walk-through guidance.
 
 ## Citation
 
@@ -183,11 +185,15 @@ If you find this useful in your research, please consider citing:
 ```
 @article{Tsoi:2025nvg,
     author = "Tsoi, Ho Fung and Rankin, Dylan and Loncar, Vladimir and Harris, Philip",
-    title = "{SparsePixels: Efficient Convolution for Sparse Data on FPGAs}",
+    title = "{SparsePixels: efficient convolution for sparse data on FPGAs}",
     eprint = "2512.06208",
     archivePrefix = "arXiv",
     primaryClass = "cs.AR",
-    month = "12",
-    year = "2025"
+    doi = "10.1088/2632-2153/ae9fb5",
+    journal = "Mach. Learn. Sci. Tech.",
+    volume = "7",
+    number = "5",
+    pages = "055025",
+    year = "2026"
 }
 ```

{sparsepixels-0.3.2 → sparsepixels-0.3.3}/README.md

@@ -13,6 +13,7 @@
 
 # SparsePixels: Efficient convolution for sparse data on FPGAs
 
+[![Docs](https://img.shields.io/badge/docs-site-informational?color=blue&style=flat-square)](https://hftsoi.github.io/sparse-pixels)
 [![arXiv](https://img.shields.io/badge/arXiv-2512.06208-b31b1b.svg?style=flat-square)](https://arxiv.org/abs/2512.06208)
 [![PyPI - Version](https://img.shields.io/pypi/v/sparsepixels?color=orange&style=flat-square)](https://pypi.org/project/sparsepixels)
 
@@ -40,24 +41,24 @@ active_pixels_vs_threshold(x_train)
 plot_reduced_examples(x_train, n=20, threshold=0.1, n_examples=3)
 ```
 
-Build an example sparse CNN within HGQ2 quantization scopes. A custom input quantizer config with
-higher initial fractional bits (e.g., `f0=8`) prevents the lower default (`f0=2`) from aggressively zeroing out sparse signals
-in early training epochs. `InputReduce` keeps the first `n` active pixels (based on the first channel above
-`threshold`) in a row-major order.
+Build an example sparse CNN within HGQ2 quantization scopes. Set generous initial bit-widths at the
+scope level: sparse signals are small (and get diluted further by pooling), so the low HGQ2 defaults
+(4-bit weights, 2 fractional bits on activations) can quantize them, or entire low-magnitude
+kernels, to exact zeros at initialization and block training. Starting wide (e.g. `b0=8` for
+weights, `f0=8` for activations) keeps everything alive, and the EBOPS regularizer trims the
+bit-widths back down during training. `InputReduce` keeps the first `n` active pixels (based on the
+first channel above `threshold`) in a row-major order.
 By default `n` and `threshold` are trainable hyperparameters: `beta_n` controls how aggressively `n` is driven smaller for a lower hardware footprint, and `beta_maskedE` penalizes over-masking pixel intensity.
 
 ```python
 import keras
 from hgq.layers import QDense
 from hgq.config import QuantizerConfigScope, LayerConfigScope
-from hgq.quantizer.config import QuantizerConfig
 from sparsepixels.layers import InputReduce, QConv2DSparse, AveragePooling2DSparse, MaxPooling2DSparse
 
-iq_conf = QuantizerConfig(place='datalane', q_type='kif', i0=4, f0=8, overflow_mode='WRAP')
-
 with (
-    QuantizerConfigScope(place='all', default_q_type='kbi', overflow_mode='SAT_SYM'),
-    QuantizerConfigScope(place='datalane', default_q_type='kif', overflow_mode='WRAP'),
+    QuantizerConfigScope(place='all', default_q_type='kbi', overflow_mode='SAT_SYM', b0=8, i0=0),
+    QuantizerConfigScope(place='datalane', default_q_type='kif', overflow_mode='WRAP', i0=4, f0=8),
     LayerConfigScope(enable_ebops=True, enable_iq=True, beta0=1e-5),
 ):
     x_in = keras.Input(shape=(28, 28, 1), name='x_in')
@@ -72,14 +73,16 @@ with (
         name='input_reduce',
     )(x_in)
     x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
-                      activation='relu', iq_conf=iq_conf)([x, keep_mask])
+                      activation='relu')([x, keep_mask])
     x, keep_mask = AveragePooling2DSparse(2, name='pool1')([x, keep_mask])
 
     x = keras.layers.Flatten(name='flatten')(x)
-    x = QDense(10, name='dense1', activation='relu', iq_conf=iq_conf)(x)
+    x = QDense(10, name='dense1', activation='relu')(x)
     x = keras.layers.Activation('softmax', name='softmax')(x)
 
 model = keras.Model(x_in, x)
+model.compile(optimizer=keras.optimizers.Adam(1e-3),
+              loss='categorical_crossentropy', metrics=['accuracy'])
 ```
 
 Train the model with `SparseTrainingMonitor`. It records the loss breakdown, the learned
@@ -89,13 +92,11 @@ budget/threshold, the EBOPS and the masked-intensity penalty each epoch, and it
 ```python
 from sparsepixels.utils import SparseTrainingMonitor
 
-early_stop = keras.callbacks.EarlyStopping(monitor='val_accuracy', mode='max', patience=20, restore_best_weights=True)
-model.compile(
-    optimizer=keras.optimizers.Adam(1e-3),
-    loss='categorical_crossentropy', metrics=['accuracy'],
-)
+early_stop = keras.callbacks.EarlyStopping(monitor='val_accuracy', mode='max',
+                                           patience=20, restore_best_weights=True)
 history = model.fit(x_train, y_train, validation_data=(x_val, y_val),
-                    epochs=100, batch_size=128, callbacks=[early_stop, SparseTrainingMonitor()])
+                    epochs=100, batch_size=128,
+                    callbacks=[early_stop, SparseTrainingMonitor()])
 ```
 
 After training, plot the diagnostics from the monitoring tool. The final pixel budget and threshold values are stored in `InputReduce`: `layer.n_max_pixels` and `layer.threshold` (hls4ml converter will auto-parse these from the model).
@@ -113,10 +114,10 @@ print(f"n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}")
 
 ## Converting a trained model to HLS with hls4ml
 
-> **Note:** A [PR](https://github.com/fastmachinelearning/hls4ml/pull/1468) adding `sparsepixels` support to the official [hls4ml](https://github.com/fastmachinelearning/hls4ml) repo has been submitted but is not yet merged. In the meantime you can install hls4ml from the PR branch on this fork to use the converter:
+> **Note:** `sparsepixels` support is part of the official [hls4ml](https://github.com/fastmachinelearning/hls4ml) repo ([PR #1468](https://github.com/fastmachinelearning/hls4ml/pull/1468), merged). It is not in a tagged release yet, so install hls4ml from the main branch:
 >
 > ```bash
-> pip install "git+https://github.com/hftsoi/hls4ml.git@sparsepixels"
+> pip install "git+https://github.com/fastmachinelearning/hls4ml.git"
 > ```
 
 Once installed, pull a config from the trained model, optionally set the per-layer parallelization
@@ -155,7 +156,7 @@ y_hls = hls_model.predict(x_test)
 
 ## Documentation
 
-Coming soon!
+See [here](https://hftsoi.github.io/sparse-pixels/) for documentation with walk-through guidance.
 
 ## Citation
 
@@ -164,11 +165,15 @@ If you find this useful in your research, please consider citing:
 ```
 @article{Tsoi:2025nvg,
     author = "Tsoi, Ho Fung and Rankin, Dylan and Loncar, Vladimir and Harris, Philip",
-    title = "{SparsePixels: Efficient Convolution for Sparse Data on FPGAs}",
+    title = "{SparsePixels: efficient convolution for sparse data on FPGAs}",
     eprint = "2512.06208",
     archivePrefix = "arXiv",
     primaryClass = "cs.AR",
-    month = "12",
-    year = "2025"
+    doi = "10.1088/2632-2153/ae9fb5",
+    journal = "Mach. Learn. Sci. Tech.",
+    volume = "7",
+    number = "5",
+    pages = "055025",
+    year = "2026"
 }
 ```

{sparsepixels-0.3.2 → sparsepixels-0.3.3}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = sparsepixels
-version = 0.3.2
+version = 0.3.3
 description = Efficient convolution for sparse data on FPGAs
 author = Ho Fung Tsoi
 author_email = ho.fung.tsoi@cern.ch
@@ -20,6 +20,7 @@ install_requires =
 	tensorflow
 	keras>=3.0
 	HGQ2>=0.1.8
+	quantizers<2
 	matplotlib
 include_package_data = True
 

{sparsepixels-0.3.2 → sparsepixels-0.3.3}/sparsepixels/utils.py

@@ -9,6 +9,9 @@ set_sparse_ebops_factor corrects each sparse conv's EBOPS for the fact that it o
 active pixels, so the monitored EBOPS and the EBOPS regularizer reflect the real sparse cost.
 """
 
+import os
+
+import keras
 import matplotlib.pyplot as plt
 import numpy as np
 from keras import ops
@@ -214,7 +217,7 @@ class SparseTrainingMonitor(Callback):
             logs["loss_task"] = logs["loss"] - reg_ebops - reg_n - reg_maskedE
 
 
-def plot_history(history, early_stopping=None, figsize=None, ncols=3):
+def plot_history(history, early_stopping=None, figsize=None, ncols=3, save_path=None):
     """Plot the training history recorded by SparseTrainingMonitor in one figure.
 
     Shows the total loss and each compiled metric (train, and validation when present), the loss
@@ -308,10 +311,14 @@ def plot_history(history, early_stopping=None, figsize=None, ncols=3):
     for ax in axes[n:]:
         ax.axis("off")
     fig.tight_layout()
+    if save_path is not None:
+        fig.savefig(save_path, dpi=150, bbox_inches="tight")
     plt.show()
 
 
-def active_pixels_vs_threshold(x, thresholds=None, channel=0, percentiles=(25, 50, 75), plot=True, ax=None):
+def active_pixels_vs_threshold(
+    x, thresholds=None, channel=0, percentiles=(25, 50, 75), plot=True, ax=None, save_path=None
+):
     """Study how the number of active pixels per image changes with the threshold.
 
     For each candidate threshold, counts the active pixels (x[..., channel] > threshold) in every
@@ -349,7 +356,7 @@ def active_pixels_vs_threshold(x, thresholds=None, channel=0, percentiles=(25, 5
     if plot:
         owns_fig = ax is None
         if ax is None:
-            _, ax = plt.subplots(figsize=(7, 4.5))
+            fig, ax = plt.subplots(figsize=(7, 4.5))
         ax.plot(thresholds, stats["mean"], color="black", lw=2, label="mean")
         ax.plot(thresholds, stats["min"], "--", alpha=0.7, label="min")
         for p in percentiles:
@@ -361,11 +368,15 @@ def active_pixels_vs_threshold(x, thresholds=None, channel=0, percentiles=(25, 5
         ax.legend(loc="best")
         ax.grid(alpha=0.2)
         if owns_fig:
+            if save_path is not None:
+                fig.savefig(save_path, dpi=150, bbox_inches="tight")
             plt.show()
     return stats
 
 
-def plot_reduced_examples(x, n, threshold, indices=None, n_examples=5, channel=0, figsize=None):
+def plot_reduced_examples(
+    x, n, threshold, indices=None, n_examples=5, channel=0, figsize=None, aspect=None, cmap="viridis", save_path=None
+):
     """Show what InputReduce keeps for a given budget n and threshold on a few images.
 
     Each row shows the original image and, at the same intensity scale, the pixels that are kept (the
@@ -380,12 +391,19 @@ def plot_reduced_examples(x, n, threshold, indices=None, n_examples=5, channel=0
         n_examples: number of images to show when indices is not given.
         channel: channel used to decide activity (default 0).
         figsize: optional (width, height).
+        aspect: imshow aspect: None keeps the natural pixel ratio, "auto" stretches each image to
+            fill its panel (useful for very wide images), or a float scales the pixel height.
+        cmap: colormap for the active pixels; empty pixels (at or below 0) are drawn white. For
+            binary images a reversed map like "viridis_r" makes the hits dark on white.
     """
     x = np.asarray(x)
     if indices is None:
         indices = np.arange(min(n_examples, len(x)))
     indices = list(indices)
 
+    cmap_obj = plt.get_cmap(cmap).copy()
+    cmap_obj.set_bad("white")
+
     fig, axes = plt.subplots(len(indices), 2, figsize=figsize or (6, 3 * len(indices)), squeeze=False)
     for row, idx in enumerate(indices):
         s = x[idx][..., channel]
@@ -395,16 +413,135 @@ def plot_reduced_examples(x, n, threshold, indices=None, n_examples=5, channel=0
         n_active, n_kept = int(active.sum()), int(keep.sum())
         vmax = float(s.max()) or 1.0
 
-        axes[row][0].imshow(s, cmap="gray", vmin=0, vmax=vmax)
-        axes[row][0].set_title(f"image #{idx}")
-        axes[row][1].imshow(np.where(keep, s, 0.0), cmap="gray", vmin=0, vmax=vmax)
-        axes[row][1].set_title(f"kept (n={n}, thr={threshold:g}): {n_kept} of {n_active} active")
-        for a in axes[row]:
-            a.axis("off")
+        panels = [
+            (s, f"image #{idx}"),
+            (np.where(keep, s, 0.0), f"kept (n={n}, thr={threshold:g}): {n_kept} of {n_active} active"),
+        ]
+        for a, (img, title) in zip(axes[row], panels):
+            a.imshow(
+                np.ma.masked_less_equal(img, 0.0),
+                cmap=cmap_obj,
+                vmin=0,
+                vmax=vmax,
+                aspect=aspect if aspect is not None else "equal",
+                interpolation="nearest",
+            )
+            a.set_title(title)
+            a.set_xticks([])
+            a.set_yticks([])
     fig.tight_layout()
+    if save_path is not None:
+        fig.savefig(save_path, dpi=150, bbox_inches="tight")
     plt.show()
 
 
+def freeze_quantization(model, freeze_budget=True):
+    """Freeze the quantization (and optionally the pixel budget) at the current learned values.
+
+    Sets every quantizer sublayer non-trainable and zeroes the WRAP integer-part decay, so the
+    bit-width configuration stays exactly fixed afterwards; optionally also freezes the InputReduce
+    budget. Use for two-stage training: after the quantization-aware stage converges, freeze,
+    recompile with a lower learning rate, and fine-tune. The weights then adapt to the final bit
+    assignment instead of a moving one, and early stopping effectively monitors the pure task loss
+    since the frozen regularizer terms are constants.
+
+    Args:
+        model: a keras model built with the quantized (HGQ) layers.
+        freeze_budget: also set InputReduce layers non-trainable (a learnable budget n stops moving).
+
+    Returns:
+        int: the number of layers set non-trainable. Remember to call model.compile again.
+    """
+    n_frozen = 0
+    for sub in model._flatten_layers(include_self=False):
+        cls = sub.__class__
+        is_quantizer = "quantizer" in cls.__module__.lower() or "Quantizer" in cls.__name__
+        if is_quantizer or (freeze_budget and isinstance(sub, InputReduce)):
+            sub.trainable = False
+            n_frozen += 1
+    for w in model.weights:
+        if "i_decay" in w.path:
+            w.assign(np.zeros(w.shape))
+    return n_frozen
+
+
+def plot_layer_outputs(model, x, index=0, layers=None, cmap="viridis", aspect="auto", max_channels=16, save_path=None):
+    """Plot every layer's output for one input image, channel by channel.
+
+    Feeds one image through the model and draws one figure per layer, with that layer's channels
+    stacked as rows on a common intensity scale (empty pixels in white) and the active-pixel count
+    annotated per channel. Use it to spot where the sparse signals get over-compressed, e.g. a
+    pooling layer merging the few active pixels of a track into far fewer, and adjust the
+    architecture accordingly.
+
+    Args:
+        model: a functional keras model.
+        x: image array of shape (N, H, W, C) or a single image (H, W, C).
+        index: which image of x to feed.
+        layers: layer names to show; defaults to every layer with a plottable output.
+        cmap: colormap for the active values; exact zeros are drawn white.
+        aspect: imshow aspect for the feature-map panels ("auto" fills each panel, None keeps the
+            natural pixel ratio, a float scales the pixel height).
+        max_channels: cap on the number of channels drawn per layer.
+        save_path: optional path; each layer's figure is saved with the layer name appended.
+    """
+    x = np.asarray(x, dtype="float32")
+    if x.ndim == 3:
+        x = x[None]
+    xb = x[index : index + 1]
+
+    outputs = {}
+    for layer in model.layers:
+        if layer.__class__.__name__ == "InputLayer":
+            continue
+        if layers is not None and layer.name not in layers:
+            continue
+        try:
+            out = layer.output
+        except Exception:
+            continue
+        if isinstance(out, (list, tuple)):
+            out = out[0]
+        outputs[layer.name] = out
+    probe = keras.Model(model.inputs, outputs)
+    acts = probe.predict(xb, verbose=0)
+
+    cmap_obj = plt.get_cmap(cmap).copy()
+    cmap_obj.set_bad("white")
+
+    for name, act in acts.items():
+        a = np.asarray(act)[0]
+        if a.ndim == 1:
+            a = a[None, :, None]
+        elif a.ndim != 3:
+            continue
+        n_ch = min(a.shape[-1], max_channels)
+        vmin, vmax = min(0.0, float(a.min())), float(a.max()) or 1.0
+
+        fig, axes = plt.subplots(n_ch, 1, figsize=(14, 0.75 * n_ch + 0.6), squeeze=False)
+        for ch in range(n_ch):
+            img, ax = a[..., ch], axes[ch][0]
+            ax.imshow(
+                np.ma.masked_equal(img, 0.0),
+                cmap=cmap_obj,
+                vmin=vmin,
+                vmax=vmax,
+                aspect=aspect if aspect is not None else "equal",
+                interpolation="nearest",
+                origin="lower",
+            )
+            ax.set_ylabel(f"ch {ch}\n{int((img != 0).sum())} act", fontsize=7, rotation=0, ha="right", va="center")
+            ax.set_xticks([])
+            ax.set_yticks([])
+        shown = f", showing {n_ch} of {a.shape[-1]} channels" if n_ch < a.shape[-1] else ""
+        axes[0][0].set_title(f"{name}: output {tuple(np.asarray(act).shape[1:])}{shown}", loc="left", fontsize=10)
+        fig.tight_layout()
+        if save_path is not None:
+            root, ext = os.path.splitext(save_path)
+            fig.savefig(f"{root}_{name}{ext or '.png'}", dpi=150, bbox_inches="tight")
+        plt.show()
+
+
 def print_quantization(model):
     """Print the per-layer quantizer bit-widths (kernel, bias, input as mean, min, max) and EBOPS.
 
@@ -446,7 +583,7 @@ def print_quantization(model):
     print(f"{'Total eBOPs':>{len(header) - 10}}{total_ebops:>10.0f}")
 
 
-def plot_quantization(models, figsize=(14, 3)):
+def plot_quantization(models, figsize=(14, 3), save_path=None):
     """Violin plots of the per-layer kernel, bias and input bit-width distributions.
 
     Args:
@@ -456,7 +593,7 @@ def plot_quantization(models, figsize=(14, 3)):
     if not isinstance(models, (list, tuple)):
         models = [models]
     categories = [("kq", "Kernel bits"), ("bq", "Bias bits"), ("iq", "Input bits")]
-    _, axes = plt.subplots(
+    fig, axes = plt.subplots(
         len(models),
         len(categories),
         figsize=(figsize[0], figsize[1] * len(models)),
@@ -492,4 +629,6 @@ def plot_quantization(models, figsize=(14, 3)):
             pad = max(0.5, 0.08 * (hi - lo))  # show the full band with a small margin at both ends
             ax.set_xlim(lo - pad, hi + pad)
             ax.set_title(f"{model.name} - {title}")
+    if save_path is not None:
+        fig.savefig(save_path, dpi=150, bbox_inches="tight")
     plt.show()

{sparsepixels-0.3.2 → sparsepixels-0.3.3/sparsepixels.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sparsepixels
-Version: 0.3.2
+Version: 0.3.3
 Summary: Efficient convolution for sparse data on FPGAs
 Home-page: https://github.com/hftsoi/sparse-pixels
 Author: Ho Fung Tsoi
@@ -14,6 +14,7 @@ License-File: LICENSE
 Requires-Dist: tensorflow
 Requires-Dist: keras>=3.0
 Requires-Dist: HGQ2>=0.1.8
+Requires-Dist: quantizers<2
 Requires-Dist: matplotlib
 Dynamic: license-file
 
@@ -32,6 +33,7 @@ Dynamic: license-file
 
 # SparsePixels: Efficient convolution for sparse data on FPGAs
 
+[![Docs](https://img.shields.io/badge/docs-site-informational?color=blue&style=flat-square)](https://hftsoi.github.io/sparse-pixels)
 [![arXiv](https://img.shields.io/badge/arXiv-2512.06208-b31b1b.svg?style=flat-square)](https://arxiv.org/abs/2512.06208)
 [![PyPI - Version](https://img.shields.io/pypi/v/sparsepixels?color=orange&style=flat-square)](https://pypi.org/project/sparsepixels)
 
@@ -59,24 +61,24 @@ active_pixels_vs_threshold(x_train)
 plot_reduced_examples(x_train, n=20, threshold=0.1, n_examples=3)
 ```
 
-Build an example sparse CNN within HGQ2 quantization scopes. A custom input quantizer config with
-higher initial fractional bits (e.g., `f0=8`) prevents the lower default (`f0=2`) from aggressively zeroing out sparse signals
-in early training epochs. `InputReduce` keeps the first `n` active pixels (based on the first channel above
-`threshold`) in a row-major order.
+Build an example sparse CNN within HGQ2 quantization scopes. Set generous initial bit-widths at the
+scope level: sparse signals are small (and get diluted further by pooling), so the low HGQ2 defaults
+(4-bit weights, 2 fractional bits on activations) can quantize them, or entire low-magnitude
+kernels, to exact zeros at initialization and block training. Starting wide (e.g. `b0=8` for
+weights, `f0=8` for activations) keeps everything alive, and the EBOPS regularizer trims the
+bit-widths back down during training. `InputReduce` keeps the first `n` active pixels (based on the
+first channel above `threshold`) in a row-major order.
 By default `n` and `threshold` are trainable hyperparameters: `beta_n` controls how aggressively `n` is driven smaller for a lower hardware footprint, and `beta_maskedE` penalizes over-masking pixel intensity.
 
 ```python
 import keras
 from hgq.layers import QDense
 from hgq.config import QuantizerConfigScope, LayerConfigScope
-from hgq.quantizer.config import QuantizerConfig
 from sparsepixels.layers import InputReduce, QConv2DSparse, AveragePooling2DSparse, MaxPooling2DSparse
 
-iq_conf = QuantizerConfig(place='datalane', q_type='kif', i0=4, f0=8, overflow_mode='WRAP')
-
 with (
-    QuantizerConfigScope(place='all', default_q_type='kbi', overflow_mode='SAT_SYM'),
-    QuantizerConfigScope(place='datalane', default_q_type='kif', overflow_mode='WRAP'),
+    QuantizerConfigScope(place='all', default_q_type='kbi', overflow_mode='SAT_SYM', b0=8, i0=0),
+    QuantizerConfigScope(place='datalane', default_q_type='kif', overflow_mode='WRAP', i0=4, f0=8),
     LayerConfigScope(enable_ebops=True, enable_iq=True, beta0=1e-5),
 ):
     x_in = keras.Input(shape=(28, 28, 1), name='x_in')
@@ -91,14 +93,16 @@ with (
         name='input_reduce',
     )(x_in)
     x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
-                      activation='relu', iq_conf=iq_conf)([x, keep_mask])
+                      activation='relu')([x, keep_mask])
     x, keep_mask = AveragePooling2DSparse(2, name='pool1')([x, keep_mask])
 
     x = keras.layers.Flatten(name='flatten')(x)
-    x = QDense(10, name='dense1', activation='relu', iq_conf=iq_conf)(x)
+    x = QDense(10, name='dense1', activation='relu')(x)
     x = keras.layers.Activation('softmax', name='softmax')(x)
 
 model = keras.Model(x_in, x)
+model.compile(optimizer=keras.optimizers.Adam(1e-3),
+              loss='categorical_crossentropy', metrics=['accuracy'])
 ```
 
 Train the model with `SparseTrainingMonitor`. It records the loss breakdown, the learned
@@ -108,13 +112,11 @@ budget/threshold, the EBOPS and the masked-intensity penalty each epoch, and it
 ```python
 from sparsepixels.utils import SparseTrainingMonitor
 
-early_stop = keras.callbacks.EarlyStopping(monitor='val_accuracy', mode='max', patience=20, restore_best_weights=True)
-model.compile(
-    optimizer=keras.optimizers.Adam(1e-3),
-    loss='categorical_crossentropy', metrics=['accuracy'],
-)
+early_stop = keras.callbacks.EarlyStopping(monitor='val_accuracy', mode='max',
+                                           patience=20, restore_best_weights=True)
 history = model.fit(x_train, y_train, validation_data=(x_val, y_val),
-                    epochs=100, batch_size=128, callbacks=[early_stop, SparseTrainingMonitor()])
+                    epochs=100, batch_size=128,
+                    callbacks=[early_stop, SparseTrainingMonitor()])
 ```
 
 After training, plot the diagnostics from the monitoring tool. The final pixel budget and threshold values are stored in `InputReduce`: `layer.n_max_pixels` and `layer.threshold` (hls4ml converter will auto-parse these from the model).
@@ -132,10 +134,10 @@ print(f"n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}")
 
 ## Converting a trained model to HLS with hls4ml
 
-> **Note:** A [PR](https://github.com/fastmachinelearning/hls4ml/pull/1468) adding `sparsepixels` support to the official [hls4ml](https://github.com/fastmachinelearning/hls4ml) repo has been submitted but is not yet merged. In the meantime you can install hls4ml from the PR branch on this fork to use the converter:
+> **Note:** `sparsepixels` support is part of the official [hls4ml](https://github.com/fastmachinelearning/hls4ml) repo ([PR #1468](https://github.com/fastmachinelearning/hls4ml/pull/1468), merged). It is not in a tagged release yet, so install hls4ml from the main branch:
 >
 > ```bash
-> pip install "git+https://github.com/hftsoi/hls4ml.git@sparsepixels"
+> pip install "git+https://github.com/fastmachinelearning/hls4ml.git"
 > ```
 
 Once installed, pull a config from the trained model, optionally set the per-layer parallelization
@@ -174,7 +176,7 @@ y_hls = hls_model.predict(x_test)
 
 ## Documentation
 
-Coming soon!
+See [here](https://hftsoi.github.io/sparse-pixels/) for documentation with walk-through guidance.
 
 ## Citation
 
@@ -183,11 +185,15 @@ If you find this useful in your research, please consider citing:
 ```
 @article{Tsoi:2025nvg,
     author = "Tsoi, Ho Fung and Rankin, Dylan and Loncar, Vladimir and Harris, Philip",
-    title = "{SparsePixels: Efficient Convolution for Sparse Data on FPGAs}",
+    title = "{SparsePixels: efficient convolution for sparse data on FPGAs}",
     eprint = "2512.06208",
     archivePrefix = "arXiv",
     primaryClass = "cs.AR",
-    month = "12",
-    year = "2025"
+    doi = "10.1088/2632-2153/ae9fb5",
+    journal = "Mach. Learn. Sci. Tech.",
+    volume = "7",
+    number = "5",
+    pages = "055025",
+    year = "2026"
 }
 ```

{sparsepixels-0.3.2 → sparsepixels-0.3.3}/sparsepixels.egg-info/requires.txt

@@ -1,4 +1,5 @@
 tensorflow
 keras>=3.0
 HGQ2>=0.1.8
+quantizers<2
 matplotlib