sparsepixels 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sparsepixels
-Version: 0.3.0
+Version: 0.3.1
 Summary: Efficient convolution for sparse data on FPGAs
 Home-page: https://github.com/hftsoi/sparse-pixels
 Author: Ho Fung Tsoi
@@ -47,20 +47,16 @@ pip install sparsepixels
 
 ## Getting Started
 
-Import the sparse layers, the quantization library (HGQ2), and the training utilities:
-
 ```python
 import keras
 from keras.layers import Flatten, Activation
-from hgq.layers import QConv2D, QDense
+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
 from sparsepixels.utils import (
-    active_pixels_vs_threshold, plot_reduced_examples,
-    set_sparse_ebops_factor, cosine_lr,
-    SparseTrainingMonitor, plot_history,
-    print_quantization, plot_quantization,
+    active_pixels_vs_threshold, plot_reduced_examples, cosine_lr,
+    SparseTrainingMonitor, plot_history, print_quantization, plot_quantization,
 )
 ```
 
@@ -112,31 +108,34 @@ with (
 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 and the EBOPS each epoch, and it corrects the EBOPS (a proxy for the quantized
+hardware cost) to the sparse compute automatically, so no extra setup is needed. The
+only sparse-specific choices are the cosine-decayed learning rate and `restore_best_weights`, which
+keep the learned budget from over-compressing near the end of training.
 
 ```python
-set_sparse_ebops_factor(model)
-
-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(cosine_lr(1e-3, epochs=100, steps_per_epoch=len(x_train) // 128)),
     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 and read out the learned sparsity to deploy. `plot_history`
+shows the loss breakdown, the learned budget/threshold and the EBOPS in one figure.
+`print_quantization` / `plot_quantization` summarize the per-layer bit-widths. The values to
+deploy are `layer.n_max_pixels` and `layer.threshold` (hls4ml converter will auto-parse these from the model).
+
+```python
 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
@@ -147,13 +146,31 @@ print(f"deploy with n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}
 > 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"
+
+# Optional per-layer parallelization knobs. Omit them for the fully-parallel, lowest-latency default.
+#   input_reduce  Variant             : 'tree' (default, lowest latency) or 'stream' (fewer resources)
+#   conv*         PixelParallelFactor : active pixels in parallel (<= n_max_pixels)
+#                 FiltParallelFactor  : filters in parallel (<= that conv's filters)
+#   pool*         PixelParallelFactor : active pixels in parallel
+#                 ChanParallelFactor  : channels in parallel
+#   flatten       ParallelFactor      : scatter positions in parallel (<= out_height * out_width)
+n_sparse = model.get_layer('input_reduce').n_max_pixels
+knobs = {
+    'input_reduce': {'Variant': 'stream'},
+    'conv1':   {'PixelParallelFactor': n_sparse, 'FiltParallelFactor': 3},
+    'pool1':   {'PixelParallelFactor': n_sparse, 'ChanParallelFactor': 3},
+    'flatten': {'ParallelFactor': 14 * 14},  # this model pools 28*28 -> 14*14
+}
+for name, cfg in knobs.items():
+    hls_config['LayerName'].setdefault(name, {}).update(cfg)
 
 hls_model = hls4ml.converters.convert_from_keras_model(
     model,

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

@@ -28,20 +28,16 @@ pip install sparsepixels
 
 ## Getting Started
 
-Import the sparse layers, the quantization library (HGQ2), and the training utilities:
-
 ```python
 import keras
 from keras.layers import Flatten, Activation
-from hgq.layers import QConv2D, QDense
+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
 from sparsepixels.utils import (
-    active_pixels_vs_threshold, plot_reduced_examples,
-    set_sparse_ebops_factor, cosine_lr,
-    SparseTrainingMonitor, plot_history,
-    print_quantization, plot_quantization,
+    active_pixels_vs_threshold, plot_reduced_examples, cosine_lr,
+    SparseTrainingMonitor, plot_history, print_quantization, plot_quantization,
 )
 ```
 
@@ -93,31 +89,34 @@ with (
 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 and the EBOPS each epoch, and it corrects the EBOPS (a proxy for the quantized
+hardware cost) to the sparse compute automatically, so no extra setup is needed. The
+only sparse-specific choices are the cosine-decayed learning rate and `restore_best_weights`, which
+keep the learned budget from over-compressing near the end of training.
 
 ```python
-set_sparse_ebops_factor(model)
-
-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(cosine_lr(1e-3, epochs=100, steps_per_epoch=len(x_train) // 128)),
     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 and read out the learned sparsity to deploy. `plot_history`
+shows the loss breakdown, the learned budget/threshold and the EBOPS in one figure.
+`print_quantization` / `plot_quantization` summarize the per-layer bit-widths. The values to
+deploy are `layer.n_max_pixels` and `layer.threshold` (hls4ml converter will auto-parse these from the model).
+
+```python
 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
@@ -128,13 +127,31 @@ print(f"deploy with n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}
 > 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"
+
+# Optional per-layer parallelization knobs. Omit them for the fully-parallel, lowest-latency default.
+#   input_reduce  Variant             : 'tree' (default, lowest latency) or 'stream' (fewer resources)
+#   conv*         PixelParallelFactor : active pixels in parallel (<= n_max_pixels)
+#                 FiltParallelFactor  : filters in parallel (<= that conv's filters)
+#   pool*         PixelParallelFactor : active pixels in parallel
+#                 ChanParallelFactor  : channels in parallel
+#   flatten       ParallelFactor      : scatter positions in parallel (<= out_height * out_width)
+n_sparse = model.get_layer('input_reduce').n_max_pixels
+knobs = {
+    'input_reduce': {'Variant': 'stream'},
+    'conv1':   {'PixelParallelFactor': n_sparse, 'FiltParallelFactor': 3},
+    'pool1':   {'PixelParallelFactor': n_sparse, 'ChanParallelFactor': 3},
+    'flatten': {'ParallelFactor': 14 * 14},  # this model pools 28*28 -> 14*14
+}
+for name, cfg in knobs.items():
+    hls_config['LayerName'].setdefault(name, {}).update(cfg)
 
 hls_model = hls4ml.converters.convert_from_keras_model(
     model,

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

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

@@ -49,9 +49,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.
     """
@@ -157,12 +158,19 @@ 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).
+    - 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: 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.
     """
 
+    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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sparsepixels
-Version: 0.3.0
+Version: 0.3.1
 Summary: Efficient convolution for sparse data on FPGAs
 Home-page: https://github.com/hftsoi/sparse-pixels
 Author: Ho Fung Tsoi
@@ -47,20 +47,16 @@ pip install sparsepixels
 
 ## Getting Started
 
-Import the sparse layers, the quantization library (HGQ2), and the training utilities:
-
 ```python
 import keras
 from keras.layers import Flatten, Activation
-from hgq.layers import QConv2D, QDense
+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
 from sparsepixels.utils import (
-    active_pixels_vs_threshold, plot_reduced_examples,
-    set_sparse_ebops_factor, cosine_lr,
-    SparseTrainingMonitor, plot_history,
-    print_quantization, plot_quantization,
+    active_pixels_vs_threshold, plot_reduced_examples, cosine_lr,
+    SparseTrainingMonitor, plot_history, print_quantization, plot_quantization,
 )
 ```
 
@@ -112,31 +108,34 @@ with (
 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 and the EBOPS each epoch, and it corrects the EBOPS (a proxy for the quantized
+hardware cost) to the sparse compute automatically, so no extra setup is needed. The
+only sparse-specific choices are the cosine-decayed learning rate and `restore_best_weights`, which
+keep the learned budget from over-compressing near the end of training.
 
 ```python
-set_sparse_ebops_factor(model)
-
-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(cosine_lr(1e-3, epochs=100, steps_per_epoch=len(x_train) // 128)),
     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 and read out the learned sparsity to deploy. `plot_history`
+shows the loss breakdown, the learned budget/threshold and the EBOPS in one figure.
+`print_quantization` / `plot_quantization` summarize the per-layer bit-widths. The values to
+deploy are `layer.n_max_pixels` and `layer.threshold` (hls4ml converter will auto-parse these from the model).
+
+```python
 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
@@ -147,13 +146,31 @@ print(f"deploy with n_max_pixels={ir.n_max_pixels}, threshold={ir.threshold:.3f}
 > 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"
+
+# Optional per-layer parallelization knobs. Omit them for the fully-parallel, lowest-latency default.
+#   input_reduce  Variant             : 'tree' (default, lowest latency) or 'stream' (fewer resources)
+#   conv*         PixelParallelFactor : active pixels in parallel (<= n_max_pixels)
+#                 FiltParallelFactor  : filters in parallel (<= that conv's filters)
+#   pool*         PixelParallelFactor : active pixels in parallel
+#                 ChanParallelFactor  : channels in parallel
+#   flatten       ParallelFactor      : scatter positions in parallel (<= out_height * out_width)
+n_sparse = model.get_layer('input_reduce').n_max_pixels
+knobs = {
+    'input_reduce': {'Variant': 'stream'},
+    'conv1':   {'PixelParallelFactor': n_sparse, 'FiltParallelFactor': 3},
+    'pool1':   {'PixelParallelFactor': n_sparse, 'ChanParallelFactor': 3},
+    'flatten': {'ParallelFactor': 14 * 14},  # this model pools 28*28 -> 14*14
+}
+for name, cfg in knobs.items():
+    hls_config['LayerName'].setdefault(name, {}).update(cfg)
 
 hls_model = hls4ml.converters.convert_from_keras_model(
     model,