SNN Mapping

This repository contains a Python project for training, evaluating, and exporting spiking neural networks (SNNs) for hardware-oriented deployment. The repository combines PyTorch, SpikingJelly, and custom export utilities to turn trained models into memory-oriented artifacts that can be mapped to a neuromorphic or custom accelerator platform. The current implementation focuses on the NMNIST dataset and SpikingJelly-style neuron layers, but the design is intended to be extensible to other datasets and SNN architectures. The project is research-oriented, but it also provides a production workflow for exporting trained SNNs into structured memory files and headers suitable for hardware integration. This repository was developed as part of a research project on mapping Spiking Neural Networks to neuromorphic hardware, and it is intended to serve both as a reference implementation and a starting point for further experimentation. It was tested together with a custom firmware implementation for the SparkRV project, which can be found here.

Project pipeline

The project is centered on the following pipeline:

1. Train or load an SNN model from event-based or frame-based datasets.
2. Evaluate the model in simulation.
3. Extract weights, biases, and neuron parameters.
4. Export them into structured memory files, headers, and binary artifacts for downstream hardware use.

The repository is therefore both a research and prototyping codebase: it contains training scripts for SNN experiments, utilities for model export, and support code for analyzing and serializing network parameters.

Repository structure

• core: the core implementation of the project. This package contains the modules responsible for exporting trained models, saving and formatting parameters for deployment, and profiling SNN behavior.
• export: generated export artifacts such as memory files, headers, and configuration files produced by the export pipeline.
• info: saved accuracy summaries and model-selection metadata.
• models: pretrained or checkpointed model weights used for training, evaluation, and export.
• utils: experiment-oriented helper scripts and utilities for data conversion and plotting.
• visual: generated plots and visualization outputs.
• jelly_test.py: exploratory script used to learn and test SpikingJelly concepts. It is not a core part of the production workflow.
• n_dataset.py: the main training and evaluation script for the production-oriented SNN models.

Folder structure

SNN_Mapping/
├── core/
│   ├── export.py               # Main exporter module for SNN parameters
│   ├── profiler.py             # Experimental profiler for SNNs
│   └── saving.py               # Low-level serialization utilities
├── export/                     # Generated export artifacts (memory files, headers, etc.)
├── info/
├── models/
├── utils/                      # Helper scripts and utilities                                      
│   ├── data_collection.py 
│   ├── mem2bin.py
│   └── plotting.py
├── visual/
├── jelly_test.py               # Exploratory script for SpikingJelly experiments
└── n_dataset.py                # Main training and evaluation script for SNN models

Core modules

The most important code lives in core. These modules form the backbone of the project.

core/export.py

This module is responsible for converting trained SNN parameters into hardware-oriented export files. Its responsibilities include:

• loading trained model parameters from PyTorch checkpoints;
• extracting weights, biases, and neuron-related parameters;
• organizing parameters by layer;
• partitioning layers for hardware constraints and memory limits;
• generating memory-map headers, per-layer memory files, and supporting artifacts for deployment.

The export flow is designed to be generic enough for reuse on different network layouts and memory configurations. It builds a layer-wise partitioning pipeline and writes outputs in formats suitable for subsequent conversion to binary files and firmware integration.

A key point about this module is that its export path is intended to be extensible. It already supports different parameter layouts and serialization conventions, although the production workflow used in this repository relies on floating-point values without quantization.

Partitioning

The partitioning strategy is currently based on layer-wise splitting, but it can be adapted to more complex partitioning schemes if needed. The module also includes hooks for profiling and logging spike activity during export, which can be useful for debugging and performance analysis. Note that, in order to correctly run the export pipeline, the trained model must be compatible with the expected layer types and parameter structures defined in the exporter. For example, SpikingJelly does not include neuron parameters in the checkpoint by default, so the user should make sure to include them in the model definition or checkpoint if they are needed for export.

Example:

params = torch.load(model_path, map_location=torch.device("cpu"), weights_only=False)
model = {
    "net": params,
    "params": { #These should be included in the checkpoint if needed for export
                "layer_1": [0., 1.],
                "layer_2":[0., 1.],
                "layer_3": [0., 1.],
            }
}

Memory layout

The user is expected to define a memory layout that is compatible with the target hardware. If the hardware requires specific alignment or packing of parameters, the user will be able to customize the export process accordingly. The current implementation provides the layouts used with the SparkRV firmware, but they can be modified for other platforms.

core/saving.py

This module provides the low-level serialization utilities used by the exporter. It is responsible for writing parameter arrays to:

• raw binary files;
• memory files in hexadecimal format;
• C-style headers;
• packed representations such as int16-based words and uint32 values.

It also contains helpers for saving test tensors and event-based spike packets for hardware execution. The module is designed to be extensible for different numeric representations and memory layouts, which makes it useful beyond the immediate SNN export flow.

In the current production setup, the project uses floating-point values, specifically float32, and does not rely on quantized representations. Hardware integration was tested on an FPGA-based platform which supports floating-point arithmetic and uses .mem files for parameter loading.

core/profiler.py

This module is a profiling and graph-analysis component for SNNs. It includes structures for:

• tracking spike activity through forward hooks;
• building graph-like representations of an SNN;
• estimating resource constraints for hardware mapping.

The profiler is still under development and was not fully tested in this repository. It should be treated as an experimental or incremental component rather than a mature production utility.

Training and experimentation scripts

n_dataset.py

This is the main script used for the production-oriented training workflow. It focuses on training and evaluating SNNs on the NMNIST dataset using SpikingJelly-style neuron layers and event-based processing.

It includes:

• dataset loading for NMNIST;
• training loops for simple and deeper SNN architectures;
• validation routines;
• support for profiling spike activity;
• model checkpointing for later export.

This file is the closest thing to the main training entry point in the repository.

jelly_test.py

This script was used to experiment with SpikingJelly and to validate basic SNN training and conversion concepts. It is not considered part of the core production path. It is mainly an exploratory reference for learning and testing the framework rather than a maintained entry point.

Utilities and helper scripts

The utils folder contains practical but experimental support tools:

• utils/mem2bin.py: converts generated memory files into binary artifacts.
• utils/plotting.py: plotting helpers for visualizing training or inference results.
• utils/data_collection.py: utilities related to data handling and experiment logging.

These scripts are mainly used to support experiments and generated outputs rather than to define the core application logic.

Data and model artifacts

Datasets were not included in the repository due to size constraints. The NMNIST dataset, which was used to test the SNNs, can be downloaded from its official source or through SpikingJelly utilities.

Models

The models directory stores checkpoint files for trained networks. These are used both for evaluation and as input to the export pipeline.

Export outputs

The export directory contains generated files such as:

• per-layer memory maps;
• configuration headers;
• memory files for deployment;
• test vectors and exported samples.

These artifacts represent the hardware-oriented output of the export step.

Dependencies

The project uses Python and a small set of scientific and machine-learning dependencies, as described in Pipfile. The main packages are:

• PyTorch;
• TorchVision;
• NumPy;
• Matplotlib;
• SpikingJelly;
• Requests;
• Tabulate.

A typical environment can be created with Pipenv:

pipenv install

Notes on production usage

• The production workflow is centered on n_dataset.py and the export pipeline in core/export.py.
• The profiling module in core/profiler.py is not yet considered stable or fully validated.
• The export and saving infrastructure is designed to support multiple data types and quantization schemes, but the current production pipeline uses floating-point values without quantization.
• jelly_test.py and the scripts in utils are primarily experimental or developmental aids rather than core project components.

Summary

This repository provides a complete prototype workflow for SNN experimentation and hardware-oriented export. It covers model training, evaluation, parameter extraction, and memory-file generation, making it suitable for research on mapping spiking neural networks onto custom hardware.