Skip to content
Proyectos

D-ST-Sword/mlx-snn has 427 GitHub stars and 2 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-19 07:44 UTC. Last push 2026-03-20.

Cómo se miden estas cifras

Crecimiento de estrellas medido

in 24h
0
in 7 days
Recopilando historial
in 15 days
Recopilando historial
in 1 month
Recopilando historial

Cambios netos en períodos que se solapan, no totales diarios. Los datos no disponibles se dejan en blanco. Las estrellas indican interés, no calidad.

Acerca de

Spiking Neural Network library built natively on Apple MLX

Aprendizaje automático

README.md

Original

mlx-snn

A general-purpose Spiking Neural Network library built on Apple MLX.

mlx-snn aims to provide an efficient, research-friendly SNN framework that leverages MLX's unified memory architecture and lazy evaluation. Whether you're exploring neuron dynamics, training classifiers with surrogate gradients, or exchanging models via NIR, mlx-snn offers a clean, Pythonic API that integrates naturally into the MLX ecosystem.

CI PyPI version Python 3.9+ License: GPL-3.0 Docs arXiv

9 neuron models · 6 surrogate gradients · 8 spike encodings · 5 neuromorphic datasets · LSM reservoir · NIR interop · 403 tests

Highlights

Unified Memory SNNs

SNNs store per-neuron states across every timestep — a memory bottleneck on discrete-GPU architectures. Apple Silicon's unified memory eliminates CPU↔GPU transfers, enabling extended temporal windows and larger reservoirs without the VRAM wall.

17–25× Energy Efficiency

M3 Max trains SNNs 2.6–3.7× faster than Tesla V100 at 1/7th the power. Recurrent spiking dynamics are latency-bound, not compute-bound — favoring Apple Silicon's high-bandwidth unified architecture over datacenter parallelism.

Multi-Scale Temporal Modeling

MSLeaky assigns frequency-matched decay rates to parallel spiking branches — capturing delta through gamma dynamics in a single network. Chunked BPTT with state detachment scales to long biosignal sequences (EEG, fMRI) without exploding memory.

Installation

pip install mlx-snn

Requires Python 3.9+ and Apple Silicon (M1/M2/M3/M4).

Quick Start

import mlx.core as mx
import mlx.nn as nn
import mlxsnn

# Build a spiking network
fc = nn.Linear(784, 10)
lif = mlxsnn.Leaky(beta=0.95, threshold=1.0)

# Encode input as spike train and run over time
spikes_in = mlxsnn.rate_encode(mx.random.uniform(shape=(8, 784)), num_steps=25)
state = lif.init_state(batch_size=8, features=10)

for t in range(25):
    spk, state = lif(fc(spikes_in[t]), state)

print("Output membrane:", state["mem"].shape)  # (8, 10)

Features

Neuron Models

All neurons support learn_threshold and configurable reset mechanisms (subtract / zero / none). Neurons with a decay constant support learn_beta; recurrent neurons support learn_V. State is always an explicit dict — compatible with MLX's functional transforms and mx.compile.

Model Description State Variables
Leaky (LIF) Leaky Integrate-and-Fire with configurable decay mem
IF Integrate-and-Fire (non-leaky, perfect integrator) mem
Izhikevich 2D dynamics with RS/IB/CH/FS presets v, u
ALIF Adaptive LIF with dynamic threshold mem, adapt
Synaptic Conductance-based dual-state LIF syn, mem
Alpha Dual-exponential synaptic model syn_exc, syn_inh, mem
RLeaky Recurrent LIF with learnable feedback mem, spk
RSynaptic Recurrent Synaptic with learnable feedback syn, mem, spk
MSLeaky Multi-scale LIF with per-branch frequency-matched beta mem per branch

Surrogate Gradients

All neurons support differentiable training through 6 surrogate gradient functions:

Function Surrogate gradient Properties
Arctan (default) α / (π(1 + α²x²)) Stable BPTT convergence, moderate locality
Fast Sigmoid scale / (2(1 + scale·|x|)²) Heavier tails, rational decay
Sigmoid slope · σ(slope·x) · (1 − σ(slope·x)) Standard logistic derivative
Triangular max(0, 1 − |x|) Compact support, localized near threshold
Straight-Through 1 Simplest, unit gradient everywhere
Custom User-defined Plug in any differentiable approximation

Spike Encoding

8 encoding methods for converting continuous signals into spike trains:

Method Input Use Case
Rate (Poisson) Static values Images, general-purpose classification
Latency (TTFS) Static values Energy-efficient temporal coding
Delta Modulation Temporal signals Change detection, event-like encoding
Direct Any tensor Pass-through for pre-computed inputs
Repeat Spike patterns Tile spike trains across longer windows
Frequency-Band EEG signals FFT-based decomposition into delta/theta/alpha/beta/gamma bands
Threshold-Crossing Temporal signals Multi-level amplitude crossing detection
EEG Encoder Raw EEG Configurable rate/delta/threshold encoding for biosignals

Convolutional SNN Layers

Build deep spiking convolutional networks with spatial pooling:

import mlxsnn

conv1 = mlxsnn.SpikingConv2d(in_channels=2, out_channels=64, kernel_size=3, padding=1)
pool1 = mlxsnn.SpikingMaxPool2d(kernel_size=2, stride=2)
lif1  = mlxsnn.Leaky(beta=0.95)
drop  = mlxsnn.SpikeDropout(p=0.2)  # spike-aware (no rescaling)
flat  = mlxsnn.SpikingFlatten()

Also includes 6 mathematically-principled temporal operators for Conv SNNs: TAC (Temporal Aggregated Conv), TAC-TP (Temporal-Preserving), L-TAC (Learnable), FTC (Fourier Temporal Conv), IMC (InfoMax Spike Conv), TCC (Temporal Collapse Conv).

Liquid State Machine

Reservoir computing with spiking neurons — random sparse recurrent connectivity with configurable topology:

import mlxsnn

lsm = mlxsnn.LSM(
    input_size=64, reservoir_size=500, output_size=10,
    connectivity=0.1, spectral_radius=0.9,
    topology="small_world",  # also: "erdos_renyi", "scale_free"
    exc_ratio=0.8,           # Dale's law: 80% excitatory
)
state = lsm.init_state(batch_size=32)

for t in range(num_steps):
    output, state = lsm(spikes[t], state)

Training Utilities

BPTT variants:

  • bptt_forward(model, spikes, state) — standard backpropagation through time
  • chunked_bptt_forward(model, spikes, state, chunk_size) — memory-efficient training on long sequences via state detachment at chunk boundaries
  • detach_state(state) — detach all tensors in a state dict (for truncated BPTT)

mx.compile wrappers:

  • compiled_step(model) — returns a compiled single-timestep callable
  • compiled_forward(model, spikes, state) — BPTT forward pass with per-timestep mx.compile

Loss functions (11 total):

Loss Approach
ce_rate_loss Cross-entropy on spike rates (spike count / T)
ce_count_loss Cross-entropy on raw spike counts
mse_membrane_loss MSE on final membrane potential
mse_count_loss MSE on spike counts vs targets
membrane_loss Cross-entropy on final membrane potential
rate_coding_loss Cross-entropy on log-softmax of spike counts
activity_reg_loss Penalize deviation from target firing rate
l1_spike_loss L1 sparsity penalty on spike counts
l2_spike_loss L2 regularization on spike counts

Utility functions: spike_rate, spike_count.

Learnable parameters: learn_threshold (all neurons), learn_beta (LIF-based neurons), learn_V (recurrent neurons). Works with standard MLX optimizers (mlx.optimizers.Adam, etc.).

Neuromorphic Datasets

5 built-in dataset loaders with automatic download, caching, and event-to-frame conversion:

Dataset Modality Classes Samples
DVS-Gesture Event camera (hand gestures) 11 1,342
CIFAR10-DVS Event camera (natural images) 10 10,000
N-MNIST Event camera (digits) 10 70,000
SHD Audio (spoken digits) 20 10,420
SSC Audio (spoken commands) 35 100,000+
from mlxsnn.datasets import DVSGestureDataset, create_dataloader

dataset = DVSGestureDataset(root="./data", train=True, num_steps=16)
loader = create_dataloader(dataset, batch_size=16, shuffle=True)

Visualization

Requires pip install mlx-snn[viz] (matplotlib).

from mlxsnn.utils.visualization import plot_raster, plot_membrane, plot_firing_rate

plot_raster(spike_tensor, title="Layer 1 Spikes")       # spike raster over time
plot_membrane(state["mem"], title="Membrane Potential")  # membrane trace
plot_firing_rate(spike_tensor, title="Firing Rates")     # per-neuron rates

NIR Interoperability

NIR enables cross-framework SNN model exchange — import/export models to snnTorch, Norse, SpikingJelly, and neuromorphic hardware.

pip install mlx-snn[nir]
# Export
layers = [('fc1', nn.Linear(784, 128)), ('lif1', mlxsnn.Leaky(beta=0.9)),
          ('fc2', nn.Linear(128, 10)),   ('lif2', mlxsnn.Leaky(beta=0.9))]
nir.write('model.nir', mlxsnn.export_to_nir(layers))

# Import
model = mlxsnn.import_from_nir(nir.read('model.nir'))
out, state = model(x, model.init_states(batch_size=32))

Supported: nn.Linear ↔ nir.Affine/nir.Linear, Leaky ↔ nir.LIF, IF ↔ nir.IF, Synaptic ↔ nir.CubaLIF.

Benchmarks

All experiments use identical hyperparameters: Adam (LR=1e-3), Poisson rate encoding, T=25 timesteps, batch size 128, 5 random seeds, 10 epochs, surrogate_fn="fast_sigmoid". Full scripts in benchmarks/ and our arXiv paper.

Training Accuracy (identical within noise)

Task mlx-snn (M3 Max) snnTorch (V100)
FC SNN on MNIST 97.0% 97.2%
FC SNN on FashionMNIST 85.2% 85.2%
LSM Reservoir on MNIST 92.4% 93.6%

Training Speed

Task mlx-snn (M3 Max) snnTorch (V100) Speedup
FC SNN (784→128→10) 7.4 s/epoch 19.4 s/epoch 2.6x
LSM Reservoir (500 neurons) 3.2 s/epoch 5.7 s/epoch 1.8x

Inference Throughput (samples/sec, T=25)

Model Batch mlx-snn (M3 Max) snnTorch (V100) Speedup
FC-SNN 128 23,875 6,552 3.6x
FC-SNN 512 95,735 26,058 3.7x
Conv-SNN 128 6,671 3,859 1.7x
Conv-SNN 512 6,434 4,252 1.5x

mx.compile Acceleration

Mode Time (25-step forward)
Uncompiled 2.72 ms
Compiled 0.92 ms
Speedup 2.9x

Power Efficiency

The M3 Max (TDP ~45 W) delivers 2.6–3.7x faster SNN training/inference than the V100 (TDP 300 W), yielding an estimated 17–25x better energy efficiency (performance per watt).

For detailed results and reproduction scripts, see benchmarks/ and our benchmarking paper.

Migrating from snnTorch

mlx-snn is designed to feel familiar to snnTorch users:

snnTorch (PyTorch) mlx-snn (MLX)
Import import snntorch as snn import mlxsnn
Create lif = snn.Leaky(beta=0.9) lif = mlxsnn.Leaky(beta=0.9)
Forward spk, mem = lif(x, mem) spk, state = lif(x, state)
State Separate tensors (mem) Explicit dict (state["mem"])
Tensors torch.Tensor mx.array
Gradients autograd + surrogate STE pattern + mx.stop_gradient

Key design difference: state is always an explicit dict — pass in, get out. No hidden instance variables. This plays well with MLX's functional transforms (mx.grad, mx.vmap, mx.compile).

Project Structure

mlxsnn/
├── neurons/       # Leaky, IF, Izhikevich, ALIF, Synaptic, Alpha, RLeaky, RSynaptic, MSLeaky
├── surrogate/     # arctan, fast_sigmoid, sigmoid, triangular, straight_through, custom
├── encoding/      # rate, latency, delta, direct, repeat, frequency-band, threshold-crossing, EEG
├── functional/    # Stateless pure functions, 11 loss functions, metrics
├── layers/        # SpikingConv2d, MaxPool2d, AvgPool2d, Flatten, SpikeDropout
├── operators/     # TAC, TAC-TP, L-TAC, FTC, IMC, TCC
├── liquid/        # LiquidReservoir, LSM, topology generators
├── datasets/      # DVSGesture, CIFAR10DVS, NMNIST, SHD, SSC
├── training/      # BPTT, chunked BPTT, mx.compile wrappers
├── utils/         # Visualization, state management
└── nir_*.py       # NIR export/import utilities

Roadmap

  • v0.1 — Core neurons (LIF, IF), surrogate gradients, rate/latency encoding
  • v0.2 — Extended neurons (Izhikevich, ALIF, Synaptic, Alpha), EEG encoder, delta encoding
  • v0.3 — NIR interoperability (export/import)
  • v0.4 — Recurrent neurons, conv/pooling layers, neuromorphic datasets, TAC operators
  • v0.5 — Direct/repeat encoding, activity regularization, SpikeDropout, visualization, SHD dataset
  • v0.6 — CI/CD, API documentation site, complete examples
  • v0.7 — LSM, MSLeaky neuron, chunked BPTT, mx.compile, frequency-band & threshold-crossing encoding
  • v1.0 — Full documentation, comprehensive benchmarks, JOSS paper

Publications

Citation

If you use mlx-snn in your research, please cite:

@misc{qin2026mlxsnn,
  title         = {mlx-snn: Spiking Neural Networks on Apple Silicon via {MLX}},
  author        = {Jiahao Qin},
  year          = {2026},
  eprint        = {2603.03529},
  archivePrefix = {arXiv},
  primaryClass  = {cs.LG},
  url           = {https://arxiv.org/abs/2603.03529}
}

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

License

GPL-3.0