sparsepixels 0.1.0__tar.gz → 0.2.0__tar.gz

sparsepixels-0.2.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: sparsepixels
+Version: 0.2.0
+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
+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
+
+[![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)
+
+> **Note:** We are actively working on hls4ml integration to auto-convert sparse models to HLS, along with a major upgrade with partial parallelization and streaming for sparse layers in HLS. Stay tuned!
+
+## Installation
+
+With Python >= 3.10:
+
+```
+pip install sparsepixels
+```
+
+## Getting Started
+
+Import sparse layers and quantization library (HGQ2):
+
+```python
+import keras
+from keras.layers import Flatten, Activation, ReLU
+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
+```
+
+Build an example sparse CNN within HGQ2 quantization scopes:
+
+```python
+with (
+    QuantizerConfigScope(place='all', default_q_type='kbi', overflow_mode='SAT_SYM'),
+    QuantizerConfigScope(place='datalane', default_q_type='kif', overflow_mode='WRAP'),
+    LayerConfigScope(enable_ebops=False, enable_iq=False),
+):
+    x_in = keras.Input(shape=(x_train.shape[1], x_train.shape[2], x_train.shape[3]), name='x_in')
+
+    # Sparse input reduction: retain up to n_max_pixels active pixels
+    x, keep_mask = InputReduce(n_max_pixels=20, threshold=0.1, name='input_reduce')(x_in)
+
+    # Sparse convolution
+    x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
+                      bq_conf=QuantizerConfig('default', 'bias'))([x, keep_mask])
+    x = ReLU(name='relu1')(x)
+
+    # Sparse pooling
+    x, keep_mask = AveragePooling2DSparse(2, name='pool1')([x, keep_mask])
+
+    x = Flatten(name='flatten')(x)
+    x = QDense(10, name='dense1', activation='relu')(x)
+    x = Activation('softmax', name='softmax')(x)
+
+model = keras.Model(x_in, x)
+```
+
+We are working on hls4ml integration that auto parses the sparse layers into HLS.
+
+## Documentation
+
+## 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",
+    month = "12",
+    year = "2025"
+}
+```
+

sparsepixels-0.2.0/README.md

@@ -0,0 +1,89 @@
+<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
+
+[![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)
+
+> **Note:** We are actively working on hls4ml integration to auto-convert sparse models to HLS, along with a major upgrade with partial parallelization and streaming for sparse layers in HLS. Stay tuned!
+
+## Installation
+
+With Python >= 3.10:
+
+```
+pip install sparsepixels
+```
+
+## Getting Started
+
+Import sparse layers and quantization library (HGQ2):
+
+```python
+import keras
+from keras.layers import Flatten, Activation, ReLU
+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
+```
+
+Build an example sparse CNN within HGQ2 quantization scopes:
+
+```python
+with (
+    QuantizerConfigScope(place='all', default_q_type='kbi', overflow_mode='SAT_SYM'),
+    QuantizerConfigScope(place='datalane', default_q_type='kif', overflow_mode='WRAP'),
+    LayerConfigScope(enable_ebops=False, enable_iq=False),
+):
+    x_in = keras.Input(shape=(x_train.shape[1], x_train.shape[2], x_train.shape[3]), name='x_in')
+
+    # Sparse input reduction: retain up to n_max_pixels active pixels
+    x, keep_mask = InputReduce(n_max_pixels=20, threshold=0.1, name='input_reduce')(x_in)
+
+    # Sparse convolution
+    x = QConv2DSparse(filters=3, kernel_size=3, name='conv1', padding='same', strides=1,
+                      bq_conf=QuantizerConfig('default', 'bias'))([x, keep_mask])
+    x = ReLU(name='relu1')(x)
+
+    # Sparse pooling
+    x, keep_mask = AveragePooling2DSparse(2, name='pool1')([x, keep_mask])
+
+    x = Flatten(name='flatten')(x)
+    x = QDense(10, name='dense1', activation='relu')(x)
+    x = Activation('softmax', name='softmax')(x)
+
+model = keras.Model(x_in, x)
+```
+
+We are working on hls4ml integration that auto parses the sparse layers into HLS.
+
+## Documentation
+
+## 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",
+    month = "12",
+    year = "2025"
+}
+```
+