fix: Address code review findings (bugs, DRY, lint, docs)

[ericchansen]

Summary

Address findings from a comprehensive multi-model code review (Claude Opus, Gemini 3 Pro, GPT-5.3 Codex). Fixes bugs, eliminates code duplication, tightens lint config, and corrects documentation.

Changes

Bug Fixes

• License mismatch: pyproject.toml and README.md now correctly say MIT, matching the LICENSE file and upstream nsf-c-cas/q2mm
• Gaussian parser bare except:: replaced with except StopIteration: to avoid silently masking parse errors (parsers/gaussian.py)
• .fchk Charge field over-broad match: line.startswith("Charge") also matched "Charges" array sections, silently corrupting the parsed molecular charge. Fixed to "Charge " (trailing space) (optimizers/objective.py)
• Incomplete _ATOMIC_SYMBOLS: expanded from 22 to 103 elements (Z=1-103). Unsupported atomic numbers now raise ValueError instead of silently producing "X{z}" fallback symbols that cause KeyError downstream (optimizers/objective.py)

DRY Refactors

• Centralize parameter matching: added match_bond(), match_angle(), match_vdw() to ForceField, eliminating duplicated cascade logic in OpenMM and JAX backends (models/forcefield.py, backends/mm/openmm.py, backends/mm/jax_engine.py)
• Centralize covalent radii: TinkerEngine._detect_bonds() now imports COVALENT_RADII from molecule.py instead of maintaining a separate dict with inconsistent values (Cl: 0.99 vs 1.02, Br: 1.14 vs 1.20) (backends/mm/tinker.py)

Hygiene

• Removed empty subpackages: q2mm/forcefields/ and q2mm/io/ contained only __pycache__ but were shipped in the distribution
• Tightened ruff config: removed global F821 (undefined name) and E722 (bare except) suppressions; moved to per-file ignores for legacy parser modules only (pyproject.toml)
• Fixed TYPE_CHECKING import: resolved F821 for Q2MMMolecule type hint in forcefield.py

Documentation

• Updated package structure in docs/getting-started.md (removed phantom forcefields/ and io/ modules)
• Fixed contradictory performance claim in docs/performance.md (was "1.6x faster", should be "~150x higher throughput")
• Fixed import path in examples/ethane/README.md (q2mm.io -> q2mm.parsers)

Testing

• All 356 tests pass, 44 skipped (backend-specific), 0 failures
• ruff check passes with zero violations

[Copilot]

Pull request overview

This PR addresses prior review findings by fixing several parsing/metadata bugs, centralizing repeated parameter-matching logic across MM backends, tightening lint configuration, and correcting documentation/examples to reflect the current package structure.

Changes:

• Fixes parsing correctness issues in Gaussian .out/.fchk handling and improves .fchk element/charge robustness.
• Refactors OpenMM and JAX backends to reuse centralized ForceField parameter matching helpers; aligns Tinker bond detection radii with the shared molecule model.
• Updates license metadata and refreshes docs/examples to match the current module layout; tightens Ruff ignores to targeted per-file exceptions.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Updates stated project license to MIT to match LICENSE.
q2mm/parsers/gaussian.py	Replaces bare except with except StopIteration during parsing.
q2mm/optimizers/objective.py	Fixes .fchk charge header matching; expands atomic number → symbol mapping and raises on unsupported Z.
q2mm/models/forcefield.py	Adds centralized match_bond/match_angle/match_vdw helpers; fixes TYPE_CHECKING import for molecule typing.
q2mm/backends/mm/tinker.py	Uses shared COVALENT_RADII from molecule.py for bond detection.
q2mm/backends/mm/openmm.py	Delegates bond/angle/vdW matching to ForceField.match_* helpers (DRY).
q2mm/backends/mm/jax_engine.py	Delegates bond/angle/vdW matching to ForceField.match_* helpers (DRY).
pyproject.toml	Updates license metadata/classifier; tightens Ruff ignores to per-file F821 for legacy parsers.
examples/ethane/README.md	Fixes import path (q2mm.parsers instead of removed q2mm.io).
docs/performance.md	Corrects OpenMM vs Tinker performance statement.
docs/getting-started.md	Updates package tree to reflect current modules (removes non-existent packages).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.