sparsepixels 0.3.0__tar.gz → 0.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sparsepixels
-Version: 0.3.0
+Version: 0.3.2
 Summary: Efficient convolution for sparse data on FPGAs
 Home-page: https://github.com/hftsoi/sparse-pixels
 Author: Ho Fung Tsoi
@@ -35,7 +35,7 @@ Dynamic: license-file
 [![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)
 
-SparsePixels is a Keras 3 library to build, train, and deploy sparse convolutional neural networks on FPGAs. In many detectors, especially in high-energy physics experiments, the images are almost empty: only a handful of pixels carry a signal (the hits), yet a standard CNN still spends compute on every pixel. A sparse CNN convolves only over the active pixels, so its cost scales with the number of hits rather than the image size, which is what makes low-latency, real-time inference (for example in a trigger) feasible on an FPGA. This library builds quantization-aware (via [HGQ2](https://github.com/calad0i/HGQ2)) sparse CNNs in which the pixel budget and the activity threshold can be learned from data, with a hardware-aware penalty that drives the budget toward the fewest pixels the task tolerates. Trained models convert to FPGA firmware through the [hls4ml](https://github.com/fastmachinelearning/hls4ml) integration, with control over the parallelization of the sparse layers to trade latency against resource usage.
+SparsePixels is a Keras 3 library to build, train, and deploy sparse convolutional neural networks on FPGAs. In many detectors, especially in high-energy physics experiments, the images are almost empty: only a handful of pixels carry a signal (the hits), yet a standard CNN still spends compute on every pixel. A sparse CNN convolves only over the active pixels, so its cost scales with the number of hits rather than the image size, which is what makes low-latency, real-time inference (e.g. in a trigger) feasible on an FPGA. This library builds quantization-aware (with [HGQ2](https://github.com/calad0i/HGQ2) as a backend) sparse CNNs in which the pixel budget and the activity threshold can be learned from data, with a hardware-aware penalty that drives the budget toward the fewest pixels the task tolerates. Trained models convert to FPGA firmware through the [hls4ml](https://github.com/fastmachinelearning/hls4ml) integration, with control over the parallelization of the sparse layers so user can trade latency against resource usage. This training library is designed to mirror our HLS design with bit-exact accuracy.
 
 ## Installation
 
@@ -45,40 +45,33 @@ With Python >= 3.10:
 pip install sparsepixels
 ```
 
-## Getting Started
-
-Import the sparse layers, the quantization library (HGQ2), and the training utilities:
+This includes all necessary backends (tensorflow, keras, HGQ2).
 
-```python
-import keras
-from keras.layers import Flatten, Activation
-from hgq.layers import QConv2D, QDense
-from hgq.config import QuantizerConfigScope, LayerConfigScope
-from hgq.quantizer.config import QuantizerConfig
-from sparsepixels.layers import InputReduce, QConv2DSparse, AveragePooling2DSparse, MaxPooling2DSparse
-from sparsepixels.utils import (
-    active_pixels_vs_threshold, plot_reduced_examples,
-    set_sparse_ebops_factor, cosine_lr,
-    SparseTrainingMonitor, plot_history,
-    print_quantization, plot_quantization,
-)
-```
+## Getting Started
 
 First, study the data to pick a threshold and an initial pixel budget `n`: how many pixels stay
-active as the threshold rises, and what a candidate `(n, threshold)` keeps on a few images.
+active as the threshold rises, and what a candidate `(n, threshold)` maskes out pixels on a few example images.
 
 ```python
+from sparsepixels.utils import active_pixels_vs_threshold, plot_reduced_examples
+
 active_pixels_vs_threshold(x_train)
-plot_reduced_examples(x_train, n=20, threshold=0.1, n_examples=4)
+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 (`f0=8`) prevents the default (`f0=2`) from zeroing out sparse signals
-in early training epochs. `InputReduce` keeps the first `n` active pixels (first channel above
-`threshold`); by default `n` and `threshold` are trainable hyperparameters, and a penalty of weight `beta_n`
-nudges the budget smaller, trading a little accuracy for lower FPGA latency and resources.
+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.
+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 (
@@ -88,72 +81,84 @@ with (
 ):
     x_in = keras.Input(shape=(28, 28, 1), name='x_in')
 
-    # Sparse input reduction
     x, keep_mask = InputReduce(
-        n=30,                    # initial pixel budget
-        threshold=0.1,           # initial activity threshold
-        beta_n=1e-5,             # weight of the pixel budget penalty
-        learn_n=True,            # trainable pixel budget
-        learn_threshold=True,    # trainable threshold
+        n=30,                  # initial pixel budget
+        threshold=0.1,         # initial activity threshold
+        beta_n=5e-3,           # higher -> drives the pixel budget n smaller
+        beta_maskedE=1.0,      # higher -> prevents over-masking
+        learn_n=True,          # trainable pixel budget
+        learn_threshold=True,  # trainable threshold
         name='input_reduce',
     )(x_in)
-
-    # Sparse convolution
     x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
                       activation='relu', iq_conf=iq_conf)([x, keep_mask])
-
-    # Sparse pooling
     x, keep_mask = AveragePooling2DSparse(2, name='pool1')([x, keep_mask])
 
-    x = Flatten(name='flatten')(x)
+    x = keras.layers.Flatten(name='flatten')(x)
     x = QDense(10, name='dense1', activation='relu', iq_conf=iq_conf)(x)
-    x = Activation('softmax', name='softmax')(x)
+    x = keras.layers.Activation('softmax', name='softmax')(x)
 
 model = keras.Model(x_in, x)
 ```
 
-Train the model, then read out the learned sparsity to deploy. `set_sparse_ebops_factor` makes the
-EBOPS (a proxy for the quantized hardware cost) reflect the sparse compute rather than a dense one; a
-cosine-decayed learning rate together with `restore_best_weights` keeps the learned budget from
-over-compressing near the end of training. `plot_history` shows the loss breakdown, the learned
-budget/threshold and the EBOPS in one figure, and the values to deploy are `layer.n_max_pixels` and
-`layer.threshold`.
+Train the model with `SparseTrainingMonitor`. It records the loss breakdown, the learned
+budget/threshold, the EBOPS and the masked-intensity penalty each epoch, and it corrects the EBOPS
+(a proxy for the quantized hardware cost) to the sparse compute automatically.
 
 ```python
-set_sparse_ebops_factor(model)
+from sparsepixels.utils import SparseTrainingMonitor
 
-steps_per_epoch = len(x_train) // 128
 early_stop = keras.callbacks.EarlyStopping(monitor='val_accuracy', mode='max', patience=20, restore_best_weights=True)
 model.compile(
-    optimizer=keras.optimizers.Adam(cosine_lr(1e-3, epochs=100, steps_per_epoch=steps_per_epoch)),
+    optimizer=keras.optimizers.Adam(1e-3),
     loss='categorical_crossentropy', metrics=['accuracy'],
 )
 history = model.fit(x_train, y_train, validation_data=(x_val, y_val),
                     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).
+
+```python
+from sparsepixels.utils import plot_history, print_quantization, plot_quantization
 
-plot_history(history, early_stopping=early_stop)   # loss breakdown, budget, threshold, EBOPS
-print_quantization(model)                          # per-layer bit-width distribution and EBOPS
+plot_history(history, early_stopping=early_stop)  # loss breakdown, budget, threshold, EBOPS
+print_quantization(model)                         # per-layer bit-width distribution and EBOPS
 plot_quantization(model)
 
 ir = model.get_layer('input_reduce')
-print(f"deploy with n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}")
+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 try the converter:
+> **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:
 >
 > ```bash
 > pip install "git+https://github.com/hftsoi/hls4ml.git@sparsepixels"
 > ```
 
-Once installed, converting a trained sparsepixels model to HLS is as usual:
+Once installed, pull a config from the trained model, optionally set the per-layer parallelization
+knobs, and convert:
 
 ```python
 import hls4ml
 
 hls_config = hls4ml.utils.config_from_keras_model(model, granularity='name')
-hls_config.setdefault('Model', {})['PipelineStyle'] = 'dataflow'  # use "#pragma HLS DATAFLOW" (instead of the default "#pragma HLS PIPELINE" for io_parallel)
+hls_config.setdefault('Model', {})['PipelineStyle'] = 'dataflow'  # "#pragma HLS DATAFLOW"
+
+n_max_pixels = model.get_layer('input_reduce').n_max_pixels
+
+# input reduce: 'tree' (default, lowest latency) or 'stream' (sequential, fewer resources)
+hls_config['LayerName']['input_reduce']['Variant'] = 'tree'
+# conv: active pixels in parallel (<= n_max_pixels), and filters in parallel (<= that conv's filters)
+hls_config['LayerName']['conv1']['PixelParallelFactor'] = n_max_pixels
+hls_config['LayerName']['conv1']['FiltParallelFactor'] = 3
+# pool: active pixels in parallel, and channels in parallel
+hls_config['LayerName']['pool1']['PixelParallelFactor'] = n_max_pixels
+hls_config['LayerName']['pool1']['ChanParallelFactor'] = 3
+# flatten: scatter positions in parallel (<= out_height * out_width; here 28*28 pools to 14*14)
+hls_config['LayerName']['flatten']['ParallelFactor'] = 14 * 14
 
 hls_model = hls4ml.converters.convert_from_keras_model(
     model,

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

@@ -16,7 +16,7 @@
 [![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)
 
-SparsePixels is a Keras 3 library to build, train, and deploy sparse convolutional neural networks on FPGAs. In many detectors, especially in high-energy physics experiments, the images are almost empty: only a handful of pixels carry a signal (the hits), yet a standard CNN still spends compute on every pixel. A sparse CNN convolves only over the active pixels, so its cost scales with the number of hits rather than the image size, which is what makes low-latency, real-time inference (for example in a trigger) feasible on an FPGA. This library builds quantization-aware (via [HGQ2](https://github.com/calad0i/HGQ2)) sparse CNNs in which the pixel budget and the activity threshold can be learned from data, with a hardware-aware penalty that drives the budget toward the fewest pixels the task tolerates. Trained models convert to FPGA firmware through the [hls4ml](https://github.com/fastmachinelearning/hls4ml) integration, with control over the parallelization of the sparse layers to trade latency against resource usage.
+SparsePixels is a Keras 3 library to build, train, and deploy sparse convolutional neural networks on FPGAs. In many detectors, especially in high-energy physics experiments, the images are almost empty: only a handful of pixels carry a signal (the hits), yet a standard CNN still spends compute on every pixel. A sparse CNN convolves only over the active pixels, so its cost scales with the number of hits rather than the image size, which is what makes low-latency, real-time inference (e.g. in a trigger) feasible on an FPGA. This library builds quantization-aware (with [HGQ2](https://github.com/calad0i/HGQ2) as a backend) sparse CNNs in which the pixel budget and the activity threshold can be learned from data, with a hardware-aware penalty that drives the budget toward the fewest pixels the task tolerates. Trained models convert to FPGA firmware through the [hls4ml](https://github.com/fastmachinelearning/hls4ml) integration, with control over the parallelization of the sparse layers so user can trade latency against resource usage. This training library is designed to mirror our HLS design with bit-exact accuracy.
 
 ## Installation
 
@@ -26,40 +26,33 @@ With Python >= 3.10:
 pip install sparsepixels
 ```
 
-## Getting Started
-
-Import the sparse layers, the quantization library (HGQ2), and the training utilities:
+This includes all necessary backends (tensorflow, keras, HGQ2).
 
-```python
-import keras
-from keras.layers import Flatten, Activation
-from hgq.layers import QConv2D, QDense
-from hgq.config import QuantizerConfigScope, LayerConfigScope
-from hgq.quantizer.config import QuantizerConfig
-from sparsepixels.layers import InputReduce, QConv2DSparse, AveragePooling2DSparse, MaxPooling2DSparse
-from sparsepixels.utils import (
-    active_pixels_vs_threshold, plot_reduced_examples,
-    set_sparse_ebops_factor, cosine_lr,
-    SparseTrainingMonitor, plot_history,
-    print_quantization, plot_quantization,
-)
-```
+## Getting Started
 
 First, study the data to pick a threshold and an initial pixel budget `n`: how many pixels stay
-active as the threshold rises, and what a candidate `(n, threshold)` keeps on a few images.
+active as the threshold rises, and what a candidate `(n, threshold)` maskes out pixels on a few example images.
 
 ```python
+from sparsepixels.utils import active_pixels_vs_threshold, plot_reduced_examples
+
 active_pixels_vs_threshold(x_train)
-plot_reduced_examples(x_train, n=20, threshold=0.1, n_examples=4)
+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 (`f0=8`) prevents the default (`f0=2`) from zeroing out sparse signals
-in early training epochs. `InputReduce` keeps the first `n` active pixels (first channel above
-`threshold`); by default `n` and `threshold` are trainable hyperparameters, and a penalty of weight `beta_n`
-nudges the budget smaller, trading a little accuracy for lower FPGA latency and resources.
+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.
+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 (
@@ -69,72 +62,84 @@ with (
 ):
     x_in = keras.Input(shape=(28, 28, 1), name='x_in')
 
-    # Sparse input reduction
     x, keep_mask = InputReduce(
-        n=30,                    # initial pixel budget
-        threshold=0.1,           # initial activity threshold
-        beta_n=1e-5,             # weight of the pixel budget penalty
-        learn_n=True,            # trainable pixel budget
-        learn_threshold=True,    # trainable threshold
+        n=30,                  # initial pixel budget
+        threshold=0.1,         # initial activity threshold
+        beta_n=5e-3,           # higher -> drives the pixel budget n smaller
+        beta_maskedE=1.0,      # higher -> prevents over-masking
+        learn_n=True,          # trainable pixel budget
+        learn_threshold=True,  # trainable threshold
         name='input_reduce',
     )(x_in)
-
-    # Sparse convolution
     x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
                       activation='relu', iq_conf=iq_conf)([x, keep_mask])
-
-    # Sparse pooling
     x, keep_mask = AveragePooling2DSparse(2, name='pool1')([x, keep_mask])
 
-    x = Flatten(name='flatten')(x)
+    x = keras.layers.Flatten(name='flatten')(x)
     x = QDense(10, name='dense1', activation='relu', iq_conf=iq_conf)(x)
-    x = Activation('softmax', name='softmax')(x)
+    x = keras.layers.Activation('softmax', name='softmax')(x)
 
 model = keras.Model(x_in, x)
 ```
 
-Train the model, then read out the learned sparsity to deploy. `set_sparse_ebops_factor` makes the
-EBOPS (a proxy for the quantized hardware cost) reflect the sparse compute rather than a dense one; a
-cosine-decayed learning rate together with `restore_best_weights` keeps the learned budget from
-over-compressing near the end of training. `plot_history` shows the loss breakdown, the learned
-budget/threshold and the EBOPS in one figure, and the values to deploy are `layer.n_max_pixels` and
-`layer.threshold`.
+Train the model with `SparseTrainingMonitor`. It records the loss breakdown, the learned
+budget/threshold, the EBOPS and the masked-intensity penalty each epoch, and it corrects the EBOPS
+(a proxy for the quantized hardware cost) to the sparse compute automatically.
 
 ```python
-set_sparse_ebops_factor(model)
+from sparsepixels.utils import SparseTrainingMonitor
 
-steps_per_epoch = len(x_train) // 128
 early_stop = keras.callbacks.EarlyStopping(monitor='val_accuracy', mode='max', patience=20, restore_best_weights=True)
 model.compile(
-    optimizer=keras.optimizers.Adam(cosine_lr(1e-3, epochs=100, steps_per_epoch=steps_per_epoch)),
+    optimizer=keras.optimizers.Adam(1e-3),
     loss='categorical_crossentropy', metrics=['accuracy'],
 )
 history = model.fit(x_train, y_train, validation_data=(x_val, y_val),
                     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).
+
+```python
+from sparsepixels.utils import plot_history, print_quantization, plot_quantization
 
-plot_history(history, early_stopping=early_stop)   # loss breakdown, budget, threshold, EBOPS
-print_quantization(model)                          # per-layer bit-width distribution and EBOPS
+plot_history(history, early_stopping=early_stop)  # loss breakdown, budget, threshold, EBOPS
+print_quantization(model)                         # per-layer bit-width distribution and EBOPS
 plot_quantization(model)
 
 ir = model.get_layer('input_reduce')
-print(f"deploy with n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}")
+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 try the converter:
+> **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:
 >
 > ```bash
 > pip install "git+https://github.com/hftsoi/hls4ml.git@sparsepixels"
 > ```
 
-Once installed, converting a trained sparsepixels model to HLS is as usual:
+Once installed, pull a config from the trained model, optionally set the per-layer parallelization
+knobs, and convert:
 
 ```python
 import hls4ml
 
 hls_config = hls4ml.utils.config_from_keras_model(model, granularity='name')
-hls_config.setdefault('Model', {})['PipelineStyle'] = 'dataflow'  # use "#pragma HLS DATAFLOW" (instead of the default "#pragma HLS PIPELINE" for io_parallel)
+hls_config.setdefault('Model', {})['PipelineStyle'] = 'dataflow'  # "#pragma HLS DATAFLOW"
+
+n_max_pixels = model.get_layer('input_reduce').n_max_pixels
+
+# input reduce: 'tree' (default, lowest latency) or 'stream' (sequential, fewer resources)
+hls_config['LayerName']['input_reduce']['Variant'] = 'tree'
+# conv: active pixels in parallel (<= n_max_pixels), and filters in parallel (<= that conv's filters)
+hls_config['LayerName']['conv1']['PixelParallelFactor'] = n_max_pixels
+hls_config['LayerName']['conv1']['FiltParallelFactor'] = 3
+# pool: active pixels in parallel, and channels in parallel
+hls_config['LayerName']['pool1']['PixelParallelFactor'] = n_max_pixels
+hls_config['LayerName']['pool1']['ChanParallelFactor'] = 3
+# flatten: scatter positions in parallel (<= out_height * out_width; here 28*28 pools to 14*14)
+hls_config['LayerName']['flatten']['ParallelFactor'] = 14 * 14
 
 hls_model = hls4ml.converters.convert_from_keras_model(
     model,

{sparsepixels-0.3.0 → sparsepixels-0.3.2}/notebook/utils.py

@@ -1149,6 +1149,103 @@ def preview_patches_with_pooling(
             plt.show()
 
 
+def plot_layer_outputs(model, x_input, sample_idx=0, layer_names=None,
+                       cmap='viridis', figsize_per_ch=3):
+    """Plot channel-wise feature maps for intermediate layers of a sparse or dense CNN.
+
+    Parameters
+    ----------
+    model : keras.Model
+        The model (sparse or dense). Sparse models may have layers with
+        tuple outputs (features, mask).
+    x_input : np.ndarray
+        Full input dataset (batch, H, W, C).
+    sample_idx : int
+        Index of the sample in *x_input* to visualise.
+    layer_names : list[str] or None
+        Layer names to plot.  If *None*, auto-discovers layers whose names
+        start with common prefixes (x_in, input_reduce, conv, pool, dense).
+    cmap : str
+        Matplotlib colormap name.
+    figsize_per_ch : float
+        Width of each channel subplot in inches.
+    """
+    import keras
+
+    if layer_names is None:
+        prefixes = ('x_in', 'input_reduce', 'conv', 'pool', 'dense')
+        layer_names = [l.name for l in model.layers
+                       if any(l.name.startswith(p) for p in prefixes)]
+
+    plot_tensors = []
+    plot_names = []
+    for name in layer_names:
+        layer = model.get_layer(name)
+        output = layer.output
+        if isinstance(output, (list, tuple)):
+            plot_tensors.append(output[0])
+            plot_names.append(f'{name} (features)')
+            plot_tensors.append(output[1])
+            plot_names.append(f'{name} (mask)')
+        else:
+            plot_tensors.append(output)
+            plot_names.append(name)
+
+    probe = keras.models.Model(inputs=model.input, outputs=plot_tensors)
+    preds = probe.predict(x_input[sample_idx:sample_idx + 1], verbose=0)
+
+    if not isinstance(preds, list):
+        preds = [preds]
+
+    i = 0
+    while i < len(plot_names):
+        name = plot_names[i]
+
+        if '(features)' in name and i + 1 < len(plot_names) and '(mask)' in plot_names[i + 1]:
+            arr = preds[i][0]
+            if arr.ndim == 3:
+                h, w, c = arr.shape
+                fig, axes = plt.subplots(1, c, figsize=(c * figsize_per_ch, figsize_per_ch))
+                fig.suptitle(name.replace(' (features)', ''), fontsize=13)
+                if c == 1:
+                    axes = [axes]
+                for ch in range(c):
+                    axes[ch].imshow(arr[..., ch], cmap=cmap)
+                    axes[ch].set_title(f'ch{ch}')
+                plt.tight_layout()
+                plt.show()
+            i += 2
+            continue
+
+        arr = preds[i][0]
+        if arr.ndim == 1:
+            fig, ax = plt.subplots(1, 1, figsize=(max(len(arr) * 0.3, 4), figsize_per_ch))
+            fig.suptitle(name, fontsize=13)
+            ax.bar(range(len(arr)), arr)
+            ax.set_xlabel('unit')
+            plt.tight_layout()
+            plt.show()
+        elif arr.ndim == 2:
+            fig, ax = plt.subplots(1, 1, figsize=(figsize_per_ch, figsize_per_ch))
+            fig.suptitle(name, fontsize=13)
+            ax.imshow(arr, cmap=cmap)
+            ax.set_title('ch0')
+            plt.tight_layout()
+            plt.show()
+        elif arr.ndim == 3:
+            h, w, c = arr.shape
+            fig, axes = plt.subplots(1, c, figsize=(c * figsize_per_ch, figsize_per_ch))
+            fig.suptitle(name, fontsize=13)
+            if c == 1:
+                axes = [axes]
+            for ch in range(c):
+                axes[ch].imshow(arr[..., ch], cmap=cmap)
+                axes[ch].set_title(f'ch{ch}')
+            plt.tight_layout()
+            plt.show()
+        i += 1
+
+
 def _fmt_bits(bits_tensor):
     b = np.array(bits_tensor).flatten()
     if b.size == 1:

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

@@ -1,6 +1,6 @@
 [metadata]
 name = sparsepixels
-version = 0.3.0
+version = 0.3.2
 description = Efficient convolution for sparse data on FPGAs
 author = Ho Fung Tsoi
 author_email = ho.fung.tsoi@cern.ch

{sparsepixels-0.3.0 → sparsepixels-0.3.2}/sparsepixels/layers.py

@@ -32,13 +32,18 @@ class InputReduce(keras.layers.Layer):
     plain, non-learnable selection). The selection is always exact -- the learnable versions only
     shape the gradient, so the layer behaves identically at inference and stays deployable. When n is
     learned, a penalty of weight beta_n nudges it smaller, trading a little accuracy for lower FPGA
-    latency and resources; it starts at n and stays within [1, 4*n]. After training, read the values
-    to deploy from the n_max_pixels and threshold properties.
+    latency and resources; it starts at n and can range over [1, H*W]. An optional penalty of weight
+    beta_maskedE discourages masking pixel intensity, giving the threshold (and n) a restoring force so a
+    trainable threshold settles near the noise floor instead of over-masking signal. After training,
+    read the values to deploy from the n_max_pixels and threshold properties.
 
     Args:
         n: initial pixel budget, and the fixed budget when learn_n is False.
         threshold: initial activity threshold on the first channel, fixed when learn_threshold is False.
         beta_n: weight of the budget penalty added to the loss (0 disables it).
+        beta_maskedE: weight of the masked-intensity penalty (0 disables it). Penalizes the fraction of pixel
+            intensity that gets masked, so masking bright (signal) pixels is costly while masking dim
+            (noise) pixels is cheap -- an adaptive, non-vanishing restoring force against over-masking.
         learn_n: make the pixel budget trainable.
         learn_threshold: make the threshold trainable.
         tau_threshold: softness of the threshold surrogate used to obtain gradients.
@@ -49,7 +54,8 @@ class InputReduce(keras.layers.Layer):
         self,
         n=30,
         threshold=0.0,
-        beta_n=1e-5,
+        beta_n=5e-3,
+        beta_maskedE=1.0,
         learn_n=True,
         learn_threshold=True,
         tau_threshold=0.05,
@@ -60,6 +66,7 @@ class InputReduce(keras.layers.Layer):
         self.n_init = int(n)
         self.threshold_init = float(threshold)
         self.beta_n = float(beta_n)
+        self.beta_maskedE = float(beta_maskedE)
         self.learn_n = learn_n
         self.learn_threshold = learn_threshold
         self.tau_threshold = float(tau_threshold)
@@ -76,13 +83,24 @@ class InputReduce(keras.layers.Layer):
             )
         if self.learn_n:
             # Parametrize the budget as a fraction of its initial value (n = n_init * n_frac) so it
-            # moves at a useful rate under Adam; clip to [1, 4x] so it can shrink or modestly grow.
+            # moves at a useful rate under Adam; clip to [1, H*W] so it can shrink to a single pixel
+            # or grow up to keeping every pixel.
+            if input_shape[1] and input_shape[2]:
+                hi = (input_shape[1] * input_shape[2]) / self.n_init
+            else:
+                hi = 4.0
             self.n_frac = self.add_weight(
                 name="n_frac",
                 shape=(),
                 initializer=keras.initializers.Constant(1.0),
                 trainable=True,
-                constraint=_ClipToRange(1.0 / self.n_init, 4.0),
+                constraint=_ClipToRange(1.0 / self.n_init, max(1.0, hi)),
+            )
+        if self.beta_maskedE > 0:
+            # Running masked-intensity fraction, tracked (not trained) so SparseTrainingMonitor can
+            # report the penalty; refreshed each call.
+            self._masked_intensity = self.add_weight(
+                name="masked_intensity", shape=(), initializer="zeros", trainable=False
             )
         super().build(input_shape)
 
@@ -108,6 +126,15 @@ class InputReduce(keras.layers.Layer):
             rank_soft = ops.cumsum(active_soft, axis=1)
             keep_soft = active_soft * ops.sigmoid((n - rank_soft) / self.tau_n)
             keep_flat = keep_soft + ops.stop_gradient(keep_hard - keep_soft)
+
+            if self.beta_maskedE > 0:
+                # Fraction of total pixel intensity that gets masked, added straight to the loss (not
+                # through the classifier) so its gradient does not vanish for the masked pixels.
+                # Masking bright pixels costs more than masking dim ones, so this pushes the threshold
+                # back down (and n up) before it eats into signal -- an adaptive anti-over-masking term.
+                masked_frac = ops.mean(ops.sum(score * (1.0 - keep_soft), axis=1) / (ops.sum(score, axis=1) + 1e-6))
+                self.add_loss(self.beta_maskedE * masked_frac)
+                self._masked_intensity.assign(masked_frac)
         else:
             keep_flat = keep_hard
 
@@ -140,6 +167,7 @@ class InputReduce(keras.layers.Layer):
                 "n": self.n_init,
                 "threshold": self.threshold_init,
                 "beta_n": self.beta_n,
+                "beta_maskedE": self.beta_maskedE,
                 "learn_n": self.learn_n,
                 "learn_threshold": self.learn_threshold,
                 "tau_threshold": self.tau_threshold,

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

@@ -9,7 +9,6 @@ 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 keras
 import matplotlib.pyplot as plt
 import numpy as np
 from keras import ops
@@ -49,9 +48,10 @@ def set_sparse_ebops_factor(model):
     HGQ counts a conv's EBOPS as if it ran over the whole H*W feature map, which overestimates a
     sparse conv that only touches about n_max_pixels of them. This scales each sparse conv's EBOPS by
     n_max_pixels / (H*W) through HGQ's own ebops_factor, so both the reported EBOPS and the EBOPS
-    regularization loss reflect the sparse compute. Call once after building the model, before fit.
-    For a learnable budget it uses the current n_max_pixels, which is a good approximation since the
-    budget moves slowly; call it again if the budget changes a lot.
+    regularization loss reflect the sparse compute. SparseTrainingMonitor applies this automatically
+    at the start of training, so you usually do not need to call it directly -- call it manually only
+    to correct EBOPS you inspect before training, or to refresh it if a learnable budget moves a lot
+    (it uses the current n_max_pixels, a good approximation since the budget moves slowly).
 
     Returns a dict of {layer_name: factor} for the sparse convs that were adjusted.
     """
@@ -115,6 +115,20 @@ def _budget_reg_loss(model):
     return total
 
 
+def _masked_intensity_reg_loss(model):
+    """Sum beta_maskedE * masked_intensity over the InputReduce layers using the masked-intensity penalty."""
+    total = 0.0
+    for ir in _input_reduce_layers(model):
+        beta_maskedE = getattr(ir, "beta_maskedE", 0.0)
+        mi = getattr(ir, "_masked_intensity", None)
+        if beta_maskedE > 0 and mi is not None:
+            try:
+                total += beta_maskedE * float(ops.convert_to_numpy(mi))
+            except Exception:
+                continue
+    return total
+
+
 def _fmt_bits(bits_tensor):
     b = np.array(bits_tensor).flatten()
     if b.size == 1:
@@ -157,12 +171,21 @@ class SparseTrainingMonitor(Callback):
 
     - n_max_pixels and threshold: the learned or fixed pixel budget and threshold of the InputReduce
       layer (suffixed with the layer name when there is more than one).
-    - ebops: total EBOPS over the quantized layers, a proxy for the quantized hardware cost (sparse
-      corrected once set_sparse_ebops_factor has been applied).
-    - loss_task, loss_ebops, loss_n: the training loss split into the task loss, the EBOPS penalty and
-      the pixel-budget penalty, each already scaled by its weight so the three add up to the loss.
+    - ebops: total EBOPS over the quantized layers, a proxy for the quantized hardware cost. This
+      monitor applies set_sparse_ebops_factor at the start of training, so the EBOPS (and its
+      regularizer) reflect the sparse (active-pixel) compute without any manual call.
+    - loss_task, loss_ebops, loss_n, loss_maskedE: the training loss split into the task loss, the
+      EBOPS penalty, the pixel-budget penalty and the masked-intensity penalty (the last present only
+      when its weight beta_maskedE is nonzero), each already scaled by its weight so the parts add up to the
+      loss.
     """
 
+    def on_train_begin(self, logs=None):
+        # Fold in set_sparse_ebops_factor so the user need not call it manually. Uses the current
+        # (initial) budget, matching a manual call right before fit; call it again yourself if a
+        # learnable budget moves a lot during training.
+        set_sparse_ebops_factor(self.model)
+
     def on_epoch_end(self, epoch, logs=None):
         if logs is None:
             return
@@ -177,14 +200,18 @@ class SparseTrainingMonitor(Callback):
         reg_ebops = _ebops_reg_loss(self.model) if found else 0.0
         has_budget = any(getattr(ir, "learn_n", False) for ir in irs)
         reg_n = _budget_reg_loss(self.model) if has_budget else 0.0
+        has_maskedE = any(getattr(ir, "beta_maskedE", 0.0) > 0 for ir in irs)
+        reg_maskedE = _masked_intensity_reg_loss(self.model) if has_maskedE else 0.0
         if found:
             logs["ebops"] = ebops
             logs["loss_ebops"] = reg_ebops
         if has_budget:
             logs["loss_n"] = reg_n
+        if has_maskedE:
+            logs["loss_maskedE"] = reg_maskedE
         # Task loss is the total minus the (train-only) penalties, so the parts add up to the loss.
         if "loss" in logs:
-            logs["loss_task"] = logs["loss"] - reg_ebops - reg_n
+            logs["loss_task"] = logs["loss"] - reg_ebops - reg_n - reg_maskedE
 
 
 def plot_history(history, early_stopping=None, figsize=None, ncols=3):
@@ -212,7 +239,7 @@ def plot_history(history, early_stopping=None, figsize=None, ncols=3):
 
     def _is_single(k):
         return (
-            k in ("ebops", "loss_task", "loss_ebops", "loss_n")
+            k in ("ebops", "loss_task", "loss_ebops", "loss_n", "loss_maskedE")
             or k.startswith("n_max_pixels")
             or k.startswith("threshold")
         )
@@ -222,7 +249,7 @@ def plot_history(history, early_stopping=None, figsize=None, ncols=3):
     metric_keys = [k for k in h if not k.startswith("val_") and k not in skip]
     m_order = ["loss"]
     metric_keys = [k for k in m_order if k in metric_keys] + [k for k in metric_keys if k not in m_order]
-    s_order = ["loss_task", "loss_ebops", "loss_n", "n_max_pixels", "threshold", "ebops"]
+    s_order = ["loss_task", "loss_ebops", "loss_n", "loss_maskedE", "n_max_pixels", "threshold", "ebops"]
     single_keys = [k for k in s_order if k in single_keys] + [k for k in single_keys if k not in s_order]
 
     panels = metric_keys + single_keys
@@ -246,7 +273,7 @@ def plot_history(history, early_stopping=None, figsize=None, ncols=3):
             show_legend = True
         else:
             vals = list(h[key])
-            color = "tab:red" if key in ("loss_task", "loss_ebops", "loss_n") else "tab:green"
+            color = "tab:red" if key in ("loss_task", "loss_ebops", "loss_n", "loss_maskedE") else "tab:green"
             ax.plot(ep, vals, marker=".", color=color)
             # annotate first and last epoch (above the point) so the endpoints are easy to read
             for xi, yi in ((1, vals[0]), (len(vals), vals[-1])):
@@ -284,26 +311,6 @@ def plot_history(history, early_stopping=None, figsize=None, ncols=3):
     plt.show()
 
 
-def cosine_lr(initial_learning_rate, epochs, steps_per_epoch, alpha=0.0):
-    """Cosine-decay learning-rate schedule spanning the whole training run.
-
-    A decaying rate lets the learnable budget and threshold move quickly early and then settle late,
-    instead of drifting the whole time (which is what pushes the budget to over-compress near the
-    end). Pass the result as the optimizer's learning_rate, and pair it with an EarlyStopping that
-    monitors val_accuracy with restore_best_weights so the best-validation values are the ones you
-    deploy.
-
-    Args:
-        initial_learning_rate: starting learning rate, e.g. 1e-3.
-        epochs: number of training epochs.
-        steps_per_epoch: batches per epoch, i.e. ceil(len(x_train) / batch_size).
-        alpha: final learning rate as a fraction of the initial (0 decays to about 0).
-    """
-    return keras.optimizers.schedules.CosineDecay(
-        initial_learning_rate, decay_steps=int(epochs * steps_per_epoch), alpha=alpha
-    )
-
-
 def active_pixels_vs_threshold(x, thresholds=None, channel=0, percentiles=(25, 50, 75), plot=True, ax=None):
     """Study how the number of active pixels per image changes with the threshold.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sparsepixels
-Version: 0.3.0
+Version: 0.3.2
 Summary: Efficient convolution for sparse data on FPGAs
 Home-page: https://github.com/hftsoi/sparse-pixels
 Author: Ho Fung Tsoi
@@ -35,7 +35,7 @@ Dynamic: license-file
 [![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)
 
-SparsePixels is a Keras 3 library to build, train, and deploy sparse convolutional neural networks on FPGAs. In many detectors, especially in high-energy physics experiments, the images are almost empty: only a handful of pixels carry a signal (the hits), yet a standard CNN still spends compute on every pixel. A sparse CNN convolves only over the active pixels, so its cost scales with the number of hits rather than the image size, which is what makes low-latency, real-time inference (for example in a trigger) feasible on an FPGA. This library builds quantization-aware (via [HGQ2](https://github.com/calad0i/HGQ2)) sparse CNNs in which the pixel budget and the activity threshold can be learned from data, with a hardware-aware penalty that drives the budget toward the fewest pixels the task tolerates. Trained models convert to FPGA firmware through the [hls4ml](https://github.com/fastmachinelearning/hls4ml) integration, with control over the parallelization of the sparse layers to trade latency against resource usage.
+SparsePixels is a Keras 3 library to build, train, and deploy sparse convolutional neural networks on FPGAs. In many detectors, especially in high-energy physics experiments, the images are almost empty: only a handful of pixels carry a signal (the hits), yet a standard CNN still spends compute on every pixel. A sparse CNN convolves only over the active pixels, so its cost scales with the number of hits rather than the image size, which is what makes low-latency, real-time inference (e.g. in a trigger) feasible on an FPGA. This library builds quantization-aware (with [HGQ2](https://github.com/calad0i/HGQ2) as a backend) sparse CNNs in which the pixel budget and the activity threshold can be learned from data, with a hardware-aware penalty that drives the budget toward the fewest pixels the task tolerates. Trained models convert to FPGA firmware through the [hls4ml](https://github.com/fastmachinelearning/hls4ml) integration, with control over the parallelization of the sparse layers so user can trade latency against resource usage. This training library is designed to mirror our HLS design with bit-exact accuracy.
 
 ## Installation
 
@@ -45,40 +45,33 @@ With Python >= 3.10:
 pip install sparsepixels
 ```
 
-## Getting Started
-
-Import the sparse layers, the quantization library (HGQ2), and the training utilities:
+This includes all necessary backends (tensorflow, keras, HGQ2).
 
-```python
-import keras
-from keras.layers import Flatten, Activation
-from hgq.layers import QConv2D, QDense
-from hgq.config import QuantizerConfigScope, LayerConfigScope
-from hgq.quantizer.config import QuantizerConfig
-from sparsepixels.layers import InputReduce, QConv2DSparse, AveragePooling2DSparse, MaxPooling2DSparse
-from sparsepixels.utils import (
-    active_pixels_vs_threshold, plot_reduced_examples,
-    set_sparse_ebops_factor, cosine_lr,
-    SparseTrainingMonitor, plot_history,
-    print_quantization, plot_quantization,
-)
-```
+## Getting Started
 
 First, study the data to pick a threshold and an initial pixel budget `n`: how many pixels stay
-active as the threshold rises, and what a candidate `(n, threshold)` keeps on a few images.
+active as the threshold rises, and what a candidate `(n, threshold)` maskes out pixels on a few example images.
 
 ```python
+from sparsepixels.utils import active_pixels_vs_threshold, plot_reduced_examples
+
 active_pixels_vs_threshold(x_train)
-plot_reduced_examples(x_train, n=20, threshold=0.1, n_examples=4)
+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 (`f0=8`) prevents the default (`f0=2`) from zeroing out sparse signals
-in early training epochs. `InputReduce` keeps the first `n` active pixels (first channel above
-`threshold`); by default `n` and `threshold` are trainable hyperparameters, and a penalty of weight `beta_n`
-nudges the budget smaller, trading a little accuracy for lower FPGA latency and resources.
+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.
+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 (
@@ -88,72 +81,84 @@ with (
 ):
     x_in = keras.Input(shape=(28, 28, 1), name='x_in')
 
-    # Sparse input reduction
     x, keep_mask = InputReduce(
-        n=30,                    # initial pixel budget
-        threshold=0.1,           # initial activity threshold
-        beta_n=1e-5,             # weight of the pixel budget penalty
-        learn_n=True,            # trainable pixel budget
-        learn_threshold=True,    # trainable threshold
+        n=30,                  # initial pixel budget
+        threshold=0.1,         # initial activity threshold
+        beta_n=5e-3,           # higher -> drives the pixel budget n smaller
+        beta_maskedE=1.0,      # higher -> prevents over-masking
+        learn_n=True,          # trainable pixel budget
+        learn_threshold=True,  # trainable threshold
         name='input_reduce',
     )(x_in)
-
-    # Sparse convolution
     x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
                       activation='relu', iq_conf=iq_conf)([x, keep_mask])
-
-    # Sparse pooling
     x, keep_mask = AveragePooling2DSparse(2, name='pool1')([x, keep_mask])
 
-    x = Flatten(name='flatten')(x)
+    x = keras.layers.Flatten(name='flatten')(x)
     x = QDense(10, name='dense1', activation='relu', iq_conf=iq_conf)(x)
-    x = Activation('softmax', name='softmax')(x)
+    x = keras.layers.Activation('softmax', name='softmax')(x)
 
 model = keras.Model(x_in, x)
 ```
 
-Train the model, then read out the learned sparsity to deploy. `set_sparse_ebops_factor` makes the
-EBOPS (a proxy for the quantized hardware cost) reflect the sparse compute rather than a dense one; a
-cosine-decayed learning rate together with `restore_best_weights` keeps the learned budget from
-over-compressing near the end of training. `plot_history` shows the loss breakdown, the learned
-budget/threshold and the EBOPS in one figure, and the values to deploy are `layer.n_max_pixels` and
-`layer.threshold`.
+Train the model with `SparseTrainingMonitor`. It records the loss breakdown, the learned
+budget/threshold, the EBOPS and the masked-intensity penalty each epoch, and it corrects the EBOPS
+(a proxy for the quantized hardware cost) to the sparse compute automatically.
 
 ```python
-set_sparse_ebops_factor(model)
+from sparsepixels.utils import SparseTrainingMonitor
 
-steps_per_epoch = len(x_train) // 128
 early_stop = keras.callbacks.EarlyStopping(monitor='val_accuracy', mode='max', patience=20, restore_best_weights=True)
 model.compile(
-    optimizer=keras.optimizers.Adam(cosine_lr(1e-3, epochs=100, steps_per_epoch=steps_per_epoch)),
+    optimizer=keras.optimizers.Adam(1e-3),
     loss='categorical_crossentropy', metrics=['accuracy'],
 )
 history = model.fit(x_train, y_train, validation_data=(x_val, y_val),
                     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).
+
+```python
+from sparsepixels.utils import plot_history, print_quantization, plot_quantization
 
-plot_history(history, early_stopping=early_stop)   # loss breakdown, budget, threshold, EBOPS
-print_quantization(model)                          # per-layer bit-width distribution and EBOPS
+plot_history(history, early_stopping=early_stop)  # loss breakdown, budget, threshold, EBOPS
+print_quantization(model)                         # per-layer bit-width distribution and EBOPS
 plot_quantization(model)
 
 ir = model.get_layer('input_reduce')
-print(f"deploy with n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}")
+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 try the converter:
+> **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:
 >
 > ```bash
 > pip install "git+https://github.com/hftsoi/hls4ml.git@sparsepixels"
 > ```
 
-Once installed, converting a trained sparsepixels model to HLS is as usual:
+Once installed, pull a config from the trained model, optionally set the per-layer parallelization
+knobs, and convert:
 
 ```python
 import hls4ml
 
 hls_config = hls4ml.utils.config_from_keras_model(model, granularity='name')
-hls_config.setdefault('Model', {})['PipelineStyle'] = 'dataflow'  # use "#pragma HLS DATAFLOW" (instead of the default "#pragma HLS PIPELINE" for io_parallel)
+hls_config.setdefault('Model', {})['PipelineStyle'] = 'dataflow'  # "#pragma HLS DATAFLOW"
+
+n_max_pixels = model.get_layer('input_reduce').n_max_pixels
+
+# input reduce: 'tree' (default, lowest latency) or 'stream' (sequential, fewer resources)
+hls_config['LayerName']['input_reduce']['Variant'] = 'tree'
+# conv: active pixels in parallel (<= n_max_pixels), and filters in parallel (<= that conv's filters)
+hls_config['LayerName']['conv1']['PixelParallelFactor'] = n_max_pixels
+hls_config['LayerName']['conv1']['FiltParallelFactor'] = 3
+# pool: active pixels in parallel, and channels in parallel
+hls_config['LayerName']['pool1']['PixelParallelFactor'] = n_max_pixels
+hls_config['LayerName']['pool1']['ChanParallelFactor'] = 3
+# flatten: scatter positions in parallel (<= out_height * out_width; here 28*28 pools to 14*14)
+hls_config['LayerName']['flatten']['ParallelFactor'] = 14 * 14
 
 hls_model = hls4ml.converters.convert_from_keras_model(
     model,

{sparsepixels-0.3.0 → sparsepixels-0.3.2}/sparsepixels.egg-info/top_level.txt

@@ -1,6 +1,5 @@
 dist
 docs
-hls_templates
 notebook
 sparsepixels
 tests

{sparsepixels-0.3.0 → sparsepixels-0.3.2}/tests/test_model.py

@@ -11,7 +11,7 @@ from hgq.quantizer.config import QuantizerConfig
 from keras.layers import Activation, AveragePooling2D, Flatten
 
 from sparsepixels.layers import AveragePooling2DSparse, InputReduce, QConv2DSparse
-from sparsepixels.utils import SparseTrainingMonitor, cosine_lr, plot_history, set_sparse_ebops_factor
+from sparsepixels.utils import SparseTrainingMonitor, plot_history, set_sparse_ebops_factor
 
 
 def build_cnn(is_sparse, n=20, threshold=0.0, beta_n=1e-4, learn_n=True, learn_threshold=True):
@@ -74,20 +74,19 @@ def test_sparse_cnn_fixed_mode():
 
 
 def test_sparse_cnn_trains_with_monitor():
-    # exercise the learnable path, cosine LR, EBOPS factor, monitor and plot on a tiny synthetic set
+    # exercise the learnable path, EBOPS factor, monitor and plot on a tiny synthetic set
     rng = np.random.default_rng(0)
     x = rng.random((64, 32, 32, 1)).astype('float32')
     y = keras.utils.to_categorical(np.arange(64) % 10, 10)
 
     m = build_cnn(is_sparse=True, n=20, threshold=0.3, beta_n=1e-3)
-    steps = int(np.ceil(len(x) / 32))
     m.compile(
-        optimizer=keras.optimizers.Adam(cosine_lr(1e-3, epochs=2, steps_per_epoch=steps)),
+        optimizer=keras.optimizers.Adam(1e-3),
         loss='categorical_crossentropy',
         metrics=['accuracy'],
     )
     history = m.fit(x, y, epochs=2, batch_size=32, verbose=0, callbacks=[SparseTrainingMonitor()])
 
-    for key in ('loss', 'loss_task', 'loss_ebops', 'loss_n', 'n_max_pixels', 'threshold', 'ebops'):
+    for key in ('loss', 'loss_task', 'loss_ebops', 'loss_n', 'loss_maskedE', 'n_max_pixels', 'threshold', 'ebops'):
         assert key in history.history
     plot_history(history)  # must run headless without error