fix(hessian): Address code review findings from PRs #81-83

[ericchansen]

Summary

Fixes all 8 code review findings from GPT-5.4 and Gemini 3 Pro reviews of PRs #81-83.

Changes

Bug fixes

• Silent method fallback (GPT HIGH): invert_ts_curvature(method="E") or any typo silently fell through to Method C. Now raises ValueError for unsupported values.
• Bogus element-wise check (Gemini HIGH): if not (inv_curv_hessian >= 0.0).all() checked matrix elements, not eigenvalues. Off-diagonal coupling force constants are routinely negative, so this fired false warnings for every real molecule. Removed entirely.
• Fragile index-based locking (both reviewers): detect_problematic_params returned list indices; lock_params used those indices to copy values between force fields with potentially different orderings. Now uses canonical param keys (param.key tuples).

Docstring/accuracy fixes

• Units mismatch (Gemini LOW): replace_neg_eigenvalue docstring said "Hartree/bohr^2/amu^-1" but HESSIAN_CONVERSION has no mass terms. Clarified: operates on Cartesian Hessian eigenvalues, not mass-weighted.
• lock_params honesty: Docstring previously claimed params were "frozen" -- they're only copied. Clarified that set_param_vector can still overwrite them; true freezing requires excluding params from the optimization vector.

Test improvements

• Literature validation (GPT MEDIUM): Added TestLiteratureValidation class with independently sourced force constant ranges (MM3/IR spectroscopy) so ethane tests aren't purely self-referential.
• Natural sort (Gemini MEDIUM): Jaguar .in file glob in parity tests now uses natural sort key so 2.in < 10.in regardless of zero-padding.
• Remove from __future__ import annotations (user): Removed from test_method_d_e.py and test_ethane_seminario.py -- not needed on Python 3.10+. Kept in hessian.py where it's required for TYPE_CHECKING pattern.

Testing

• All 256 tests pass (251 baseline + 5 new literature validation tests)
• 20 skipped (Schrodinger-gated)
• Ruff lint clean

[Copilot]

Pull request overview

Addresses prior review findings around TS Hessian inversion behavior, parameter locking robustness, and test reliability/validation.

Changes:

• Make invert_ts_curvature() reject unsupported methods (no silent fallback) and remove a misleading element-wise negativity check.
• Switch “problematic parameter” detection/locking from list indices to canonical parameter keys.
• Improve tests: add natural sorting for Jaguar inputs and add independent literature-based validation for ethane.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
test/test_method_d_e.py	Updates tests to use key-based locking/problem detection; adds invalid-method assertion.
test/integration/test_seminario_parity.py	Adds a natural sort key for .in files to stabilize parity/benchmark ordering.
test/integration/test_ethane_seminario.py	Adds independent literature-range validation tests for ethane force constants.
q2mm/models/hessian.py	Enforces method validation, clarifies docs/units, and migrates problematic detection/locking to key-based mapping.

---

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