radiacode/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Radiacode 103 is a gamma-ray spectrometer isotope identification pipeline. It captures spectra from a Radiacode 103 USB detector, subtracts background radiation, and identifies isotopes using a CNN-FCNN multi-task PyTorch model (VegaModel, 34.5M params, 82 isotopes). The project runs as Docker containers orchestrated by docker-compose.

Architecture

Three Docker containers, each with its own Dockerfile:

• train/ — Generates 50k synthetic spectra and trains VegaModel on GPU. Entrypoint runs generation then training sequentially. Code lives in train/vega_ml/ (synthetic_spectra, training/vega).
• detect/ — Production monitor. Connects to Radiacode 103 via USB, samples every 60s, accumulates spectrum, subtracts background, runs inference, writes JSON state and daily reports. Two scripts: radiacode_monitor.py (main loop) and capture_background.py (24h background capture).
• web/ — FastAPI dashboard on port 8080. Serves a single-page HTML/JS frontend with tabs for spectrum, background, CPS timeline, and history. Reads monitor state from JSON files written by the detect container.

Data flow: detect writes monitor_state.json + cps_log.jsonl + daily reports to /data/ and /logs/ → web reads them (read-only volume mounts). The train container reads/writes /data/synthetic/ and /models/.

Web API Routes

• /api/status — monitor status (connected, CPS, staleness)
• /api/spectrum/current — accumulated spectrum (CsI-corrected, 1023 channels)
• /api/spectrum/difference — background-subtracted spectrum (CsI-corrected)
• /api/background, /api/background/spectrum, /api/background/reference, /api/background/theoretical — background data (live, 24h reference, theoretical CsI(Tl) model)
• /api/cps/timeline — CPS time series
• /api/history, /api/history/{date} — daily detection reports

Key Physics Constants

Energy calibration: E(keV) = 0.33 + 2.97 * channel_index (env vars ENERGY_CALIBRATION_OFFSET and ENERGY_CALIBRATION_SLOPE). The detector has 1024 raw channels but channel 1023 is an overflow bin — only the first 1023 channels (0.33–3036 keV) are used for display and inference. CsI(Tl) crystal with 8.4% FWHM at 662 keV.

CsI(Tl) non-linear response correction: CsI(Tl) has non-proportional scintillation response at low energies, causing peaks to appear at higher energies than their true gamma energy. The correction E_apparent = E_true * (1 + alpha * exp(-E_true/beta)) with alpha=0.37, beta=100 shifts the Am-241 peak from 71.6 keV (apparent) back to 59.5 keV (true). This correction is applied in the inference pipeline (radiacode_monitor.py) and web display, NOT in training data (which uses theoretical energies). Parameters are configurable via CSI_NONLINEAR_ALPHA and CSI_NONLINEAR_BETA env vars.

Commands

# Build all images
docker compose build

# Train model (GPU required, ~30 min on RTX 5060 Ti)
docker compose run --rm train

# Capture 24h background (leave running, no radioactive source nearby)
docker compose run --rm -d --name radiacode-bg detect python capture_background.py

# Start continuous detection monitor
docker compose up detect

# Start web dashboard
docker compose up web

# Run both detect and web
docker compose up detect web

# Test detection manually (inside detect container)
docker compose run --rm -v $(pwd)/test_detection.py:/app/test_detection.py detect python /app/test_detection.py

No test suite exists in this project. No linter is configured.

VegaModel

Defined in train/vega_ml/training/vega/model.py. Input: 1D spectrum (1023 channels). Output: classification logits (82 isotopes, apply sigmoid for probabilities) + activity predictions (Bq, scaled by max_activity_bq=1000). Loss: VegaLoss = BCE(logits) + 0.1 * Huber(activities * mask) — regression only penalizes present isotopes.

Inference pipeline (in radiacode_monitor.py::run_inference):

1. Subtract background from accumulated spectrum → net_rate
2. Apply CsI(Tl) non-linear correction: correct_csi_nonlinear(net_rate) — remaps channels so peaks appear at theoretical energies
3. Normalize with log1p: log1p(corrected) / max(log1p(corrected))
4. Feed to VegaModel → sigmoid → filter by threshold

The model checkpoint (models/vega_best.pt) stores model_config and model_state_dict. At inference, the detect container dynamically imports VegaModel and IsotopeIndex from the mounted vega_ml volume.

Synthetic Spectrum Generation

Detector Physics Model

Training spectra include realistic CsI(Tl) detector effects:

• Energy calibration: E = 0.33 + 2.97 * ch with 1023 channels (matching real detector)
• K-escape peaks: Iodine K-shell X-ray escape at E - 28.5 keV with energy-dependent escape fraction (up to 35% at low energies). Implemented in spectrum_physics.py::_k_escape_fraction()
• Asymmetric peaks: Low-energy tail for peaks below 200 keV (15% tail fraction at 0 keV, 0% above 200 keV). Implemented in spectrum_physics.py::_asymmetric_peak()
• FWHM: Energy-dependent resolution FWHM(E) = 0.084 * 662 * sqrt(E/662) keV (8.4% at 662 keV)

Background Model

The training background uses a realistic CsI(Tl) continuum shape:

• Continuum: Asymmetric hump at ~110 keV (sigma_left=55, sigma_right=50 keV) + Compton tail + noise floor. Calibrated against real Radiacode 103 measurements.
• Isotope peaks: K-40, Pb-214, Bi-214, Ac-228, Pb-212, Tl-208 — with stochastic activity variation per sample.
• Hybrid training: If MEASURED_BACKGROUND_PATH points to a valid .npy file, 70% measured + 30% synthetic continuum is used.
• Background subtraction mode: 10% of training samples are background-subtracted (simulate the inference pipeline)

Training Data Augmentation

• Normalization: log1p (replaces max normalization for better weak-signal detection)
• Low-signal samples: 15% of samples use 0.01–5 Bq activities with 30–300s durations
• Duration range: 30–300 seconds (covers short accumulations to long measurements)
• Activity range: 0.01–100 Bq (covers weak to strong sources)

Configuration

All config is via environment variables in docker-compose.yml. Key variables:

Train container:

• NUM_SAMPLES — number of synthetic spectra (default 50000)
• BATCH_SIZE — training batch size (default 32)
• MIN_DURATION/MAX_DURATION — spectrum duration range in seconds (default 30–300)
• MEASURED_BACKGROUND_PATH — path to measured background .npy for hybrid training

Detect container:

• MODEL_PATH, ISOTOPE_INDEX_PATH, BACKGROUND_PATH — file paths
• VEGA_DEVICE — cpu or cuda
• THRESHOLD — detection probability threshold (default 0.5)
• SAMPLE_INTERVAL — seconds between samples (default 60)
• ENERGY_CALIBRATION_OFFSET/SLOPE — energy calibration constants
• CSI_NONLINEAR_ALPHA/BETA — CsI(Tl) non-linear response correction (default 0.37/100.0)

Web container:

• ENERGY_CALIBRATION_OFFSET/SLOPE — energy calibration constants
• CSI_NONLINEAR_ALPHA/BETA — CsI(Tl) correction parameters (must match detect)