Validation science: NVE stability probe, TCF spectra (VDOS/IR/Raman/SFG), learning curves

[basillicus]

What

The validation stage grows from parity-only into the actual scientific acceptance test for a MACE model — all folded into the same quality_report.json so every new number thresholds exactly like parity metrics (and becomes an input for the future AL convergence criterion).

• NVE stability probe ([validation.stability]): Langevin equilibration → Velocity-Verlet (NVE) production with a force/energy explosion guard. Metrics: nve_aborted (an exploding model is a result, not a crash), nve_drift_mev_per_atom_ps, nve_energy_std_mev_per_atom, nve_temp_mean. Probes the first n_structures reference frames; worst case reported.
• Spectra from MLIP-driven MD ([validation.spectra], TCF route): one production trajectory → VDOS (mass-weighted VACF, per-element), IR (dipole-derivative ACF), Raman (isotropic/anisotropic invariants → VV/VH/unpolarized/depolarization, (nu_L-nu)^4/nu + Bose prefactors, selectable quantum-correction factor), and SFG (Morita–Hynes dipole–polarizability cross-TCF, signed Im χ⁽²⁾, configurable component/ssp). Artifacts: two-column .dat per spectrum + spectra.json (peaks, params, metrics) under validation/spectra/ — O(1) files. Optional per-spectrum reference files → <name>_spectral_error = 1 − cosine similarity after common-grid Gaussian broadening.
• Dielectric models as calculators: MaceCalc.model_type passes through to MACECalculator so trained AtomicDipolesMACE/AtomicDielectricMACE models load as the spectra property calculator (runtime-gated, same status as the QE ph.x polarizability path). The MD driver and the dielectric model are decoupled.
• SERS: honest scoping — chemical enhancement is implicit when the dielectric model is trained on adsorbed-system DFT data (a docs recipe); electromagnetic enhancement is not computable here, but a user-supplied enhancement_file profile is interpolated and multiplied onto the Raman spectra (raman_*_enhanced.dat).
• Learning curves: traincraft learning-curve CONFIG --fractions ... retrains on nested random subsets (one seeded shuffle, prefixes) and validates every point against one fixed holdout (trainer's own split, never trained on) → validation/learning_curve.json. A diagnostic command, not a stage: no events, no cache keys.
• Loader fix: _resolve_input_paths now also resolves validation.test_file + spectra reference/enhancement paths against the config dir (previously geometry-only — this also closes a latent gap in the remote-execution PR, whose shipped snapshots rewrite test_file to a config-relative path).

Design notes

• validation/spectra.py is pure numpy (no ASE, no I/O), formulas cited to standard literature in docstrings (Thomas et al. PCCP 2013; Berne & Pecora; Ramírez et al. JCP 2004; Morita & Hynes JPCB 2002). Clean-room: no legacy code consulted (verified the legacy tree contains no spectra code).
• Derivative-ACF spectra ≡ harmonic-QCF convention, so qcf="harmonic" is the identity and other choices apply as ratios — one consistent knob instead of double-counted detailed-balance factors.
• run_validation stays parity-only; run_validation_science composes parity + probes and applies thresholds once over the merged metrics (so nve_*/*_spectral_error threshold names work, and probe-referencing thresholds don't explode inside the parity pass).
• Probes are opt-in sub-sections → default validate behavior, report shape, and cache keys unchanged (_stage_inputs already hashes the whole [validation] section).
• No new dependencies (numpy.fft; windowing via np.hanning).

Testing

• test_spectra.py (13): synthetic signals with known answers — peak positions, <cos²>=1/2 ACF, iso mode → depolarization 0, traceless mode → 3/4, QCF classical limits, SFG signal vs quiet component, similarity identity/disjoint, stick-vs-broadened matching.
• test_dynamics.py (7): EMT NVE conservation (<5 meV/atom/ps drift), seeded reproducibility, guard abort → nve_aborted=1 without drift metric, analytic point-charge dielectric capture, hard error on missing requested property.
• test_validation_science.py (7): end-to-end [validation.spectra] → artifacts + spectra.json; self-reference → ir_spectral_error≈0 passes threshold, displaced reference fails it; enhancement profile kills the enhanced curves only; aborted MD is a metric not a crash; config validators; loader path resolution.
• test_learning_curve.py (4): nested-prefix subsets, fixed holdout, rounding-collision dedup, guards, CLI (incl. bad --fractions → exit 2) — via a fake mace_run_train through TRAINCRAFT_MACE_TRAIN_COMMAND.

Full suite: 268 passed, 27 skipped; ruff clean; mkdocs build --strict clean.

Docs

New how-to docs/how-to/validation-science.md (MD-length/timestep/QCF guidance, SFG setup, SERS recipe + limits, learning-curve usage); [validation.stability]/[validation.spectra]/model_type reference tables; traincraft learning-curve CLI reference; agent-skill recipes + gotchas; roadmap tick (EOS/phonons + harmonic spectra stay 🔜).

🤖 Generated with Claude Code

Co-Authored-By: Claude Fable 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_017RmprSjfXNtRV84X9cdkwS