NeuroPudding

A live visualization and debugging tool for Spiking Neural Networks. Attach to any SpikingJelly model with one line of Python and get a real-time dashboard of spike activity, neuron health, and emergent dynamics.

Features

• Spike Raster — live scrolling neuron × timestep grid
• Membrane Traces — real voltage waveforms per neuron with fire threshold line
• Network Topology — interactive layer graph with clickable node inspector
• Layer Health — per-layer firing rate and dead neuron bars
• Emergence Monitor — branching ratio (criticality), synchrony, cell assembly detection
• Training Paradigm — KPI graphs for Surrogate Gradient, Evolutionary, STDP, and Reservoir training
• Anomaly Detection — auto-flags dead subnetworks, runaway excitation, silent layers
• Timeline Rewind — scrub back through 5 minutes of training history
• Activity Heatmap — per-neuron firing rate grid in the right panel

Requirements

• Arch Linux (or any Linux with X11)
• Rust (stable)
• Python 3.10+
• SpikingJelly

Installation

git clone https://github.com/YOUR_USERNAME/NeuroPudding.git
cd NeuroPudding

# Install Python package
python -m venv pudding
source pudding/bin/activate
pip install -e np-hook/

# Build Rust renderer
cd np-core && cargo build && cd ..

Quick Start

# Start everything with one command
./run.sh

Or manually:

# Terminal 1 — start the visualizer
DISPLAY=:0 WINIT_UNIX_BACKEND=x11 ./np-core/target/debug/neuropudding

# Terminal 2 — attach to your model
python examples/quicktest.py

Usage

import torch
import torch.nn as nn
from spikingjelly.activation_based import neuron, functional
import neuropudding

net = nn.Sequential(
    nn.Linear(128, 256),
    neuron.LIFNode(v_threshold=0.5),
    nn.Linear(256, 10),
    neuron.LIFNode(v_threshold=0.5),
)

with neuropudding.watch(net):
    for step in range(10000):
        out = net(torch.rand(4, 128))
        functional.reset_net(net)

Logging Training KPIs

# Surrogate gradient
neuropudding.log("loss", loss.item())
neuropudding.log("accuracy", acc)
neuropudding.log("grad_norm", grad_norm)

# Evolutionary
neuropudding.log("generation", gen)
neuropudding.log("best_fitness", best_fit)
neuropudding.log("species", n_species)
neuropudding.log("innovations", n_innovations)

Architecture

NeuroPudding/ ├── np-hook/ # Python package — SpikingJelly hooks + shared memory writer │ └── neuropudding/ │ ├── hook.py # Forward hooks, neuronal_charge patch for voltage capture │ ├── buffer.py # POSIX shared memory ring buffer (writer side) │ ├── writer.py # Apache Arrow IPC serializer │ └── kpi_writer.py # KPI metrics channel └── np-core/ # Rust workspace — renderer + pipeline └── crates/ ├── np-pipeline/ # Ring buffer reader, Arrow deserializer └── np-render/ # egui dashboard ├── app.rs # Main application + layout ├── raster.rs # Spike raster pixel buffer ├── topology.rs # Interactive network topology ├── traces.rs # Membrane potential traces ├── stats.rs # Layer statistics ├── emergence.rs # Emergence monitor ├── kpi.rs # Training KPI tracker ├── anomaly.rs # Anomaly detection ├── snapshot.rs # Timeline rewind └── events.rs # Spike event log

License

MIT