You can deploy this model and start earning money today!

KD099/
nqr-snn-framework

Name: nqr-snn-framework
Availability: InStock

ml-intern

Views

No views yet

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

python

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.