KD099/nqr-snn-framework

NQR-SNN Framework v3.2

Nuclear Quadrupole Resonance Signal Detection using Spiking Neural Networks

Detects ¹⁴N-containing explosives/narcotics (RDX, TNT, HMX, PETN, cocaine, heroin) from NQR receiver RF signals buried in noise at -25 to -50 dB SNR.

v3.2 Results

99.17% mean accuracy across all SNR levels.

SNR (dB)	Accuracy	AUC	F1
-25	99.0%	1.000	0.990
-30	100.0%	1.000	1.000
-35	100.0%	1.000	1.000
-40	98.0%	1.000	0.980
-45	98.0%	1.000	0.980
-50	100.0%	1.000	1.000

All gate checks passed: ✅ -35 dB ≥ 95% ✅ -40 dB ≥ 90% ✅ -50 dB ≥ 80%

Full Pipeline (6 Stages)

python run_full_pipeline.py --quick          # ~90s on CPU
python run_full_pipeline.py                  # full run

Stage	What it does	Key output
1. Denoiser Selection	Evaluates LM, SSA, Wavelet on low-SNR white noise; selects best	denoiser_selection.txt
2. Parallel Neuron Search	5 neuron × 3 surrogate = 15 configs via ProcessPoolExecutor	neuron_search.csv, heatmap
3. Dataset Generation	SNR-controlled signals → denoised → 7-channel feature extraction	train/val DataLoaders
4. Ensemble Training	N-member heterogeneous CNN+SNN ensemble with TET loss	model checkpoints
5. SNR Evaluation	Accuracy/AUC/F1 at each dB level with denoising	snn_accuracy_vs_snr.csv, ROC plots
6. Stress Test	Gaussian, S&P, RFI, weight noise, OOD frequency shift	degradation + OOD plots

Pipeline Data Flow

Raw NQR signal ──→ [Wavelet/SSA/LM Denoiser] ──→ Denoised signal
    ↓                                                    ↓
    └──────────────────────────────────→ [7-channel Feature Extraction]
                                              ↓
                                    real, imag, magnitude,
                                    log-FFT, FFT phase,
                                    unbiased autocorrelation,
                                    instantaneous frequency
                                              ↓
                                    [CNN + SE Attention + Residual]
                                    Conv1d(7→16→32→64) + SE blocks
                                    GlobalAvgPool → 64-dim
                                              ↓
                                    [Learnable Temporal Encoder]
                                    Differentiable time-weighting → T=8
                                              ↓
                                    [SNN Classification Head]
                                    PLIF (learnable τ) + detach_reset
                                    TET loss (per-timestep supervision)
                                              ↓
                                    Detection: ¹⁴N signal / noise

v3.2 Changes (from v3.1)

Bug Fixes

#	Fix	Impact
1	Neuron search → ensemble wiring	Search results now populate ENSEMBLE_CONFIGS dynamically (was dead code — search ran but result was ignored)
2	Encoder train/inference mismatch	LearnableTemporalEncoder used at inference (was DeterministicEncoder), encoder weights saved in checkpoints
3	Early stopping on val_accuracy	Was val_loss — at 99%+ accuracy, loss fluctuates while accuracy plateaus, causing premature stopping

Code Quality

#	Change	Impact
4	Consolidated noise generation	generate_noise_sample() is single source of truth (was copy-pasted 4×)
5	Consolidated denoiser dispatch	denoise_signal()/denoise_batch() in nqr_snn.denoising (was copy-pasted 4×)
6	Removed dead code	RateCodingEncoder, legacy NQRDataset/build_dataloaders/get_balanced_loader removed
7	Removed archive files	Source lives on main branch directly — no more zip/tar.gz clutter
8	Removed dead config	USE_CURRICULUM/CURRICULUM_UNLOCK_FRAC removed (never implemented)
9	Tautological SNR verification	Removed noisy - clean check that always returned target exactly by construction

Hyperparameter Tuning

#	Parameter	Old → New	Why
10	NEURON_SEARCH_EPOCHS	20 → 40	Too few to differentiate neuron types
11	MAX_EPOCHS	200 → 100	Models converge at ~40-60; cosine schedule calibrated
12	EARLY_STOP_PATIENCE	25 → 35	More room for fine-grained improvement

Signal Physics

The NQR receiver detects Free Induction Decay (FID) from ¹⁴N nuclei:

y(t) = A · exp(-t²/2σ² - t/T₂) · exp(i[2πνt + φ]) + ε(t)

• A — amplitude (∝ nitrogen density)
• σ — Gaussian decay (inhomogeneous broadening)
• T₂ — spin-spin relaxation (~1-10 ms for nitrogen compounds)
• ν — resonance frequency offset (compound + temperature specific)
• φ — phase (pulse timing dependent)
• ε(t) — environmental RF noise (10⁴-10⁵× stronger than signal)

CLI Options

--quick                 Fast demo mode (~90s CPU)
--train_size N          Samples per class for training (default: 3000)
--val_size N            Samples per class for validation (default: 1000)
--ensemble_size N       Ensemble members (default: 10)
--max_epochs N          Max training epochs (default: 100)
--n_test N              Test samples per SNR level (default: 300)
--search_workers N      Parallel workers for neuron search (default: auto)
--search_epochs N       Epochs per neuron search config (default: 40)
--skip_denoise          Skip denoiser selection
--skip_neuron_search    Skip neuron search (use PLIF+ATan)
--skip_stress_test      Skip noise injection stress test

Requirements

pip install -r requirements.txt

• PyTorch ≥ 2.1
• SpikingJelly ≥ 0.0.0.0.14 (falls back to MLP without it)
• NumPy, SciPy, scikit-learn, PyWavelets, matplotlib, pandas

Literature References

• PLIF / learnable τ: ParametricLIF node from SpikingJelly; AR-LIF (2507.20746) showed +3-4% on temporal tasks
• TET loss: Temporal Efficient Training from AR-LIF §3, λ=0.5 balances per-timestep + mean loss
• SE attention: Squeeze-and-Excitation Networks (Hu et al. 2018) adapted for 1D signal processing
• Heterogeneous ensemble: STEP (2505.11151) found τ and neuron type matter more than architecture depth
• T=8 timesteps: STEP + AR-LIF show T=4-8 sufficient; lower T reduces BPTT memory 2-4×
• detach_reset: DCLS-Delays (2306.17670) flags this as essential for stable training with T>4
• Instantaneous frequency: Standard NQR detection feature — NQR FID has constant IF vs random for noise

Generated by ML Intern

This model repository was generated by ML Intern, an agent for machine learning research and development on the Hugging Face Hub.

• Try ML Intern: https://smolagents-ml-intern.hf.space
• Source code: https://github.com/huggingface/ml-intern

Usage

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = 'KD099/nqr-snn-framework'
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id)

For non-causal architectures, replace AutoModelForCausalLM with the appropriate AutoModel class.