Metadata-Version: 2.3
Name: spike-finn
Version: 0.1.1
Summary: Add your description here
Author: Henrik Iver Thorøe
Author-email: Henrik Iver Thorøe <henrik.thoroe@student.kit.edu>
Requires-Dist: brevitas>=0.12.1
Requires-Dist: dataclasses-json>=0.6.7
Requires-Dist: ipywidgets>=8.1.8
Requires-Dist: numpy>=1.26.4
Requires-Dist: onnx==1.18.0
Requires-Dist: onnxoptimizer>=0.4.2
Requires-Dist: onnxscript>=0.5.0
Requires-Dist: rich>=15.0.0
Requires-Dist: snntorch>=0.9.4
Requires-Dist: torch>=2.12.0
Requires-Dist: torchvision>=0.27.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Spike-FINN

Spike-FINN is a framework for training and exporting spiking neural networks (SNNs) to FPGA hardware using the FINN compiler. It provides tools for collecting parameters during the forward pass of a PyTorch model, generating reports, and converting them into HLSLayerConfig objects for use in the export process. The framework includes implementations for Leaky Integrate-and-Fire (LIF) neuron layers, allowing users to design and optimize SNNs for efficient hardware deployment.

## Prerequisites

Before you can use Spike-FINN, ensure you have the following dependencies installed:

- A local clone of [FINN](https://github.com/Xilinx/finn)
- A Vivado installation (tested for 2022.2)

## Installation

To install Spike-FINN, you can use the following command:

```bash
uv add spike-finn
```

## Project Guide

### 0. General Idea
Spike-FINN makes use of the FINN framework for accelerating neural networks on FPGA hardware.
It replaces the default computation unit with a statefull replacement, that shares all the same APIs.
The replacement unit is configured using parameters collected directly from the SNNTorch implementation
of the spiking neural network. The framework is intended to be easily extendable to support new hardware 
strategies and new spiking neuron types, by implementing new ParameterCollector and ParameterReport classes.
The default implementation is for Leaky Integrate-and-Fire (LIF) neurons, but the framework can be extended to 
support other neuron types and hardware configurations.

### 1. Parameter Collection & Export
To map a spiking neuron layer on hardware, some parameters are required. For the provided LIF example,
we need to know the threshold, number of neurons, leakage factor, reset mode and the size of the buffer 
required to store the membrane potential. These parameters are collected during the forward pass of the model
using the LIFParameterCollector, which wraps the spiking activation function. The collected parameters are
used to generate a LIFParameterReport, which can be converted into an HLSLayerConfig for use in the export process.
The export process involves converting the collected parameters into a format that can be used by the FINN compiler 
to generate the necessary hardware description for the FPGA. This allows for efficient deployment of the 
spiking neural network on FPGA hardware, leveraging the performance benefits of custom hardware acceleration.

As a user you need to wrap your spiking activation functions with the parameter collector. E.g like this:
```py
LIFParameterCollector.leaky(
    neurons=16,
    act=snn.Leaky(
        beta=beta,
        spike_grad=spike_grad,
        init_hidden=False,
        reset_mechanism="zero",
        learn_threshold=True,
    ),
)
```

A provided function then evaluates the network and collects all parameters:

```py
with collect_parameters(net) as reports:
    evaluate()
```

If different strategies should be used, a custom `ParameterCollector` can be used.


### 2. Build and Synthesis

The build process involves using the collected parameters to configure the custom 
HLS compute units in the FINN framework. Parts of the FINN compiler are overridden
to correctly include custom HLS in the build process. More details can be found 
at `src/spike_finn/finn/entrypoint.py`. Spike-FINN creates a configuration file, that 
removes semantic meaning and only contains pre-compiler directives and template parameters 
that are passed to the HLS unit. If a custom HLS implementation follows the same 
schema to configure the unit, the `entrypoint.py` file can stay as is. 

After configuration the build process is handed over to the FINN compiler, which 
generates the necessary hardware description for the FPGA. 
