--- tags: - ml-intern --- # NQR-SNN Framework v3.2 **Nuclear Quadrupole Resonance Signal Detection using Spiking Neural Networks** Detects 14N-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: 14N 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 14N nuclei: ``` y(t) = A · exp(-t2/2σ2 - t/T2) · exp(i[2πνt + φ]) + ε(t) ``` - **A** — amplitude (∝ nitrogen density) - **σ** — Gaussian decay (inhomogeneous broadening) - **T2** — spin-spin relaxation (~1-10 ms for nitrogen compounds) - **ν** — resonance frequency offset (compound + temperature specific) - **φ** — phase (pulse timing dependent) - **ε(t)** — environmental RF noise (104-105× 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](https://github.com/huggingface/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.
