potnn 1.0.0__py3-none-any.whl

potnn-1.0.0.dist-info/METADATA

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: potnn
+Version: 1.0.0
+Summary: Multiplication-free neural networks for ultra-low-power MCUs
+Home-page: https://github.com/scienthoon/potnn
+Author: Scienthoon
+Author-email: scienthoon@gmail.com
+License: GPL-3.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: numpy
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# PoT-NN: Multiplication-Free Neural Networks for Ultra-Low-Power MCUs
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
+
+**PoT-NN** is a quantization framework that enables **deep learning inference without multiplication**.  
+Run neural networks on ultra-low-cost MCUs without hardware multipliers (CH32V003, PY32F003, etc.).
+
+> 🇰🇷 [한국어 문서](README_ko.md)
+
+## 🎯 Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Multiplication-Free** | All weights quantized to powers-of-two, using only `<<`, `>>`, `+` operations |
+| **Integer-Only Inference** | No floating-point operations, only `int8`/`int32` arithmetic |
+| **5 Encoding Modes** | Choose between accuracy vs. memory tradeoff |
+| **Auto C Export** | Generates standalone C header files with zero dependencies |
+| **Bit-Exact Matching** | Guaranteed 100% match between Python simulation and C code |
+
+## 📦 Installation
+
+```bash
+git clone https://github.com/YOUR_USERNAME/potnn.git
+cd potnn
+pip install -e .
+```
+
+## 🚀 Quick Start
+
+### Method 1: One-Line Training (Recommended)
+
+```python
+import torch
+import torch.nn as nn
+import potnn
+from potnn import PoTConv2d, PoTLinear
+
+# 1. Define model using PoT layers
+class TinyNet(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.conv1 = PoTConv2d(1, 8, kernel_size=3, padding=1)
+        self.conv2 = PoTConv2d(8, 16, kernel_size=3, padding=1)
+        self.pool = nn.AdaptiveAvgPool2d(1)  # Auto-replaced with PoTGlobalAvgPool
+        self.fc = PoTLinear(16, 10)
+    
+    def forward(self, x):
+        x = torch.relu(self.conv1(x))
+        x = nn.functional.max_pool2d(x, 2)
+        x = torch.relu(self.conv2(x))
+        x = self.pool(x).view(x.size(0), -1)
+        return self.fc(x)
+
+model = TinyNet()
+
+# 2. Configure
+config = potnn.Config(
+    flash=16384,      # Target MCU Flash (bytes)
+    ram=2048,         # Target MCU RAM (bytes)
+    mean=0.1307,      # Dataset mean
+    std=0.3081,       # Dataset std
+    input_h=16, input_w=16, input_channels=1,
+)
+
+# 3. Train (Float → Calibrate → QAT → Integer Sim)
+model = potnn.train(model, train_loader, test_loader, config,
+                    float_epochs=15, qat_epochs=50)
+
+# 4. Export to C
+potnn.export(model, "model.h", config)
+```
+
+### Method 2: Manual Pipeline
+
+```python
+import potnn
+
+# Step 1: Train float model (standard PyTorch training)
+train_float(model, train_loader, epochs=15)
+
+# Step 2: Fuse BatchNorm into Conv (if any)
+potnn.fuse_batchnorm(model)
+
+# Step 3: Calibrate activation scales
+potnn.calibrate(model, train_loader, config)
+
+# Step 4: Prepare for QAT
+potnn.prepare_qat(model, config)
+
+# Step 5: QAT training
+train_qat(model, train_loader, epochs=50)
+
+# Step 6: Enable integer simulation (C-compatible)
+potnn.enable_integer_sim(model, input_std=config.std, input_mean=config.mean)
+
+# Step 7: Export
+potnn.export(model, "model.h", config)
+```
+
+## 📊 Encoding Modes
+
+Choose encoding based on accuracy vs. memory tradeoff:
+
+| Encoding | Levels | Values | Bits/Weight | Best For |
+|----------|--------|--------|-------------|----------|
+| `unroll` | 17 | 0, ±1, ±2, ±4, ..., ±128 | Code-unrolled | Highest accuracy |
+| `fp130` | 16 | ±1, ±2, ±4, ..., ±128 | 4-bit | Dense layers |
+| `5level` | 5 | -8, -1, 0, +1, +8 | 4-bit (skip) | Balanced |
+| `2bit` | 4 | -2, -1, +1, +2 | 2-bit | Smallest memory |
+| `ternary` | 3 | -1, 0, +1 | 2-bit (RLE) | Sparse models |
+
+### Per-Layer Encoding
+
+```python
+config = potnn.Config(
+    flash=16384, ram=2048,
+    layer_encodings={
+        'conv1': 'unroll',  # First layer: max accuracy
+        'conv2': '5level',  # Middle layer
+        'fc': 'unroll',     # Last layer: max accuracy
+    },
+    default_encoding='5level'
+)
+```
+
+### Encoding Details
+
+#### `unroll` (Default)
+- Weights embedded directly as shift-add operations
+- Zero weights omitted entirely (sparse-friendly)
+- Largest code size, highest accuracy
+
+#### `fp130` (FP1.3.0 Format)
+- 4-bit packing: `[sign(1)][exp(3)]`
+- No zero (zeros replaced with ±1)
+- Good for dense layers
+
+#### `5level` (Skip Encoding)
+- 4-bit packing: `[skip(2)][sign(1)][mag(1)]`
+- Skip field compresses consecutive zeros (0-3)
+- **Constraint**: Max 3 consecutive zeros (4th+ replaced with +1)
+
+#### `2bit`
+- 2-bit packing: `[sign(1)][shift(1)]`
+- Smallest memory (16 weights per uint32)
+- No zero (zeros replaced with ±1)
+
+#### `ternary` (Triple-Run)
+- 2-bit codes with run-length encoding
+- `11` code = repeat previous value 2 more times
+- Best for very sparse models
+
+## 📁 Supported Layers
+
+| Layer | Class | Notes |
+|-------|-------|-------|
+| Conv2D | `PoTConv2d` | All standard parameters supported |
+| Conv1D | `PoTConv1d` | For time series |
+| Depthwise | `PoTDepthwiseConv2d` | MobileNet-style |
+| Linear | `PoTLinear` | Fully connected |
+| GAP | Auto-replaced | `nn.AdaptiveAvgPool2d(1)` → `PoTGlobalAvgPool` |
+| Add | `PoTAdd` | For residual connections |
+| BatchNorm | Auto-fused | Merged into preceding Conv/Linear |
+
+## ⚙️ API Reference
+
+### `potnn.Config`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `flash` | int | ✅ | Flash memory budget (bytes) |
+| `ram` | int | ✅ | RAM budget (bytes) |
+| `mean` | float/list | ❌ | Dataset mean (single or per-channel) |
+| `std` | float/list | ❌ | Dataset std |
+| `input_h`, `input_w` | int | ❌ | Input dimensions (default: 16×16) |
+| `input_channels` | int | ❌ | Input channels (default: 1) |
+| `layer_encodings` | dict | ❌ | Per-layer encoding override |
+| `default_encoding` | str | ❌ | Default encoding (default: 'unroll') |
+
+### Key Functions
+
+```python
+potnn.train(model, train_loader, test_loader, config, ...)  # Full pipeline
+potnn.calibrate(model, data_loader, config)                  # Calibrate scales
+potnn.prepare_qat(model, config)                             # Enable QAT mode
+potnn.enable_integer_sim(model, input_std, input_mean)       # C-compatible mode
+potnn.export(model, output_path, config)                     # Generate C code
+potnn.fuse_batchnorm(model)                                  # Fuse BN layers
+```
+
+## 🧪 Verified Results
+
+- **Bit-Exact Matching**: Python integer simulation matches C output 100%
+- **MNIST**: 97%+ accuracy with 12KB binary
+- **100-Model Stress Test**: Verified across random architectures
+
+## 📝 License
+
+**Dual License**: GPL-3.0 + Commercial
+
+| Use Case | License |
+|----------|---------|
+| Open Source Projects | GPL-3.0 (Free) |
+| Proprietary/Commercial | Commercial License (Contact us) |
+
+See [LICENSE](LICENSE) for details.
+
+## 🙏 Contributing
+
+This project was created by a solo developer without formal CS education.  
+There may be bugs, inefficiencies, or areas for improvement.
+
+**Any contributions are greatly appreciated!**
+- 🐛 Bug reports
+- 💡 Feature suggestions  
+- 🔧 Pull requests
+- 📖 Documentation improvements
+
+If you find issues or have ideas, please open an issue or PR. Thank you!
+
+---
+
+**Made with ❤️ for ultra-low-power AI**

potnn-1.0.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+potnn/__init__.py,sha256=RmM9ryV2CxB692tNaaQXwnKJ2GgfTUzbf0ubISCpciw,2561
+potnn/config.py,sha256=mR9NbbGN9q5G6wEm3vx0ODeWSHbVliyW7RHIj8uS1os,4464
+potnn/export.py,sha256=wHOWeOLd9YlN3-GFL0lIiLdZud8yPvdqtGkvy7A78L8,92313
+potnn/fuse.py,sha256=_ReCS9sk6ygQbZA7G2jS11ApAg8l6xWGxieJJ-K7L7Q,5631
+potnn/wrapper.py,sha256=zgETMT7IlkhvMo1MZBSxmG21AJ7uzgmrK1eyB8pKIlY,11889
+potnn/codegen/__init__.py,sha256=htno5WMgQlvjsDSi1fM3mSyc6N8TZCI5eXb2jQujorg,599
+potnn/codegen/bit2.py,sha256=5lTgaHsuD8J1ppqBihpXm3dUNT3ZUQ4ecKNDVel57t0,9786
+potnn/codegen/fp130.py,sha256=E3ufBvru-ZadooXfc_-2jtj7JWlmOGwGgRUDUiuuBSg,10363
+potnn/codegen/header.py,sha256=fY3s8bm47eIWtMydf2fo8V8O3eyNdMjp3P4OAbGZ4aY,18586
+potnn/codegen/level5.py,sha256=-tLPvymYQFTENuuwdl3E5f0bkKqy9XEUbcqVu7wEeFY,14733
+potnn/codegen/scale.py,sha256=N_5olynrFs8E66GWCr33iHtlH5WL9P26e2A1DDt0szE,5974
+potnn/codegen/ternary.py,sha256=-PSWa334SxVcTy23hEI_PJqK86KaQ8-Uh_TqUPLhMqI,13117
+potnn/codegen/unroll.py,sha256=-RttYPp7GMu8qFq81v0pqM4xJp09cap_2GRL8g0po2A,23251
+potnn/modules/__init__.py,sha256=TEhviXjRra7PIGTZpDQKX0tEJb8uajIjcE_fiZiHWyk,382
+potnn/modules/add.py,sha256=M_ccOyRjnLqtoYVU5bnUKMEaCLQquP6i3zNe1_nF5ks,4352
+potnn/modules/avgpool.py,sha256=eX6IgWIDlCh-wvop01aEWZN64aWg2gudhwqaaXhVOCs,6878
+potnn/modules/base.py,sha256=oWHWXV-O7NQ0N4G0GosGC8H3vaHRpljaPVcxgPEv9v0,8069
+potnn/modules/conv.py,sha256=2n_b-WCqPOriZRM-KQmgwoTpCQKmLnxzVG94AJ9EdIg,7869
+potnn/modules/conv1d.py,sha256=x1zz6sZ7qm4wW0vFYxGI2iUKbFLi81kyu2e3JnGWcMo,13257
+potnn/modules/depthwise.py,sha256=D4u1gmWESRyaqp5idWqMUJioxuWHga2FjLvgSOOzyGE,8725
+potnn/modules/linear.py,sha256=ZipAI0rbwiPEVxDAcY-AVkuf1RoxbSLk9jut6nZ573w,7910
+potnn/quantize/__init__.py,sha256=rBLPaOLE3Lcv4gvmw_CjN7AJwbz2j3CtZb5dC-K6DWA,967
+potnn/quantize/calibration.py,sha256=xBUjQwhNRie9xcG8XTyU8m5xXnD_UU1QMlre1wMBtRw,9570
+potnn/quantize/integer_ops.py,sha256=8alMYkmqOQLrwu2hx0uXU4Gaz1HnRpw_fgrL86a4TNI,7534
+potnn/quantize/integer_sim.py,sha256=pKpJ-dY_AlNW6HpyUWZ3JEKgWIJSCdA_E9DgHuNntc8,6140
+potnn/quantize/pot.py,sha256=_x86v3BXpIe17jZjvTy3Ozd3Mlumw4hH9yUXazd0YCI,14705
+potnn/quantize/qat.py,sha256=6ozzrH1IiSH5Oj1qDpVTJ2-LG4Lf7daKF4t4DM0XRK4,13629
+potnn/utils/__init__.py,sha256=OTwUq1x-nRfC-ZnR1ZGvJX-gb_aaAXLwYFBdO9xnHvs,352
+potnn/utils/allocation.py,sha256=swIfoOEl2pbt0Cf-W_5Za1qAva8OTBS9wfCwKGCCZX8,7731
+potnn/utils/memory.py,sha256=xuLYnOfh7WcfOkEikZb1pSMBdXwD_mUwuQG0Gc9dEBs,5110
+potnn-1.0.0.dist-info/licenses/LICENSE,sha256=cZZ65pYx8hdCtK3VRVbUiI5NaFsNHrq195NuctTSmtU,2731
+potnn-1.0.0.dist-info/METADATA,sha256=bS24-cfZo2yw8T05-O8SRLAty5ky78fyDFC2XW_JRm0,8393
+potnn-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+potnn-1.0.0.dist-info/top_level.txt,sha256=fc3uRsXRimIAyDiapfFVH2jm9bL14fZziC7Y5isAsJU,6
+potnn-1.0.0.dist-info/RECORD,,

potnn-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

potnn-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,72 @@
+PoT-NN Dual License
+====================
+
+This software is available under a dual license model:
+
+1. GNU General Public License v3.0 (GPL-3.0) - For open source use
+2. Commercial License - For proprietary/closed-source use
+
+--------------------------------------------------------------------------------
+
+OPTION 1: GPL-3.0 (Open Source)
+--------------------------------
+
+Copyright (c) 2026 PoT-NN Developers
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+**Summary of GPL-3.0 Requirements:**
+- You must disclose your source code if you distribute the software
+- Derivative works must also be licensed under GPL-3.0
+- You must include the original copyright notice
+- Changes to the code must be documented
+
+--------------------------------------------------------------------------------
+
+OPTION 2: Commercial License
+-----------------------------
+
+For companies and individuals who wish to use PoT-NN in proprietary products
+without the obligations of the GPL license, a commercial license is available.
+
+**Commercial License Benefits:**
+- Use in closed-source products
+- No requirement to disclose your source code
+- No copyleft obligations
+- Priority support available
+
+**To obtain a commercial license, please contact:**
+- Email: [YOUR_EMAIL@example.com]
+- Website: [YOUR_WEBSITE]
+
+--------------------------------------------------------------------------------
+
+Which License Applies to You?
+------------------------------
+
+- **Open Source Projects**: If your project is open source and will be
+  distributed under GPL-3.0 or a compatible license, you can use PoT-NN
+  for free under the GPL-3.0 license.
+
+- **Commercial/Proprietary Use**: If you want to use PoT-NN in a proprietary
+  product without releasing your source code, you need a commercial license.
+
+- **Internal Use**: If you're only using PoT-NN internally and not distributing
+  it, GPL-3.0 does not require you to release your source code. However, if
+  you want dedicated support or prefer clear legal terms, consider a
+  commercial license.
+
+--------------------------------------------------------------------------------
+
+Full GPL-3.0 License Text: https://www.gnu.org/licenses/gpl-3.0.txt

potnn-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+potnn