How adeola-jo/spiking-neural-networks works
Project type and purpose
• This is a domain-specific machine learning pipeline rather than a typical web service or microservice architecture. It implements Spiking Neural Networks (SNNs) for neuromorphic vision data (N-MNIST) using SNNTorch. The primary purpose is to provide end-to-end training, evaluation, checkpointing, and visualization of SNN models.
File structure
• Top-level directories:
• src/ → core modules: data ingestion, model definitions, training logic, utilities
• datasets/ → raw and preprocessed neuromorphic data (scripts & readme)
• checkpoints/ → saved model weights & resume training
• logs/ → serialized results, plots, raster images
• dump/ → alternative scripts: quick experiments & visualization
• tests/ → unit tests for data, models, utilities
• Key scripts/configs:
• src/train.py → orchestrates full training pipeline
• run_training.sh → wrapper to launch training with environment
• requirements.txt → dependencies (PyTorch, SNNTorch, Tonic, etc.)
• dump/__train.py → experimental training variants
• dump/visualize_*.py → ad hoc visualization
README for additional insights
• It describes two main SNN architectures (SpikingCNN, SpikingResNet) and the training pipeline capabilities (optimizers, schedulers, loss functions, logging, checkpointing, visualization).
• Emphasis on modular design (data, models, utils, visualization).
a. Main components:
• External Data Source: N-MNIST dataset (Tonic loader)
• Data Module (src/data/dataset.py): preprocessing, batching, spike generation
• Model Module (src/models/snn_models.py): SpikingCNN & SpikingResNet implementations
• Training Engine (src/train.py): training loop, validation, test, metrics, checkpoint orchestration
• Utilities:
– Checkpoint Manager (src/utils/checkpoint.py)
– Training Helpers (src/utils/train_utils.py)
– Logging & Print (src/utils/print_utils.py)
– Visualization (src/utils/visualization.py + visualize_activations, visualize_nmnist)
• Persistence:
– Checkpoints/Model Store
– Logs & Plots
b. Relationships and interactions:
1. Data Source → Data Module
2. Data Module feeds minibatches to Training Engine
3. Training Engine invokes Model Module, Utils (losses, optimizers, schedulers)
4. After each epoch/step, Training Engine:
– Writes checkpoints via Checkpoint Manager
– Emits metrics to Logs
– Triggers Visualization utilities (optional)
5. End of training: Logs & Plots available for analysis
c. Architectural patterns & principles:
• Modular separation: data / models / training / utilities
• Pluggable architectures: selector switch for CNN vs. ResNet variant
• Observer pattern in logging & visualization (training emits events, utils subscribe)
• Checkpointing as a persistent state manager
d. Relevant technologies:
• PyTorch & SNNTorch for core SNN functionality
• Tonic for neuromorphic data loading
• Matplotlib / Seaborn for visualization
• Python scripts / shell wrapper (run_training.sh)
Detailed capturing of essential elements
• Break out sub-components: DataLoader, Preprocessor, BatchGenerator
• In Training Engine: show loops over epochs and time steps
• External dependencies: annotate SNNTorch, Tonic, PyTorch outside the system boundary