Skip to content

Examples Gallery

The examples/ directory contains production-quality scripts that demonstrate core btorch patterns. This page annotates each example and links to the relevant tests and API docs.

rsnn.py — Minimal RSNN

A self-contained demonstration of a recurrent spiking neural network using GLIF3, AlphaPSC, and RecurrentNN. The recurrent layer now uses SparseConnection by default and supplies an expected spike-density hint, allowing CUDA models to select the source-driven Triton push backend. Dense and sparse networks can be constructed from identical weights for numerical and performance comparisons.

Run the small plotting and training demo with the default sparse connection:

PYTHONPATH=. python examples/rsnn.py

Compare identical dense and sparse GLIF networks on a larger CUDA workload:

PYTHONPATH=. python examples/rsnn.py --mode compare --device cuda --benchmark \
  --num-hidden 16384 --timesteps 20 --batch-size 4 \
  --recurrent-density 0.001 --expected-spike-density 0.015 --input-scale 6

The comparison checks outputs and spike agreement before timing and prints the runtime plan selected for the sparse recurrent connection. Reported timings are end-to-end wall-clock latency, including state reset and synchronized CUDA execution; they are not isolated sparse-kernel timings.

On October 7, 2026, this command selected the Triton push backend on an RTX 5090, produced 1.76% spike activity, matched the dense network exactly, and measured 23.535 ms dense versus 17.751 ms sparse (1.33x end-to-end). Results depend on the GPU, software versions, and network activity.

Key patterns: - functional.init_net_state and functional.reset_net - SparseConnection with Hints(expected_density=...) - Dense/sparse output-equivalence and benchmark mode - environ.context(dt=1.0) - update_state_names for state recording - plot_raster and plot_neuron_traces from btorch.visualisation

See also: - Tutorial 1: Building an RSNN - Tutorial 2: Training an SNN - Tutorial: Heterogeneous Multi-Receptor E/I RSNN

rsnn_brain.py — Brain-Environment Interaction

Extends the basic RSNN with brain-environment interaction networks. Demonstrates NeuronEmbedMapLayer and DetectionWindow for sensory-motor tasks.

Key patterns: - Embedding maps between neuron spaces - Detection windows for spike-based event detection - Multi-module composition beyond RecurrentNN

fmnist.py — Fashion-MNIST Training (Plain PyTorch)

A full training pipeline for Fashion-MNIST classification using a GLIF3-based RSNN with sparse recurrent connectivity and voltage regularization.

Key patterns: - SparseConnection for sparse recurrent weights - AlphaPSCBilleh synapse with heterogeneous time constants - VoltageRegularizer for membrane-voltage regularization - Manual training loop with reset_net per batch - Checkpointing memories_rv alongside state_dict()

See also: - Tutorial 2: Training an SNN - API: btorch.models.regularizer

fmnist_lightning.py — PyTorch Lightning Integration

The same Fashion-MNIST model factored into a PyTorch Lightning LightningModule. Shows how btorch state management fits into the Lightning training lifecycle.

Key patterns: - Lightning training_step with reset_net - scale_state_ for scaling neuron-parameter dicts - Validation loop with state recording

delayed_synapse_demo.py — Synaptic Delays

Demonstrates synaptic delays using SpikeHistory, DelayedPSC, and HeterSynapsePSC.

Key patterns: - SpikeHistory as a rolling spike buffer - DelayedPSC for adding scalar delays to any PSC model - HeterSynapsePSC(..., max_delay_steps=...) for delay + receptor combinations - expand_conn_for_delays for delay-aware connection matrices

See also: - API: btorch.models.history and btorch.models.synapse - Tests: tests/connectome/test_delay_expansion.py

Tests as Examples

Many tests/ files contain concise, validated usage patterns that are ideal for documentation:

  • tests/models/test_mem_load_save.py — Checkpointing and state restoration
  • tests/models/test_compile.py — torch.compile with dt context
  • tests/utils/test_conf.py — OmegaConf patterns
  • tests/visualisation/*.py — Nearly every plotting function

Heterogeneous E/I Workflow

The heterogeneous multi-receptor E/I tutorial builds a complete recurrent network with semantic receptor-labelled edges, receptor-specific PSC kinetics, Dale's law, training, and channel inspection.