Add validated execution examples to 12 skills and fix bugs they exposed

[bowen-bd]

Summary

Adds validated execution examples to the 12 executable skills that had none. Each example compares its outputs with published literature, an official database release or a theory reference, and gives citations. Running the examples exposed bugs in several skills and in the shared MD code; this PR fixes them.

Examples added

Skill	Example	Reference	Result
chem-db-qmof	HKUST-1 (DOTSOV01)	QMOF figshare release; Chui et al. 1999	Band gap and density identical to the release; a = 26.474 Å vs 26.343 Å exp. (+0.5 %)
chem-db-mof	ARC-MOF ddmof_559	Majumdar et al. 2021; ARC-MOF metadata	Volume, density and Ni₄(μ₃-OH)₂ node stoichiometry match
chem-nmr-predict	ethyl acetate, ethanol	Fulmer et al. 2010; Gottlieb et al. 1997	Ethyl acetate MAE 0.045 ppm; ethanol CH₂ error (0.41 ppm) and missing OH documented
chem-nmr-analysis	camphor reduction; kinetics series	Lopansri et al. 2022; reference-free rate constant	13.1 % borneol vs 12.6 % direct integral (17 % in the paper; gap is in the digitized input); k within 5 %
general-arxiv-search	MACE title lookup; MLIP keyword search	arXiv abs records	All fields match
general-biorxiv-search	DOI lookups; date-range search	bioRxiv API, Crossref	All fields match
mat-dft-mixing-functionals	Fe₂O₃, Al₂O₃, FeS₂	MP corrected energies; Wang et al. 2021	Reproduces MP2020 corrections exactly
mat-elemental-energies	Li, Fe, Cu, O, Si × 4 checkpoints	MP GGA / r2SCAN energies	Within the models' published MAE; Li₂O formation energy within 0.2 meV/atom of MP
mat-md-monitors	Cu NVT, 300 K and 100 K	Equipartition; Dulong–Petit	⟨ΔE_pot⟩ within 3.5 % / 0.7 %; c_v within 1.6 % of 3R
ml-mlip-nvalchemi	batched vs sequential static, strained Cu	stored benchmark table	ΔF = 0, ΔE ≤ 1.9e-6 eV; batched MD re-measured at 1.40× (stored 4.90× does not reproduce), SKILL.md updated
ml-mlip-speed	NaCl up to 2000 atoms, 4 models	stored GB10 reference	ms/atom within 5–18 % and MB/atom within 14 % (uma-s-1p1 now 4.5× faster)

The skills without examples either execute nothing (rules, setup, references, protocols) or need ORCA, which will be tested on another machine.

Fixes

• MD (src/utils/mlips):
  • run_md treated every input as a restart because Atoms.get_velocities() returns zeros, not None, so a perfect crystal started at rest and stayed at 0 K.
  • ExplosionMonitor read the caller's copy of the atoms, not the integrated atoms, so it could never fire.
  • run_md now returns status: "stopped" and stop_reason when a monitor ends a run.
  • final_structure is now the last MD frame rather than the input.
  • Explicitly supplied momenta, including all zeros, are kept (no relaxation or velocity redraw), so NVE starts from rest work.
• chem-nmr-analysis: --baseline-correct subtracts only the minimum, which biases noisy or offset spectra toward 50:50. New --baseline-window (median or max of a signal-free window), --ppm-range with --range-protons (a restricted fit counts only the protons inside the range), a reported noise fraction, and a corrected fit plot. Workflows updated to match.
• general-arxiv-search: multi-word queries were OR-ed (all:a b c), which returned off-topic papers. Terms are now AND-ed, authors are quoted, and categories are combined correctly.
• general-biorxiv-search:
  • Multi-word categories never matched.
  • DOI lookup returned v1 instead of the latest version.
  • medRxiv URLs pointed at bioRxiv.
• chem-db-qmof / chem-db-mof:
  • Refcode lookup returned nothing.
  • Band gaps were never saved.
  • ddmof_42 matched ddmof_4291.
  • --elements now requires all listed elements by default; --element-match any covers mixed-metal sets.
  • SKILL.md described downloads, file names and charges the code does not use.
• mat-elemental-energies:
  • Corrected O and Cl references where the molecular crystal collapsed during relaxation: MACE-MP-medium, MACE-MH-0 (three heads), MACE-MATPES-PBE-0 and MACE-MP-small.
  • Regenerated the TensorNet r2SCAN and PBE v2025.1 files with the weights now loaded under those names (adds the missing TensorNet-MatPES-PBE-v2025.1-PES alias).
  • The documented command now works from the repository root.
• ml-mlip-speed: the plot-only step read a different file from the one runs write.
• Citations: SPINUS (Anal. Chem. 2002), Lopansri et al. 2022 (replacing a citation that could not be found), and Burner et al. 2023 (ARC-MOF).

Known follow-ups (not in this PR)

• Deprecate CHGNet-MPtrj-2023.12.1-2.7M-PES in favour of CHGNet-PES-MatPES-*-1M-2026.9, and deprecate M3GNet (the M3GNet-MP-2021.2.8-PES alias currently loads MatPES-PBE weights; the M3GNet-MatPES-v2025.1 library files are stale).
• ORCA examples, to be tested on another machine.

Testing

• venv/run cpu python -m pytest tests/test_*.py -q: 1082 passed, 5 skipped. New: tests/test_chem_nmr_baseline.py and four tests in tests/test_md_utils.py.
• tools/check_skill_commands.py passes; pre-commit hooks pass.
• Every example command was re-run from the repository root.

🤖 Generated with Claude Code