# nsram — Neuro-Synaptic RAM Simulator

The first open-source Python library for simulating NS-RAM floating-body transistor neurons with charge-trapping synaptic plasticity.

Based on: Pazos et al., *"Synaptic and neural behaviours in a standard silicon transistor"*, Nature 640, 69-76 (2025).

## Installation

```bash
pip install nsram              # CPU only (numpy)
pip install nsram[gpu]         # GPU acceleration (PyTorch)
pip install nsram[all]         # Everything (GPU + plotting + ODE solvers)
```

## Quickstart

```python
from nsram import NSRAMReservoir, rc_benchmark

# Create 128-neuron reservoir with heterogeneous short-term plasticity
res = NSRAMReservoir(N=128, stp='heterogeneous')

# Run reservoir computing benchmarks
results = rc_benchmark(res)
# XOR-1: 90.3%, MC: 2.29, NARMA-10: 0.52, Wave-4: 92.5%
```

## What is NS-RAM?

NS-RAM (Neuro-Synaptic Random Access Memory) is a standard CMOS floating-body transistor that exhibits both neuron-like spiking and synapse-like plasticity from device physics alone — no special materials or processes required.

**Key device physics simulated:**
- Impact ionization avalanche (Chynoweth model): `I_aval = I0 × exp((Vcb - BVpar) / Vt)`
- Breakdown voltage control: `BVpar = 3.5 - 1.5 × Vg1` (gate-tunable, from Pazos SPICE)
- Temperature dependence: `BVpar(T) = BVpar × (1 - 21.3μ × ΔT)`
- SRH charge trapping: `dQ/dt = k_cap(Vg2) × (1-Q) × rate - k_em × Q`
- VG2-controlled mode switching (neuron ↔ synapse)

## Novel Finding: Charge Trapping = Tsodyks-Markram STP

This library implements the mapping between NS-RAM charge trapping and the Tsodyks-Markram short-term plasticity model:

| NS-RAM physics | TM-STP neuroscience |
|---|---|
| Q (trapped charge) | 1 − x (depleted resources) |
| k_cap(VG2) | U (utilization) |
| 1/k_em | τ_rec (recovery time) |
| ΔVth = −αQ | PSP amplitude modulation |

VG2 voltage controls the STP type: low VG2 → depression, high VG2 → facilitation.

## API Reference

### `NSRAMReservoir(N, stp, connectivity, ...)`

| Parameter | Default | Description |
|---|---|---|
| `N` | 128 | Number of neurons |
| `stp` | `'heterogeneous'` | STP mode: `'none'`, `'std'`, `'stf'`, `'heterogeneous'` |
| `connectivity` | `'sparse'` | `'sparse'` (15%), `'small_world'`, `'dense'` |
| `spectral_radius` | 0.90 | Recurrent weight spectral radius |
| `variability` | 0.10 | Die-to-die parameter variability |
| `backend` | `'auto'` | `'numpy'`, `'torch'`, `'auto'` |

### `rc_benchmark(reservoir, n_steps, n_reps)`

Runs XOR (τ=1,2,5), Memory Capacity, NARMA-5/10, and 4-class waveform classification.

### Lower-level API

```python
from nsram import NSRAMParams, NSRAMNetwork
from nsram.physics import breakdown_voltage, avalanche_current, srh_trapping

# Direct physics calculations
bvpar = breakdown_voltage(Vg1=0.40, temperature=350)
I_aval = avalanche_current(Vcb=2.5, Vg1=0.40)

# Custom network
params = NSRAMParams(N=256, variability=0.20, bg_frac=0.90)
net = NSRAMNetwork(N=256, params=params, connectivity='small_world')
result = net.run(input_signal, noise_sigma=0.01)
```

## Device Parameters

Default parameters from Pazos et al. SPICE model (Zenodo: 13843362):

| Parameter | Value | Source |
|---|---|---|
| BVpar₀ | 3.5 V | BJTparams.txt |
| dBVpar/dVg1 | -1.5 V/V | BJTparams.txt |
| Tbv1 | -21.3 μ/K | Davalanche.txt |
| Is | 1×10⁻¹⁶ A | BJTparams.txt |
| Bf | 50 | BJTparams.txt |
| Vth₀ (NMOS) | 0.432 V | PTM130bulk_lite.txt |
| Energy/spike | 21 fJ | Nature 640 |
| Cell area (1T) | 8 μm² | Nature 640 |
| Cell area (2T) | 17 μm² | Nature 640 |

## Citation

If you use this library, please cite:

```bibtex
@article{pazos2025nsram,
  title={Synaptic and neural behaviours in a standard silicon transistor},
  author={Pazos, Sebastian and others},
  journal={Nature},
  volume={640},
  pages={69--76},
  year={2025}
}
```

## License

Apache 2.0
