# StreamHLS Compiler
[](https://badge.fury.io/py/streamhls-compiler)
[](https://www.python.org/downloads/)
**Compile PyTorch models to HLS deployment packages with one line of code.**
StreamHLS Compiler is a Python package that automatically converts PyTorch neural network models into optimized HLS (High-Level Synthesis) C++ code for FPGA deployment, using the Stream-HLS compilation framework.
## Features
✨ **One-Line Compilation** - Convert any PyTorch model to HLS with a single function call
🚀 **Automatic Optimization** - Built-in optimization levels (0-5) for performance tuning
📦 **MNIST_deployment Format** - Outputs ready-to-synthesize deployment packages
🎯 **Compile-Only Mode** - Skip Vitis HLS synthesis for faster iteration
🔧 **Weight Embedding** - Automatically embeds trained weights into generated code
## Installation
### Prerequisites
1. **Stream-HLS Repository** must be installed:
```bash
git clone https://github.com/ayushkumar1808/Stream-HLS.git
export STREAMHLS_REPO=/path/to/Stream-HLS
```
2. **Python 3.8+** with PyTorch
### Install from PyPI
```bash
pip install streamhls-compiler
```
### Install from Source
```bash
git clone https://github.com/ayushkumar1808/streamhls-compiler.git
cd streamhls-compiler
pip install -e .
```
## Quick Start
### Basic Usage
```python
import torch
import torch.nn as nn
from streamhls import compile_model
# Define your PyTorch model
class MyModel(nn.Module):
def __init__(self):
super().__init__()
self.fc1 = nn.Linear(784, 128)
self.fc2 = nn.Linear(128, 10)
def forward(self, x):
x = torch.relu(self.fc1(x))
return self.fc2(x)
# Create and compile
model = MyModel()
report = compile_model(
model=model,
input_shape=(1, 784),
output_dir="./MyModel_deployment",
model_name="MyModel",
opt_level=0
)
print(f"✅ Deployment package created at: {report['output_dir']}")
```
### Using the StreamHLSModel Base Class
```python
from streamhls import StreamHLSModel
class MyModel(StreamHLSModel):
def __init__(self):
super().__init__()
self.conv1 = nn.Conv2d(3, 32, 3)
self.conv2 = nn.Conv2d(32, 64, 3)
self.fc = nn.Linear(64 * 6 * 6, 10)
def forward(self, x):
x = torch.relu(self.conv1(x))
x = torch.relu(self.conv2(x))
x = x.view(-1, 64 * 6 * 6)
return self.fc(x)
# Compile directly from model
model = MyModel()
model.compile_to_hls(
input_shape=(1, 3, 32, 32),
output_dir="./MyModel_deployment",
opt_level=0
)
```
## API Reference
### `compile_model()`
Main compilation function.
```python
compile_model(
model: torch.nn.Module,
input_shape: Tuple[int, ...],
output_dir: str,
model_name: str = "Model",
opt_level: int = 0,
dsps: int = 7680,
weights_path: Optional[str] = None,
verbose: bool = True
) -> dict
```
**Parameters:**
- `model` (torch.nn.Module): PyTorch model to compile
- `input_shape` (Tuple[int, ...]): Input tensor shape, e.g., `(1, 784)` or `(1, 3, 32, 32)`
- `output_dir` (str): Output directory for deployment package
- `model_name` (str): Name of the model (default: "Model")
- `opt_level` (int): Optimization level 0-5 (default: 0)
- `0`: No optimization (fastest compilation)
- `3`: Parallelization optimization (recommended)
- `5`: Full optimization (slowest, best performance)
- `dsps` (int): Number of DSPs available (default: 7680)
- `weights_path` (str, optional): Path to pretrained weights `.pth` file
- `verbose` (bool): Print compilation progress (default: True)
**Returns:**
Dictionary with compilation report:
```python
{
"model_name": str,
"input_shape": tuple,
"opt_level": int,
"output_dir": str,
"hls_src": str, # Path to HLS C++ source
"mlir_files": str, # Path to MLIR intermediates
"success": bool
}
```
## Output Structure
The compilation creates a deployment package in **MNIST_deployment format**:
```
MyModel_deployment/
├── hls/
│ ├── src/ # HLS C++ source code
│ │ ├── kernel.cpp
│ │ ├── kernel.h
│ │ └── run.tcl # Vitis HLS script
│ └── data/ # Golden output data
│ └── output.dat
├── mlir/ # MLIR intermediate files
│ ├── kernel/
│ ├── host/
│ └── graphs/
├── metadata.json # Compilation metadata
└── README.md # Deployment guide
```
## Optimization Levels
| Level | Description | Use Case |
|-------|-------------|----------|
| 0 | No optimization | Fast iteration, debugging |
| 1 | Basic optimizations | Testing |
| 2 | Permutation optimization | Moderate performance |
| 3 | Parallelization | **Recommended for most cases** |
| 4 | Permutation + Parallelization | High performance |
| 5 | Full optimization | Maximum performance |
## Examples
### Convolutional Neural Network
```python
from streamhls import compile_model
import torch.nn as nn
class SimpleCNN(nn.Module):
def __init__(self):
super().__init__()
self.conv1 = nn.Conv2d(3, 16, kernel_size=3)
self.conv2 = nn.Conv2d(16, 32, kernel_size=3)
self.fc = nn.Linear(32 * 6 * 6, 10)
def forward(self, x):
x = torch.relu(self.conv1(x))
x = torch.relu(self.conv2(x))
x = x.view(x.size(0), -1)
return self.fc(x)
model = SimpleCNN()
compile_model(
model=model,
input_shape=(1, 3, 32, 32),
output_dir="./CNN_deployment",
model_name="SimpleCNN",
opt_level=3 # Use parallelization
)
```
### With Pretrained Weights
```python
# Train your model
model = MyModel()
# ... training code ...
torch.save(model.state_dict(), "trained_weights.pth")
# Compile with trained weights
compile_model(
model=model,
input_shape=(1, 784),
output_dir="./MyModel_deployment",
model_name="MyModel",
weights_path="trained_weights.pth",
opt_level=3
)
```
## Environment Variables
- `STREAMHLS_REPO`: Path to Stream-HLS repository (required)
```bash
export STREAMHLS_REPO=/path/to/Stream-HLS
```
## Troubleshooting
### "Stream-HLS repository not found"
Set the `STREAMHLS_REPO` environment variable:
```bash
export STREAMHLS_REPO=/path/to/Stream-HLS
```
### Compilation Fails
1. Check that Stream-HLS is properly installed
2. Ensure your model is compatible (no unsupported operations)
3. Try with `opt_level=0` first for debugging
4. Set `verbose=True` to see detailed output
## Limitations
- Currently supports compile-only mode (no Vitis HLS synthesis via Python API)
- Some PyTorch operations may not be supported
- Model forward pass must be traceable
## Roadmap
- [ ] Automatic model code generation from torch.jit.script
- [ ] Support for more PyTorch operations
- [ ] CLI interface
- [ ] Batch compilation
- [ ] Vitis HLS synthesis integration
- [ ] Performance profiling tools
## Contributing
Contributions welcome! Please open an issue or submit a PR.
## License
MIT License - see LICENSE file for details
## Citation
If you use StreamHLS Compiler in your research, please cite:
```bibtex
@software{streamhls_compiler,
author = {Kumar, Ayush},
title = {StreamHLS Compiler: PyTorch to HLS Deployment},
year = {2025},
url = {https://github.com/ayushkumar1808/streamhls-compiler}
}
```
## Acknowledgments
Built on top of the [Stream-HLS](https://github.com/ayushkumar1808/Stream-HLS) compilation framework.
---
**Made with ❤️ by Ayush Kumar**
Raw data
{
"_id": null,
"home_page": "https://github.com/ayushkumar1808/Stream-HLS",
"name": "configai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "pytorch, hls, fpga, compiler, mlir, configai",
"author": "Ayush Kumar",
"author_email": "Ayush Kumar <ayush@example.com>",
"download_url": "https://files.pythonhosted.org/packages/58/5d/15d804efbf4fae4a65b60ea2d75b86bc51e0b147c383978d3d816186a98f/configai-0.1.1.tar.gz",
"platform": null,
"description": "# StreamHLS Compiler\n\n[](https://badge.fury.io/py/streamhls-compiler)\n[](https://www.python.org/downloads/)\n\n**Compile PyTorch models to HLS deployment packages with one line of code.**\n\nStreamHLS Compiler is a Python package that automatically converts PyTorch neural network models into optimized HLS (High-Level Synthesis) C++ code for FPGA deployment, using the Stream-HLS compilation framework.\n\n## Features\n\n\u2728 **One-Line Compilation** - Convert any PyTorch model to HLS with a single function call\n\n\ud83d\ude80 **Automatic Optimization** - Built-in optimization levels (0-5) for performance tuning\n\n\ud83d\udce6 **MNIST_deployment Format** - Outputs ready-to-synthesize deployment packages\n\n\ud83c\udfaf **Compile-Only Mode** - Skip Vitis HLS synthesis for faster iteration\n\n\ud83d\udd27 **Weight Embedding** - Automatically embeds trained weights into generated code\n\n## Installation\n\n### Prerequisites\n\n1. **Stream-HLS Repository** must be installed:\n```bash\ngit clone https://github.com/ayushkumar1808/Stream-HLS.git\nexport STREAMHLS_REPO=/path/to/Stream-HLS\n```\n\n2. **Python 3.8+** with PyTorch\n\n### Install from PyPI\n\n```bash\npip install streamhls-compiler\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/ayushkumar1808/streamhls-compiler.git\ncd streamhls-compiler\npip install -e .\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport torch\nimport torch.nn as nn\nfrom streamhls import compile_model\n\n# Define your PyTorch model\nclass MyModel(nn.Module):\n def __init__(self):\n super().__init__()\n self.fc1 = nn.Linear(784, 128)\n self.fc2 = nn.Linear(128, 10)\n \n def forward(self, x):\n x = torch.relu(self.fc1(x))\n return self.fc2(x)\n\n# Create and compile\nmodel = MyModel()\n\nreport = compile_model(\n model=model,\n input_shape=(1, 784),\n output_dir=\"./MyModel_deployment\",\n model_name=\"MyModel\",\n opt_level=0\n)\n\nprint(f\"\u2705 Deployment package created at: {report['output_dir']}\")\n```\n\n### Using the StreamHLSModel Base Class\n\n```python\nfrom streamhls import StreamHLSModel\n\nclass MyModel(StreamHLSModel):\n def __init__(self):\n super().__init__()\n self.conv1 = nn.Conv2d(3, 32, 3)\n self.conv2 = nn.Conv2d(32, 64, 3)\n self.fc = nn.Linear(64 * 6 * 6, 10)\n \n def forward(self, x):\n x = torch.relu(self.conv1(x))\n x = torch.relu(self.conv2(x))\n x = x.view(-1, 64 * 6 * 6)\n return self.fc(x)\n\n# Compile directly from model\nmodel = MyModel()\nmodel.compile_to_hls(\n input_shape=(1, 3, 32, 32),\n output_dir=\"./MyModel_deployment\",\n opt_level=0\n)\n```\n\n## API Reference\n\n### `compile_model()`\n\nMain compilation function.\n\n```python\ncompile_model(\n model: torch.nn.Module,\n input_shape: Tuple[int, ...],\n output_dir: str,\n model_name: str = \"Model\",\n opt_level: int = 0,\n dsps: int = 7680,\n weights_path: Optional[str] = None,\n verbose: bool = True\n) -> dict\n```\n\n**Parameters:**\n\n- `model` (torch.nn.Module): PyTorch model to compile\n- `input_shape` (Tuple[int, ...]): Input tensor shape, e.g., `(1, 784)` or `(1, 3, 32, 32)`\n- `output_dir` (str): Output directory for deployment package\n- `model_name` (str): Name of the model (default: \"Model\")\n- `opt_level` (int): Optimization level 0-5 (default: 0)\n - `0`: No optimization (fastest compilation)\n - `3`: Parallelization optimization (recommended)\n - `5`: Full optimization (slowest, best performance)\n- `dsps` (int): Number of DSPs available (default: 7680)\n- `weights_path` (str, optional): Path to pretrained weights `.pth` file\n- `verbose` (bool): Print compilation progress (default: True)\n\n**Returns:**\n\nDictionary with compilation report:\n```python\n{\n \"model_name\": str,\n \"input_shape\": tuple,\n \"opt_level\": int,\n \"output_dir\": str,\n \"hls_src\": str, # Path to HLS C++ source\n \"mlir_files\": str, # Path to MLIR intermediates\n \"success\": bool\n}\n```\n\n## Output Structure\n\nThe compilation creates a deployment package in **MNIST_deployment format**:\n\n```\nMyModel_deployment/\n\u251c\u2500\u2500 hls/\n\u2502 \u251c\u2500\u2500 src/ # HLS C++ source code\n\u2502 \u2502 \u251c\u2500\u2500 kernel.cpp\n\u2502 \u2502 \u251c\u2500\u2500 kernel.h\n\u2502 \u2502 \u2514\u2500\u2500 run.tcl # Vitis HLS script\n\u2502 \u2514\u2500\u2500 data/ # Golden output data\n\u2502 \u2514\u2500\u2500 output.dat\n\u251c\u2500\u2500 mlir/ # MLIR intermediate files\n\u2502 \u251c\u2500\u2500 kernel/\n\u2502 \u251c\u2500\u2500 host/\n\u2502 \u2514\u2500\u2500 graphs/\n\u251c\u2500\u2500 metadata.json # Compilation metadata\n\u2514\u2500\u2500 README.md # Deployment guide\n```\n\n## Optimization Levels\n\n| Level | Description | Use Case |\n|-------|-------------|----------|\n| 0 | No optimization | Fast iteration, debugging |\n| 1 | Basic optimizations | Testing |\n| 2 | Permutation optimization | Moderate performance |\n| 3 | Parallelization | **Recommended for most cases** |\n| 4 | Permutation + Parallelization | High performance |\n| 5 | Full optimization | Maximum performance |\n\n## Examples\n\n### Convolutional Neural Network\n\n```python\nfrom streamhls import compile_model\nimport torch.nn as nn\n\nclass SimpleCNN(nn.Module):\n def __init__(self):\n super().__init__()\n self.conv1 = nn.Conv2d(3, 16, kernel_size=3)\n self.conv2 = nn.Conv2d(16, 32, kernel_size=3)\n self.fc = nn.Linear(32 * 6 * 6, 10)\n \n def forward(self, x):\n x = torch.relu(self.conv1(x))\n x = torch.relu(self.conv2(x))\n x = x.view(x.size(0), -1)\n return self.fc(x)\n\nmodel = SimpleCNN()\ncompile_model(\n model=model,\n input_shape=(1, 3, 32, 32),\n output_dir=\"./CNN_deployment\",\n model_name=\"SimpleCNN\",\n opt_level=3 # Use parallelization\n)\n```\n\n### With Pretrained Weights\n\n```python\n# Train your model\nmodel = MyModel()\n# ... training code ...\ntorch.save(model.state_dict(), \"trained_weights.pth\")\n\n# Compile with trained weights\ncompile_model(\n model=model,\n input_shape=(1, 784),\n output_dir=\"./MyModel_deployment\",\n model_name=\"MyModel\",\n weights_path=\"trained_weights.pth\",\n opt_level=3\n)\n```\n\n## Environment Variables\n\n- `STREAMHLS_REPO`: Path to Stream-HLS repository (required)\n\n```bash\nexport STREAMHLS_REPO=/path/to/Stream-HLS\n```\n\n## Troubleshooting\n\n### \"Stream-HLS repository not found\"\n\nSet the `STREAMHLS_REPO` environment variable:\n\n```bash\nexport STREAMHLS_REPO=/path/to/Stream-HLS\n```\n\n### Compilation Fails\n\n1. Check that Stream-HLS is properly installed\n2. Ensure your model is compatible (no unsupported operations)\n3. Try with `opt_level=0` first for debugging\n4. Set `verbose=True` to see detailed output\n\n## Limitations\n\n- Currently supports compile-only mode (no Vitis HLS synthesis via Python API)\n- Some PyTorch operations may not be supported\n- Model forward pass must be traceable\n\n## Roadmap\n\n- [ ] Automatic model code generation from torch.jit.script\n- [ ] Support for more PyTorch operations\n- [ ] CLI interface\n- [ ] Batch compilation\n- [ ] Vitis HLS synthesis integration\n- [ ] Performance profiling tools\n\n## Contributing\n\nContributions welcome! Please open an issue or submit a PR.\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Citation\n\nIf you use StreamHLS Compiler in your research, please cite:\n\n```bibtex\n@software{streamhls_compiler,\n author = {Kumar, Ayush},\n title = {StreamHLS Compiler: PyTorch to HLS Deployment},\n year = {2025},\n url = {https://github.com/ayushkumar1808/streamhls-compiler}\n}\n```\n\n## Acknowledgments\n\nBuilt on top of the [Stream-HLS](https://github.com/ayushkumar1808/Stream-HLS) compilation framework.\n\n---\n\n**Made with \u2764\ufe0f by Ayush Kumar**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "PyTorch to HLS deployment compiler powered by Stream-HLS",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/ayushkumar1808/Stream-HLS",
"Repository": "https://github.com/ayushkumar1808/Stream-HLS"
},
"split_keywords": [
"pytorch",
" hls",
" fpga",
" compiler",
" mlir",
" configai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5aad5a53b3dc5562a84e1a1a701f1ae02bac526a5b375e8e1ca7a8835f57e3dd",
"md5": "7589c596eb757afb1d8b8b5cec0433ff",
"sha256": "6b384e656f7eb86968835769a84b83d4e09d8c6a5ddea1325cb87b3128c106f9"
},
"downloads": -1,
"filename": "configai-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7589c596eb757afb1d8b8b5cec0433ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9855,
"upload_time": "2025-10-12T10:26:34",
"upload_time_iso_8601": "2025-10-12T10:26:34.948887Z",
"url": "https://files.pythonhosted.org/packages/5a/ad/5a53b3dc5562a84e1a1a701f1ae02bac526a5b375e8e1ca7a8835f57e3dd/configai-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "585d15d804efbf4fae4a65b60ea2d75b86bc51e0b147c383978d3d816186a98f",
"md5": "15a50b51df45ec1e4aeb911a6141de26",
"sha256": "d9ecb5f6447684fa47c726c28c6ba2d81d6f912d8e0dd493a9d10d8661782ff1"
},
"downloads": -1,
"filename": "configai-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "15a50b51df45ec1e4aeb911a6141de26",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9930,
"upload_time": "2025-10-12T10:26:36",
"upload_time_iso_8601": "2025-10-12T10:26:36.745539Z",
"url": "https://files.pythonhosted.org/packages/58/5d/15d804efbf4fae4a65b60ea2d75b86bc51e0b147c383978d3d816186a98f/configai-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 10:26:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ayushkumar1808",
"github_project": "Stream-HLS",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
"==",
"1.26.0"
]
]
},
{
"name": "torch",
"specs": []
},
{
"name": "torch-mlir",
"specs": []
}
],
"lcname": "configai"
}
JSON
