Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,133 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+tags:
+  - spiking-neural-network
+  - neuromorphic
+  - loihi
+  - temporal-classification
+  - audio
+datasets:
+  - zenke-lab/spiking-heidelberg-digits
+metrics:
+  - accuracy
+model-index:
+  - name: Catalyst SHD SNN
+    results:
+      - task:
+          type: audio-classification
+          name: Spoken Digit Recognition
+        dataset:
+          name: Spiking Heidelberg Digits (SHD)
+          type: zenke-lab/spiking-heidelberg-digits
+        metrics:
+          - name: Test Accuracy (float32)
+            type: accuracy
+            value: 85.9
+          - name: Test Accuracy (int16 quantized)
+            type: accuracy
+            value: 85.4
+---
+
+# Catalyst SHD Spiking Neural Network
+
+A recurrent spiking neural network trained on the [Spiking Heidelberg Digits (SHD)](https://zenkelab.org/resources/spiking-heidelberg-datasets-shd/) benchmark, achieving **85.9% test accuracy** (float) / **85.4% quantized (int16)**.
+
+Trained using the [Catalyst Neuromorphic](https://catalyst-neuromorphic.com) SDK (`neurocore`) with surrogate gradient descent, and deployable directly to Loihi-compatible neuromorphic hardware via the Catalyst Cloud API.
+
+## Model Details
+
+| Parameter | Value |
+|-----------|-------|
+| **Architecture** | Recurrent LIF (Leaky Integrate-and-Fire) |
+| **Input neurons** | 700 (cochlea spike channels) |
+| **Hidden neurons** | 512 (recurrent) |
+| **Output classes** | 20 (digits 0-9, German + English) |
+| **Total parameters** | ~1.49M |
+| **Time bins** | 250 (dt = 4ms, 1s duration) |
+
+## Training Configuration
+
+| Hyperparameter | Value |
+|----------------|-------|
+| Epochs | 200 |
+| Batch size | 128 |
+| Optimizer | AdamW |
+| Learning rate | 1e-3 (cosine annealing) |
+| Weight decay | 1e-4 |
+| Dropout | 0.3 |
+| Gradient clipping | 1.0 norm |
+| Surrogate gradient | Fast sigmoid (scale=25.0) |
+| Membrane decay (hidden) | 0.95 (learnable) |
+| Membrane decay (output) | 0.9 (learnable) |
+| Threshold | 1.0 |
+| Reset mechanism | Hard reset: v = v * (1 - spike) |
+
+## Hardware Deployment
+
+The model is quantized to **int16** for direct deployment on Catalyst neuromorphic hardware (FPGA) and the [Catalyst Cloud API](https://catalyst-neuromorphic.com/cloud):
+
+- Threshold: 1000 (int16)
+- Decay mapping: `decay_v = round(beta * 4096)` (CUBA neurons)
+- Quantization accuracy loss: only **0.4%** (85.9% -> 85.4%)
+
+## Benchmark Context
+
+| Method | SHD Accuracy |
+|--------|-------------|
+| Cramer et al. (2020) | 83.2% |
+| Zenke & Vogels (2021) | 83.4% |
+| **Catalyst (this model)** | **85.9%** |
+
+## Checkpoint Format
+
+PyTorch `.pt` file containing:
+```python
+{
+    'epoch': int,
+    'model_state_dict': OrderedDict,  # PyTorch model weights
+    'test_acc': 0.859,
+    'args': dict  # Complete training arguments
+}
+```
+
+## Usage
+
+```python
+import torch
+
+checkpoint = torch.load("shd_model.pt", map_location="cpu")
+print(f"Test accuracy: {checkpoint['test_acc']:.1%}")
+
+# Load weights into your model
+model.load_state_dict(checkpoint['model_state_dict'])
+```
+
+Or use the Catalyst Cloud API:
+```bash
+pip install catalyst-cloud
+```
+
+```python
+from catalyst_cloud import CatalystClient
+client = CatalystClient(api_key="your-key")
+result = client.simulate(network_config={...})
+```
+
+## Citation
+
+If you use this model, please cite:
+```bibtex
+@misc{shulayevbarnes2026catalyst,
+    title={Catalyst N1: An Open-Design Neuromorphic Processor with Full Loihi Parity},
+    author={Shulayev Barnes, Henry},
+    year={2026},
+    publisher={Zenodo}
+}
+```
+
+## Links
+
+- [Website](https://catalyst-neuromorphic.com)
+- [Cloud API](https://catalyst-neuromorphic.com/cloud)
+- [PyPI: catalyst-cloud](https://pypi.org/project/catalyst-cloud/)
+- [Paper (Zenodo)](https://zenodo.org/records/14868368)