# adeola-jo/spiking-neural-networks architecture

> Architecture diagram of the GitHub repository adeola-jo/spiking-neural-networks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adeola-jo/spiking-neural-networks
- Repository: https://github.com/adeola-jo/spiking-neural-networks

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB

    %% External Dependencies
    subgraph "External Dependencies"
        SNNTorch["SNNTorch"]:::external
        PyTorch["PyTorch"]:::external
        Tonic["Tonic"]:::external
    end

    %% External Data Source
    External_NMNIST["External Data Source\n(N-MNIST via Tonic)"]:::external

    %% Core Modules
    subgraph "Core Modules"
        DataModule["Data Module"]:::code
        ModelModule["Model Module"]:::code
        TrainingEngine["Training Engine"]:::script
    end

    %% Utilities
    subgraph "Utilities"
        CheckpointManager["Checkpoint Manager"]:::utility
        TrainHelpers["Training Helpers"]:::utility
        PrintUtils["Logging & Print"]:::utility
        VizCore["Visualization Utility"]:::utility
        VizAct["Activation Visualization"]:::utility
        VizNMnist["N-MNIST Visualization"]:::utility
    end

    %% Persistence
    subgraph "Persistence"
        CheckpointStore["Checkpoints Store"]:::persistence
        LogsStore["Logs & Results Store"]:::persistence
    end

    %% Wrapper
    ShellWrapper["Shell Wrapper"]:::script

    %% External flows
    Tonic --> External_NMNIST
    External_NMNIST --> DataModule
    DataModule --> TrainingEngine
    SNNTorch --> ModelModule
    PyTorch --> ModelModule
    ModelModule --> TrainingEngine
    TrainingEngine --> ModelModule

    %% Training orchestration
    ShellWrapper --> TrainingEngine

    %% Utility interactions
    TrainingEngine --> CheckpointManager
    TrainingEngine --> TrainHelpers
    TrainingEngine --> PrintUtils
    TrainingEngine --> VizCore
    VizCore -.-> VizAct
    VizCore -.-> VizNMnist

    %% Persistence outputs
    TrainingEngine --> CheckpointStore
    TrainingEngine --> LogsStore

    %% Click Events
    click External_NMNIST "https://github.com/adeola-jo/spiking-neural-networks/tree/main/datasets/"
    click DataModule "https://github.com/adeola-jo/spiking-neural-networks/blob/main/src/data/dataset.py"
    click ModelModule "https://github.com/adeola-jo/spiking-neural-networks/blob/main/src/models/snn_models.py"
    click TrainingEngine "https://github.com/adeola-jo/spiking-neural-networks/blob/main/src/train.py"
    click ShellWrapper "https://github.com/adeola-jo/spiking-neural-networks/blob/main/run_training.sh"
    click CheckpointManager "https://github.com/adeola-jo/spiking-neural-networks/blob/main/src/utils/checkpoint.py"
    click TrainHelpers "https://github.com/adeola-jo/spiking-neural-networks/blob/main/src/utils/train_utils.py"
    click PrintUtils "https://github.com/adeola-jo/spiking-neural-networks/blob/main/src/utils/print_utils.py"
    click VizCore "https://github.com/adeola-jo/spiking-neural-networks/blob/main/src/utils/visualization.py"
    click VizAct "https://github.com/adeola-jo/spiking-neural-networks/blob/main/src/utils/visualize_activations.py"
    click VizNMnist "https://github.com/adeola-jo/spiking-neural-networks/blob/main/src/utils/visualize_nmnist.py"
    click CheckpointStore "https://github.com/adeola-jo/spiking-neural-networks/tree/main/checkpoints/"
    click LogsStore "https://github.com/adeola-jo/spiking-neural-networks/tree/main/logs/"

    %% Styles
    classDef external fill:#d3d3d3,stroke:#777,stroke-width:1px
    classDef code fill:#cce5ff,stroke:#4d94ff,stroke-width:1px
    classDef script fill:#d5f5e3,stroke:#28b463,stroke-width:1px
    classDef utility fill:#fcf3cf,stroke:#f1c40f,stroke-width:1px
    classDef persistence fill:#e8daef,stroke:#8e44ad,stroke-width:1px
```
