gsmc-torch 0.1.0__tar.gz

gsmc_torch-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Sumit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO LICENSE OF MERCHANTABILITY, FITNESS FOR
+A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

gsmc_torch-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: gsmc-torch
+Version: 0.1.0
+Summary: Gated Spiking Memory Cell (GSMC) -- Standalone PyTorch plugin for vanishing-gradient-free spiking neural networks
+Author: Sumit
+License: MIT
+Project-URL: Documentation, https://github.com/Griffith-7/GSMC-SNN#readme
+Project-URL: Repository, https://github.com/Griffith-7/GSMC-SNN
+Project-URL: Issues, https://github.com/Griffith-7/GSMC-SNN/issues
+Keywords: spiking-neural-networks,snn,neuromorphic,vanishing-gradients,constant-error-carousel,pytorch,snn-transformer,plugin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: torchvision>=0.15; extra == "dev"
+Dynamic: license-file
+
+# GSMC-Torch: Gated Spiking Memory Cell Plugin
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch 2.0+](https://img.shields.io/badge/pytorch-2.0%2B-ee4c2c.svg)](https://pytorch.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A standalone, production-grade PyTorch plugin library for **Gated Spiking Memory Cells (GSMC)**.
+
+GSMC provides a fundamental solution to the **vanishing gradient problem** in Spiking Neural Networks (SNNs) and Spiking Transformers via a learnable **Constant-Error Carousel (CEC)**, while maintaining strict binary inter-neuron communication and **multiplier-free operations (~41 pJ/step/neuron on 45 nm, 46× cheaper than ANN-LSTM)**.
+
+---
+
+## Key Features
+
+- **Drop-in PyTorch Plugin (`nn.Module`)**: Seamlessly integrates into any PyTorch model architecture (SNN-Transformers, RNNs, ConvNets, hybrid models).
+- **Dual Execution Modes**:
+  - `GSMCv2` / `GSMCLayer`: Vectorized sequence-to-sequence layer for fast BPTT over multi-timestep sequence tensors `(batch, time, features)`.
+  - `GSMCCell`: Low-level single-timestep stateful cell for step-by-step unrolling, streaming inference, or custom Transformer attention blocks.
+- **Vanishing-Gradient Immunity**: Preserves temporal gradients over $T=784$ steps **34+ orders of magnitude above LIF baselines**.
+- **Split-Gamma Reset ($\gamma_r = 0.1$)**: Eliminates the "reset tax" on temporal gradients while maintaining negative feedback stabilization.
+- **Hardware Energy Model**: Built-in 45nm CMOS energy metrics generator (`compute_energy_per_step`).
+
+---
+
+## Installation
+
+Install directly in editable mode:
+
+```bash
+cd gsmc-plugin
+pip install -e .
+```
+
+Or install with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart
+
+```python
+import torch
+from gsmc_torch import GSMCv2, GSMCCell
+
+# 1. High-level sequence layer (batch_first=True)
+layer = GSMCv2(input_size=1, hidden_size=128)
+
+# Input binary spikes: (batch=32, time=784, features=1)
+x = (torch.rand(32, 784, 1) > 0.5).float()
+
+# Forward pass -> returns output binary spikes (32, 784, 128)
+spikes = layer(x)
+print(f"Output spikes shape: {spikes.shape}")
+
+# 2. Low-level stateful step cell
+cell = GSMCCell(input_size=1, hidden_size=128)
+state = cell.init_state(batch_size=32)
+
+x_t = (torch.rand(32, 1) > 0.5).float()
+s_next, state = cell(x_t, state)
+print(f"Step spike shape: {s_next.shape}")
+```
+
+---
+
+## Integration into Spiking Transformers
+
+GSMC can be used directly inside Spiking Attention blocks to provide long-horizon temporal memory:
+
+```python
+import torch
+import torch.nn as nn
+from gsmc_torch import GSMCv2
+
+class SpikingAttentionBlock(nn.Module):
+    def __init__(self, embed_dim=64, hidden_dim=128):
+        super().__init__()
+        self.q_proj = nn.Linear(embed_dim, embed_dim)
+        self.k_proj = nn.Linear(embed_dim, embed_dim)
+        self.v_proj = nn.Linear(embed_dim, embed_dim)
+        
+        # GSMC Temporal Memory Cell replacing standard attention decay
+        self.gsmc_memory = GSMCv2(input_size=embed_dim, hidden_size=hidden_dim, batch_first=True)
+        self.out_proj = nn.Linear(hidden_dim, embed_dim)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        attn_features = (self.q_proj(x) * self.k_proj(x)) + self.v_proj(x)
+        spiking_attn = (attn_features > 0.0).float()
+        memory_spikes = self.gsmc_memory(spiking_attn)
+        return self.out_proj(memory_spikes)
+```
+
+---
+
+## Mathematical Formulation
+
+### Forward Dynamics
+All affine operations act on binary vectors $X[t], S[t-1] \in \{0, 1\}$, eliminating dense multiplications on neuromorphic hardware:
+
+$$\begin{aligned}
+f[t] &= \sigma(W_f X[t] + U_f S[t-1] + b_f) && \text{(Forget gate: initial } b_f=8.0) \\
+i[t] &= \sigma(W_i X[t] + U_i S[t-1]) && \text{(Input write gate)} \\
+o[t] &= \sigma(W_o X[t] + U_o S[t-1] + b_o) && \text{(Output exposure gate: initial } b_o=-2.0) \\
+g[t] &= \tanh(W_g X[t] + U_g S[t-1]) && \text{(Candidate state)} \\
+A[t] &= f[t] \odot M[t-1] + i[t] \odot g[t] && \text{(Memory-bus accumulator)} \\
+V[t] &= o[t] \odot \text{Norm}(A[t]) + W_d X[t] && \text{(Exposed membrane voltage)} \\
+S[t] &= \Theta(V[t] - \theta_t) && \text{(Spike generation)} \\
+M[t] &= A[t] - v_{th} \tilde{S}[t] && \text{(Refractory reset via split } \gamma_r)
+\end{aligned}$$
+
+### BPTT Temporal Jacobian
+The temporal Jacobian decomposes into:
+
+$$J_t = \frac{\partial M[t]}{\partial M[t-1]} = \operatorname{diag}(f[t]) + \mathcal{B}_t$$
+
+Holding $S$ constant gives $\prod_{t=1}^T \operatorname{diag}(f[t])$, a learnable constant-error carousel immune to exponential decay.
+
+---
+
+## Hardware Energy Footprint (45 nm CMOS)
+
+| Model | Dense MACs | Energy ($\text{pJ}/\text{step}/\text{neuron}$) | Energy vs ANN-LSTM |
+| :--- | :--- | :--- | :--- |
+| **VanillaLIF** | 0 | 16.9 pJ | 112× cheaper |
+| **GSMC v2 (`gsmc_torch`)** | **0** | **41.2 pJ** | **46× cheaper** |
+| **SpikingLSTM** | 0 | 40.8 pJ | 46× cheaper |
+| **ANN-LSTM** | Dense ($32 \times 32$) | 1900.8 pJ | 1.0× (Baseline) |
+
+---
+
+## Running Tests
+
+Execute the comprehensive Pytest suite:
+
+```bash
+pytest
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

gsmc_torch-0.1.0/README.md

@@ -0,0 +1,146 @@
+# GSMC-Torch: Gated Spiking Memory Cell Plugin
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch 2.0+](https://img.shields.io/badge/pytorch-2.0%2B-ee4c2c.svg)](https://pytorch.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A standalone, production-grade PyTorch plugin library for **Gated Spiking Memory Cells (GSMC)**.
+
+GSMC provides a fundamental solution to the **vanishing gradient problem** in Spiking Neural Networks (SNNs) and Spiking Transformers via a learnable **Constant-Error Carousel (CEC)**, while maintaining strict binary inter-neuron communication and **multiplier-free operations (~41 pJ/step/neuron on 45 nm, 46× cheaper than ANN-LSTM)**.
+
+---
+
+## Key Features
+
+- **Drop-in PyTorch Plugin (`nn.Module`)**: Seamlessly integrates into any PyTorch model architecture (SNN-Transformers, RNNs, ConvNets, hybrid models).
+- **Dual Execution Modes**:
+  - `GSMCv2` / `GSMCLayer`: Vectorized sequence-to-sequence layer for fast BPTT over multi-timestep sequence tensors `(batch, time, features)`.
+  - `GSMCCell`: Low-level single-timestep stateful cell for step-by-step unrolling, streaming inference, or custom Transformer attention blocks.
+- **Vanishing-Gradient Immunity**: Preserves temporal gradients over $T=784$ steps **34+ orders of magnitude above LIF baselines**.
+- **Split-Gamma Reset ($\gamma_r = 0.1$)**: Eliminates the "reset tax" on temporal gradients while maintaining negative feedback stabilization.
+- **Hardware Energy Model**: Built-in 45nm CMOS energy metrics generator (`compute_energy_per_step`).
+
+---
+
+## Installation
+
+Install directly in editable mode:
+
+```bash
+cd gsmc-plugin
+pip install -e .
+```
+
+Or install with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart
+
+```python
+import torch
+from gsmc_torch import GSMCv2, GSMCCell
+
+# 1. High-level sequence layer (batch_first=True)
+layer = GSMCv2(input_size=1, hidden_size=128)
+
+# Input binary spikes: (batch=32, time=784, features=1)
+x = (torch.rand(32, 784, 1) > 0.5).float()
+
+# Forward pass -> returns output binary spikes (32, 784, 128)
+spikes = layer(x)
+print(f"Output spikes shape: {spikes.shape}")
+
+# 2. Low-level stateful step cell
+cell = GSMCCell(input_size=1, hidden_size=128)
+state = cell.init_state(batch_size=32)
+
+x_t = (torch.rand(32, 1) > 0.5).float()
+s_next, state = cell(x_t, state)
+print(f"Step spike shape: {s_next.shape}")
+```
+
+---
+
+## Integration into Spiking Transformers
+
+GSMC can be used directly inside Spiking Attention blocks to provide long-horizon temporal memory:
+
+```python
+import torch
+import torch.nn as nn
+from gsmc_torch import GSMCv2
+
+class SpikingAttentionBlock(nn.Module):
+    def __init__(self, embed_dim=64, hidden_dim=128):
+        super().__init__()
+        self.q_proj = nn.Linear(embed_dim, embed_dim)
+        self.k_proj = nn.Linear(embed_dim, embed_dim)
+        self.v_proj = nn.Linear(embed_dim, embed_dim)
+        
+        # GSMC Temporal Memory Cell replacing standard attention decay
+        self.gsmc_memory = GSMCv2(input_size=embed_dim, hidden_size=hidden_dim, batch_first=True)
+        self.out_proj = nn.Linear(hidden_dim, embed_dim)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        attn_features = (self.q_proj(x) * self.k_proj(x)) + self.v_proj(x)
+        spiking_attn = (attn_features > 0.0).float()
+        memory_spikes = self.gsmc_memory(spiking_attn)
+        return self.out_proj(memory_spikes)
+```
+
+---
+
+## Mathematical Formulation
+
+### Forward Dynamics
+All affine operations act on binary vectors $X[t], S[t-1] \in \{0, 1\}$, eliminating dense multiplications on neuromorphic hardware:
+
+$$\begin{aligned}
+f[t] &= \sigma(W_f X[t] + U_f S[t-1] + b_f) && \text{(Forget gate: initial } b_f=8.0) \\
+i[t] &= \sigma(W_i X[t] + U_i S[t-1]) && \text{(Input write gate)} \\
+o[t] &= \sigma(W_o X[t] + U_o S[t-1] + b_o) && \text{(Output exposure gate: initial } b_o=-2.0) \\
+g[t] &= \tanh(W_g X[t] + U_g S[t-1]) && \text{(Candidate state)} \\
+A[t] &= f[t] \odot M[t-1] + i[t] \odot g[t] && \text{(Memory-bus accumulator)} \\
+V[t] &= o[t] \odot \text{Norm}(A[t]) + W_d X[t] && \text{(Exposed membrane voltage)} \\
+S[t] &= \Theta(V[t] - \theta_t) && \text{(Spike generation)} \\
+M[t] &= A[t] - v_{th} \tilde{S}[t] && \text{(Refractory reset via split } \gamma_r)
+\end{aligned}$$
+
+### BPTT Temporal Jacobian
+The temporal Jacobian decomposes into:
+
+$$J_t = \frac{\partial M[t]}{\partial M[t-1]} = \operatorname{diag}(f[t]) + \mathcal{B}_t$$
+
+Holding $S$ constant gives $\prod_{t=1}^T \operatorname{diag}(f[t])$, a learnable constant-error carousel immune to exponential decay.
+
+---
+
+## Hardware Energy Footprint (45 nm CMOS)
+
+| Model | Dense MACs | Energy ($\text{pJ}/\text{step}/\text{neuron}$) | Energy vs ANN-LSTM |
+| :--- | :--- | :--- | :--- |
+| **VanillaLIF** | 0 | 16.9 pJ | 112× cheaper |
+| **GSMC v2 (`gsmc_torch`)** | **0** | **41.2 pJ** | **46× cheaper** |
+| **SpikingLSTM** | 0 | 40.8 pJ | 46× cheaper |
+| **ANN-LSTM** | Dense ($32 \times 32$) | 1900.8 pJ | 1.0× (Baseline) |
+
+---
+
+## Running Tests
+
+Execute the comprehensive Pytest suite:
+
+```bash
+pytest
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

gsmc_torch-0.1.0/gsmc_torch/__init__.py

@@ -0,0 +1,31 @@
+"""GSMC-Torch: Gated Spiking Memory Cell Plugin for PyTorch.
+
+A drop-in PyTorch library implementing vanishing-gradient-free spiking neurons
+with constant-error carousels (CEC) for SNNs, Spiking Transformers, and Neuromorphic computing.
+"""
+
+from .cell import GSMCCell, GSMCv2, GSMCLayer, GSMCState
+from .fused_cell import FusedGSMCv2, FusedGSMCLayer
+from .transformer import GSMCSpikingAttention
+from .surrogate import ATanSurrogate, surrogate_spike
+from .baselines import VanillaLIF, LSNNCell
+from .utils import compute_energy_per_step, compute_energy_table
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GSMCCell",
+    "GSMCv2",
+    "GSMCLayer",
+    "FusedGSMCv2",
+    "FusedGSMCLayer",
+    "GSMCSpikingAttention",
+    "GSMCState",
+    "ATanSurrogate",
+    "surrogate_spike",
+    "VanillaLIF",
+    "LSNNCell",
+    "compute_energy_per_step",
+    "compute_energy_table",
+    "__version__",
+]

gsmc_torch-0.1.0/gsmc_torch/baselines.py

@@ -0,0 +1,132 @@
+"""Baseline SNN cells (VanillaLIF, LSNNCell) for drop-in comparative analysis."""
+
+import torch
+import torch.nn as nn
+from typing import Optional, Tuple
+from .surrogate import surrogate_spike
+
+
+class VanillaLIF(nn.Module):
+    """Standard Leaky Integrate-and-Fire (LIF) neuron layer with fixed decay beta < 1.
+
+    Args:
+        input_size: Feature dimension of inputs.
+        hidden_size: Hidden state dimension.
+        beta: Membrane potential leak factor (default: 0.9).
+        v_th: Spike threshold (default: 1.0).
+        batch_first: If True, sequence tensor is (batch, time, features). Default: True.
+    """
+
+    def __init__(
+        self,
+        input_size: int,
+        hidden_size: int,
+        beta: float = 0.9,
+        v_th: float = 1.0,
+        batch_first: bool = True,
+    ):
+        super().__init__()
+        self.input_size = input_size
+        self.hidden_size = hidden_size
+        self.beta = beta
+        self.v_th = v_th
+        self.batch_first = batch_first
+
+        self.W_x = nn.Linear(input_size, hidden_size, bias=True)
+        self.V_x = nn.Linear(hidden_size, hidden_size, bias=False)
+        nn.init.xavier_uniform_(self.W_x.weight)
+        nn.init.orthogonal_(self.V_x.weight)
+
+    def forward(self, x_seq: torch.Tensor) -> torch.Tensor:
+        if not self.batch_first:
+            x_seq = x_seq.transpose(0, 1)
+
+        batch_size, seq_len, _ = x_seq.size()
+        device = x_seq.device
+        dtype = x_seq.dtype
+
+        v_t = torch.zeros(batch_size, self.hidden_size, device=device, dtype=dtype)
+        s_t = torch.zeros(batch_size, self.hidden_size, device=device, dtype=dtype)
+        spikes = []
+
+        for t in range(seq_len):
+            x_t = x_seq[:, t, :]
+            i_t = self.W_x(x_t) + self.V_x(s_t)
+            v_t = self.beta * v_t + i_t
+            s_t = surrogate_spike(v_t - self.v_th)
+            v_t = v_t - s_t * self.v_th
+            spikes.append(s_t)
+
+        spikes = torch.stack(spikes, dim=1)
+        if not self.batch_first:
+            spikes = spikes.transpose(0, 1)
+        return spikes
+
+
+class LSNNCell(nn.Module):
+    """Long Short-Term Memory Spiking Neural Network Cell (LSNN) with adaptive threshold.
+
+    Based on Bellec et al. (2018). Combines leaky integration with refractory threshold adaptation.
+
+    Args:
+        input_size: Feature dimension of inputs.
+        hidden_size: Hidden state dimension.
+        beta: Membrane leak factor (default: 0.93).
+        beta_a: Threshold adaptation decay factor (default: 0.98).
+        v_th: Base threshold voltage (default: 1.0).
+        beta_scale: Adaptation scaling factor (default: 1.8).
+        batch_first: If True, input tensor shape is (batch, time, features).
+    """
+
+    def __init__(
+        self,
+        input_size: int,
+        hidden_size: int,
+        beta: float = 0.93,
+        beta_a: float = 0.98,
+        v_th: float = 1.0,
+        beta_scale: float = 1.8,
+        batch_first: bool = True,
+    ):
+        super().__init__()
+        self.input_size = input_size
+        self.hidden_size = hidden_size
+        self.beta = beta
+        self.beta_a = beta_a
+        self.v_th = v_th
+        self.beta_scale = beta_scale
+        self.batch_first = batch_first
+
+        self.W_x = nn.Linear(input_size, hidden_size, bias=True)
+        self.V_x = nn.Linear(hidden_size, hidden_size, bias=False)
+        nn.init.xavier_uniform_(self.W_x.weight)
+        nn.init.orthogonal_(self.V_x.weight)
+
+    def forward(self, x_seq: torch.Tensor) -> torch.Tensor:
+        if not self.batch_first:
+            x_seq = x_seq.transpose(0, 1)
+
+        batch_size, seq_len, _ = x_seq.size()
+        device = x_seq.device
+        dtype = x_seq.dtype
+
+        v_t = torch.zeros(batch_size, self.hidden_size, device=device, dtype=dtype)
+        s_t = torch.zeros(batch_size, self.hidden_size, device=device, dtype=dtype)
+        b_t = torch.zeros(batch_size, self.hidden_size, device=device, dtype=dtype)
+        spikes = []
+
+        for t in range(seq_len):
+            x_t = x_seq[:, t, :]
+            i_t = self.W_x(x_t) + self.V_x(s_t)
+            v_t = self.beta * v_t + i_t
+            
+            theta_eff = self.v_th + self.beta_scale * b_t
+            s_t = surrogate_spike(v_t - theta_eff)
+            v_t = v_t - s_t * self.v_th
+            b_t = self.beta_a * b_t + s_t
+            spikes.append(s_t)
+
+        spikes = torch.stack(spikes, dim=1)
+        if not self.batch_first:
+            spikes = spikes.transpose(0, 1)
+        return spikes