auto-pwa

Partial Wave Analysis (PWA) in high-energy physics demands both deep domain expertise and meticulous execution: querying PDG resonance tables, verifying J^P and J^PC quantum-number constraints, hand-editing config.yml, submitting ctpwa fits, reading ROOT histograms, and deciding whether to add a new resonance. A single oversight in any of these steps can silently produce a physically illegitimate result. auto-pwa wraps the entire workflow into twenty-one structured tools so that an AI agent can drive the full loop—from candidate discovery through numerical fitting to iterative convergence—while strict hard gates intercept every physically invalid edit before it touches the config file. Every mutation passes a full validateConfig check plus PDG cross-referencing, guaranteeing that only consistent configurations are written.\n\nCapabilities span three layers. The decision layer covers PDG-2026 resonance lookup with single-experiment measurement histories, decay-channel J^P and two-vertex J^PC reachability checks, pull-above-3sigma region candidate discovery, fit.json diagnostics (parameter degeneracy, boundary hits, strong interference), Legendre-moment and partial-wave-fraction evaluation, per-bin ROOT histogram reading, arbitrary wave-combination interference comparison, and base-versus-trial delta-NLL / AIC / BIC significance adjudication. The execution layer provides fully validated atomic config.yml editing with atomic writes and backups, parallel candidate short-fits, and DSH background-task submission with real-time status queries. The automation layer implements a goal-driven multi-round state machine: evaluate, convergence judgement, decision persistence (iterate / rollback / converge), and durable state that survives session restarts.\n\nArchitecturally, the pure-physics core in src/ carries 160-plus unit tests and zero DSH dependencies, while the thin integration layer in plugin/ patches into any DSH profile. The built-in AI-first fit driver (aifit.py) runs the identical ctpwa engine and emits a structured fit.json containing parameter uncertainties, the full Hessian correlation matrix, the interference matrix read back from the ROOT file, and partial-wave fractions—so the AI can make physics judgements without parsing free-form text. A reference-outsource mechanism further allows resonance parameters to deviate from PDG averages (for example, to adopt the latest experimental measurement) while retaining every hard physical constraint, optionally cross-checking the cited DOI against the PDG measurement record.\n\nThis plugin is ideal for high-energy physics experimental and theory groups actively performing partial wave analysis, especially teams that want to accelerate multi-round iteration with an AI agent without sacrificing the rigour of physical correctness. It works out-of-the-box on local CUDA GPUs or SLURM clusters (A100 or V100 templates included) with no extra environment setup required.