# NeuroSparkSNT — Supplementary Material & Reproducibility Guide

**Paper:** NeuroSparkSNT: An Eight-Operator Framework for Behavioral
Phase Dynamics in C. elegans Neural Simulation

**Author:** Durhan Yazır, SNT CoreX Dynamics
**Contact:** durhan@sntcorexdynamics.com
**ORCID:** 0009-0007-4304-2066
**Web:** sntcorexdynamics.com

---

## SUPPLEMENTARY FILES

| File | Role | Description |
|------|------|-------------|
| `cook2019connectome.xlsx` | S1 | Structural connectome (Cook et al. 2019, unmodified) |
| `neurosparksnt.py` | S2 | Full model — Models A + B, all 8 operators, ChainTaskPipeline |
| `neurosparksnt_bench.py` | S3 | Paper-grade benchmark suite (B1–B12) |
| `README.md` | S4 | This file — setup and reproducibility guide |

> **Important:** filenames in S1–S3 must be preserved exactly as shown
> (lowercase). The code searches for `cook2019connectome.xlsx` by name.

---

## EXTERNAL DATASETS (auto-downloaded at runtime)

The following datasets are fetched automatically when
`neurosparksnt.py` is executed. No manual download required.

### 1. Kato et al. 2015 — Whole-brain calcium imaging

```
Source : OSF repository
URL    : https://osf.io/2395t/
File   : WT_NoStim.mat (~40 MB)
License: CC0 (public domain)
```

Used for: B1 (AVA-AVB r), B2 (PCA spectrum), B3 (autocorrelation),
B7 (dwell-time ground truth)

If running offline, download `WT_NoStim.mat` manually and place it
in the working directory. The loader detects it automatically.

### 2. OpenWorm connectome (baseline model)

```
Source : GitHub — adammarblestone-zz/simple-C-elegans
URL    : https://raw.githubusercontent.com/adammarblestone-zz/
         simple-C-elegans/master/OpenWorm/connectome.csv
License: MIT
```

Used for: OpenWorm-type HH-ODE baseline construction.

### 3. Cook et al. 2019 — C. elegans connectome

```
Source : Nature supplementary data
URL    : https://doi.org/10.1038/s41586-019-1352-7
File   : cook2019connectome.xlsx  (provided as Supplementary S1)
```

Included directly as S1. Used read-only; no modifications were made.

---

## SYSTEM REQUIREMENTS

- Python 3.9+
- Google Colab (recommended for reviewers) or local environment
- GPU: not required — CPU is sufficient for all benchmarks
- RAM: 8 GB minimum, 16 GB recommended
- Disk: ~250 MB (dataset downloads + model)

### Required packages

```
torch>=2.0
numpy>=1.24
scipy>=1.10
scikit-learn>=1.2
h5py>=3.8
requests>=2.28
pandas>=1.5
openpyxl>=3.1
```

---

## INSTALLATION

### Google Colab (recommended for reviewers)

```python
# Step 1: Install dependencies
!pip install torch numpy scipy scikit-learn h5py requests pandas openpyxl

# Step 2: Upload supplementary files
from google.colab import files
uploaded = files.upload()
# Upload: neurosparksnt.py, neurosparksnt_bench.py, cook2019connectome.xlsx
```

### Local environment

```bash
pip install torch numpy scipy scikit-learn h5py requests pandas openpyxl
# Place all four supplementary files in the same directory
```

---

## RUNNING THE EXPERIMENT

### Step 1 — Load model and baselines

```python
exec(open('neurosparksnt.py').read())
```

Expected output (abridged):

```
NeuroSparkSNT -- Symplectic Neural Topology
====================================================
Connectome: cook2019connectome.xlsx
[1/5] Cook 2019...   N=300, 3669 synapses
[2/5] NeuroSparkSNT...   dim=114
[3/5] Wilson-Cowan...
[4/5] OpenWorm HH-ODE...   OK
[5/5] Kato 2015 PCA...   PC1=18.1%
✓ Ready: ns_snt, ns_snt_b, wc, ow, kato_spec, reg, reg_full
```

### Step 2 — Run full benchmark suite

```python
exec(open('neurosparksnt_bench.py').read())
```

Expected runtime: 15–25 minutes on CPU.
All 12 benchmarks (B1–B12) run sequentially with fixed seeds.
Results are saved to `neurosparksnt_bench_results.json`.

---

## BENCHMARK OVERVIEW

| ID  | Name | Models evaluated |
|-----|------|-----------------|
| B1  | AVA–AVB antagonism | All 4 |
| B2  | PCA spectral fidelity | All 4 |
| B3  | Temporal autocorrelation | All 4 |
| B4  | Power spectrum 1/f β | All 4 |
| B5  | Lyapunov stability | All 4 |
| B6  | Noise robustness | All 4 |
| B7  | Locomotor dwell times | All 4 |
| B8  | Perturbation recovery | All 4 |
| B9  | Emergence score (LOPO) | All 4 |
| B10 | Generative stimulus response | NST-A |
| B11 | Blind biological predictions | NST-A |
| B12 | Chain task completion | NST-A |

### Random seed control

All benchmarks use fixed seeds for full reproducibility:

```python
N_SEEDS = 3          # trials per model
BASE_SEED = 42       # base seed (each trial = BASE_SEED + trial_index)
```

### Running individual benchmarks

After loading the model, any single benchmark can be called by name:

```python
exec(open('neurosparksnt.py').read())
exec(open('neurosparksnt_bench.py').read())

# Individual calls (any subset):
result_b1  = b1_ava_avb()
result_b6  = b6_noise()
result_b7  = b7_dwell()
result_b10, score = b10_generative()
result_b12 = b12_chain_task()
```

### Stimulus types available

| stype | Expected response | Used in |
|-------|-------------------|---------|
| `"none"` | Spontaneous alternation | B1–B9 |
| `"food_odor"` | FWD dominant | B10 calibration |
| `"noxious"` | REV dominant | B10 calibration |
| `"temperature"` | TURN (klinokinesis) | B10 test |
| `"touch_anterior"` | REV (hard) | B10 test |
| `"co2"` | REV (graded) | B10 test |
| `"oxygen_high"` | REV (acute) | B10 test |
| `"yemek_ye"` | APPROACH → CONTACT | B12 |

---

## REPRODUCIBILITY TIPS FOR REVIEWERS

### Tip 1 — Verify B1 (key result) in under 2 minutes

```python
exec(open('neurosparksnt.py').read())

r = ns_snt_b.simulate(
    n_steps=1200, stype="none",
    stim_on=9999, stim_off=10000,
    seed=42, verbose=False)

print(f"NST-B AVA-AVB r = {r['ava_avb_r']:.4f}")
# Expected: r ≈ −0.47 to −0.49  (ground truth: −0.420)
```

### Tip 2 — Verify chain task completion (B12)

```python
r = ns_snt.simulate(
    n_steps=3200, stype="yemek_ye",
    stim_on=1.0, stim_off=150.0,
    seed=42, verbose=False)

TASK_CONTACT = 2
completed = (r["chain_stage_hist"] == TASK_CONTACT).any()
print(f"Chain task completed: {completed}")
# Expected: True
```

### Tip 3 — Verify noise robustness (B6 feature result)

```python
import numpy as np

for sigma in [0.0, 0.1, 0.3, 0.5]:
    r = ns_snt_b.simulate(
        n_steps=1200, stype="none",
        stim_on=9999, stim_off=10000,
        seed=42, verbose=False,
        noise_sigma=sigma)
    print(f"sigma={sigma:.1f}  r={r['ava_avb_r']:+.4f}")
# NST-B should maintain r < -0.05 across the full sigma range
```

### Tip 4 — Verify StimulusAwarenessLayer responses (B10)

```python
for stype in ["touch_anterior", "co2", "oxygen_high", "temperature"]:
    r = ns_snt.simulate(
        n_steps=600, stype=stype,
        stim_on=2.0, stim_off=20.0,
        seed=42, verbose=False)
    pp = r["phase_pcts"]
    print(f"{stype:<18}: REV={pp.get('REV',0):.0f}%  "
          f"TURN={pp.get('TURN',0):.1f}%")
# touch_anterior, co2, oxygen_high → elevated REV
# temperature → elevated TURN
```

### Tip 5 — Hardware independence

Results should be numerically identical across CPU/GPU and across
operating systems (Linux, macOS, Windows) because:

- No GPU-specific operations are used
- `torch.Generator()` with fixed seed is deterministic
- All random state is passed explicitly; no global RNG mutation

If small differences appear (< 0.001 in r values), this is normal
floating-point variance across hardware. Directional results and
benchmark pass/fail criteria are hardware-independent.

---

## DATASET CITATIONS

```bibtex
@article{cook2019connectome,
  title   = {Whole-animal connectomes of both Caenorhabditis elegans sexes},
  author  = {Cook, Steven J. and others},
  journal = {Nature},
  volume  = {571},
  pages   = {63--71},
  year    = {2019},
  doi     = {10.1038/s41586-019-1352-7}
}

@article{kato2015global,
  title   = {Global brain dynamics embed the motor command sequence
             of Caenorhabditis elegans},
  author  = {Kato, Saul and others},
  journal = {Cell},
  volume  = {163},
  number  = {3},
  pages   = {656--669},
  year    = {2015},
  doi     = {10.1016/j.cell.2015.09.034}
}
```

---

## PAPER CITATION

```bibtex
@article{yazir2025neurosparksnt,
  title   = {NeuroSparkSNT: An Eight-Operator Framework for
             Behavioral Phase Dynamics in C. elegans Neural Simulation},
  author  = {Yaz{\i}r, Durhan},
  journal = {Journal of Computational Neuroscience},
  year    = {2025},
  note    = {Under review}
}
```

---

*SNT CoreX Dynamics — sntcorexdynamics.com*