sparsepixels 0.3.1__tar.gz → 0.3.3__tar.gz

sparsepixels-0.3.3/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: sparsepixels
+Version: 0.3.3
+Summary: Efficient convolution for sparse data on FPGAs
+Home-page: https://github.com/hftsoi/sparse-pixels
+Author: Ho Fung Tsoi
+Author-email: ho.fung.tsoi@cern.ch
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+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
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hftsoi/sparse-pixels/main/docs/figs/logo.png" width="300" />
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hftsoi/sparse-pixels/main/docs/figs/sparsepixels.png" width="900"/>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hftsoi/sparse-pixels/main/docs/figs/cnn_standard.gif" width="400" />
+  <img src="https://raw.githubusercontent.com/hftsoi/sparse-pixels/main/docs/figs/cnn_sparse.gif" width="400" />
+</p>
+
+# 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)
+
+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
+
+With Python >= 3.10:
+
+```
+pip install sparsepixels
+```
+
+This includes all necessary backends (tensorflow, keras, HGQ2).
+
+## 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)` 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=3)
+```
+
+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 sparsepixels.layers import InputReduce, QConv2DSparse, AveragePooling2DSparse, MaxPooling2DSparse
+
+with (
+    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')
+
+    x, keep_mask = InputReduce(
+        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)
+    x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
+                      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')(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
+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
+from sparsepixels.utils import SparseTrainingMonitor
+
+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()])
+```
+
+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_quantization(model)
+
+ir = model.get_layer('input_reduce')
+print(f"n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}")
+```
+
+## Converting a trained model to HLS with hls4ml
+
+> **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/fastmachinelearning/hls4ml.git"
+> ```
+
+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'  # "#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,
+    hls_config=hls_config,
+    output_dir='hls_proj/my_sparse_cnn',
+    backend='Vitis',
+    io_type='io_parallel',
+)
+hls_model.write()
+hls_model.compile()
+y_hls = hls_model.predict(x_test)
+```
+
+## Documentation
+
+See [here](https://hftsoi.github.io/sparse-pixels/) for documentation with walk-through guidance.
+
+## Citation
+
+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}",
+    eprint = "2512.06208",
+    archivePrefix = "arXiv",
+    primaryClass = "cs.AR",
+    doi = "10.1088/2632-2153/ae9fb5",
+    journal = "Mach. Learn. Sci. Tech.",
+    volume = "7",
+    number = "5",
+    pages = "055025",
+    year = "2026"
+}
+```

sparsepixels-0.3.3/README.md

@@ -0,0 +1,179 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hftsoi/sparse-pixels/main/docs/figs/logo.png" width="300" />
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hftsoi/sparse-pixels/main/docs/figs/sparsepixels.png" width="900"/>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hftsoi/sparse-pixels/main/docs/figs/cnn_standard.gif" width="400" />
+  <img src="https://raw.githubusercontent.com/hftsoi/sparse-pixels/main/docs/figs/cnn_sparse.gif" width="400" />
+</p>
+
+# 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)
+
+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
+
+With Python >= 3.10:
+
+```
+pip install sparsepixels
+```
+
+This includes all necessary backends (tensorflow, keras, HGQ2).
+
+## 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)` 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=3)
+```
+
+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 sparsepixels.layers import InputReduce, QConv2DSparse, AveragePooling2DSparse, MaxPooling2DSparse
+
+with (
+    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')
+
+    x, keep_mask = InputReduce(
+        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)
+    x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
+                      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')(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
+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
+from sparsepixels.utils import SparseTrainingMonitor
+
+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()])
+```
+
+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_quantization(model)
+
+ir = model.get_layer('input_reduce')
+print(f"n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}")
+```
+
+## Converting a trained model to HLS with hls4ml
+
+> **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/fastmachinelearning/hls4ml.git"
+> ```
+
+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'  # "#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,
+    hls_config=hls_config,
+    output_dir='hls_proj/my_sparse_cnn',
+    backend='Vitis',
+    io_type='io_parallel',
+)
+hls_model.write()
+hls_model.compile()
+y_hls = hls_model.predict(x_test)
+```
+
+## Documentation
+
+See [here](https://hftsoi.github.io/sparse-pixels/) for documentation with walk-through guidance.
+
+## Citation
+
+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}",
+    eprint = "2512.06208",
+    archivePrefix = "arXiv",
+    primaryClass = "cs.AR",
+    doi = "10.1088/2632-2153/ae9fb5",
+    journal = "Mach. Learn. Sci. Tech.",
+    volume = "7",
+    number = "5",
+    pages = "055025",
+    year = "2026"
+}
+```

{sparsepixels-0.3.1 → sparsepixels-0.3.3}/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.1 → sparsepixels-0.3.3}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = sparsepixels
-version = 0.3.1
+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.1 → sparsepixels-0.3.3}/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,