Skip to content

docs: Improve tutorial, fix benchmarks, add molecule constructors#66

Merged
ericchansen merged 1 commit intomasterfrom
docs/tutorial-improvements
Mar 19, 2026
Merged

docs: Improve tutorial, fix benchmarks, add molecule constructors#66
ericchansen merged 1 commit intomasterfrom
docs/tutorial-improvements

Conversation

@ericchansen
Copy link
Copy Markdown
Owner

Summary

Improve tutorial docs from live review, fix flawed performance benchmarks, and enhance API reference.

Changes

Tutorial (docs/tutorial.md)

Performance benchmarks (docs/performance.md)

  • Fix flawed data: L-BFGS-B and Powell previously showed ~0 initial scores because they were run on already-optimized parameters instead of fresh starting points
  • Regenerate all numbers from scripts/generate_benchmarks.py with identical starting params (initial score 42.9 for all methods)
  • Add L-BFGS-B convergence warning (final score 0.93 vs 0.000 for Nelder-Mead/Powell)
  • Update throughput: OpenMM ~190 eval/s (was ~10), Tinker ~1.3 eval/s (was ~6)

API reference (docs/api.md)

  • Add Q2MMMolecule constructors table (from_xyz, from_structure, from_qcel, raw)
  • Add Gaussian log file example
  • Cross-link to tutorial for bond_tolerance details

New script

  • scripts/generate_benchmarks.py -- reproducible benchmark generation so performance data is never hand-written again

Related Issues

Testing

  • mkdocs build --strict passes clean
  • ruff check . passes
  • Benchmark script verified: all methods start from identical params (score 42.9)

Tutorial improvements from live review:
- Add collapsible molecule constructor examples (Gaussian, QCElemental)
- Connect Step 1 QM outputs to Step 2 molecule building
- Combine and clarify bond_tolerance explanation
- Add Hessian eigenmatrix training data warning (not yet ported)
- Replace manual ReferenceData with loop-based extraction from molecule
- Note future automation helper for ReferenceData

Performance benchmarks:
- Fix flawed data where L-BFGS-B/Powell showed ~0 initial scores
- Regenerate from scripts/generate_benchmarks.py with identical starting params
- Add L-BFGS-B convergence warning (final score 0.93 vs 0.000)
- Update throughput numbers (OpenMM ~190 eval/s, Tinker ~1.3 eval/s)

API reference:
- Add Q2MMMolecule constructors table
- Add Gaussian log example
- Cross-link to tutorial for bond_tolerance details

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@ericchansen ericchansen merged commit f855503 into master Mar 19, 2026
6 checks passed
@ericchansen ericchansen deleted the docs/tutorial-improvements branch March 19, 2026 19:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant