Fix read_orca_hess silently returning energy=0.0 for ordinary jobs - #108
Merged
Conversation
Verified against a real ORCA 6.1.1 calculation (water, HF/STO-3G, Freq): $act_energy in the .hess file is 0.000000 for an ordinary geometry optimization + frequency job. It is a relaxed-surface-scan field (alongside $act_atom/$act_coord, both 0 here too) that ORCA only populates meaningfully for scan jobs, so a plain .hess carries no reliable electronic energy for the common case. read_orca_hess previously treated $act_energy as the energy unconditionally, so a real ORCA .hess (without an explicit energy= override) silently returned 0.0 Hartree instead of the true SCF/DFT energy -- wrong thermochemistry with no error. The bug went undetected because the existing test fixture was a hand-written synthetic .hess with a plausible nonzero $act_energy. Fix: prefer the companion <basename>.property.txt file ORCA writes alongside the .hess ($Single_Point_Data / &FinalEnergy, its own machine-readable output); fall back to a nonzero $act_energy (for relaxed-scan use); otherwise None (unchanged contract, still requires an explicit energy= from the caller). Add the real captured water_freq.hess + water_freq.property.txt as test fixtures and a regression test reproducing the exact bug (a literal 0.0 $act_energy without a property file must not be read as a real energy). Closes #107
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #108 +/- ##
==========================================
+ Coverage 97.25% 97.27% +0.02%
==========================================
Files 31 31
Lines 1895 1910 +15
==========================================
+ Hits 1843 1858 +15
Misses 52 52
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Review nit: the docstring and the 'no energy' error still described the old (incorrect) $act_energy-only model. Point at the companion .property.txt file instead.
galjos
added a commit
that referenced
this pull request
Jul 8, 2026
Small docs-only addition following the ORCA/Gaussian/Turbomole real-software validation work (#108, #110, #112): a brief note in the QM-import usage section stating that `orca_thermo`/`cclib_thermo` are validated against genuine program output, and that unparseable files raise `TSValueError` rather than an arbitrary parser exception. Verified by building the docs locally and visually checking the rendered note (Furo's styled admonition) in the browser. No code changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Found by running a real ORCA 6.1.1 calculation (water, HF/STO-3G, Freq) — the first time this reader (added in #99) was tested against genuine ORCA output rather than a hand-written synthetic
.hess.The bug
$act_energyin the.hessfile is0.000000for an ordinary geometry-optimization + frequency job. Confirmed from the real file:$act_atom/$act_coordare also0— these three fields together describe the active point of a relaxed surface scan, and ORCA only populates them meaningfully for scan jobs. A plain.hesscarries no reliable electronic energy at all.read_orca_hesstreated$act_energyas the energy unconditionally, so a real-world.hess(without an explicitenergy=override) silently returned0.0Hartree instead of the true SCF/DFT energy — wrong thermochemistry, no error. My original synthetic test fixture had a plausible fake nonzero$act_energy, which is exactly why this went undetected.The fix
Prefer the companion
<basename>.property.txtfile ORCA writes alongside every.hess($Single_Point_Data/&FinalEnergy— ORCA's own machine-readable output, verified against the real file to match the.outlog's "FINAL SINGLE POINT ENERGY" to full precision). Fall back to a nonzero$act_energy(genuine relaxed-scan use). OtherwiseNone— same contract as before, still requires an explicitenergy=from the caller.Verification
Captured the real
water_freq.hess+water_freq.property.txtfrom that ORCA run and committed them as test fixtures (tests/data/calculator/orca/). New tests: exact energy match against real output, fullorca_thermoend-to-end (entropy lands at 45.06 cal/mol/K — right at the well-known experimental value for gas-phase water), a direct regression test for the exact bug (literal0.0$act_energywithout a property file →None, not0.0), property-file-wins-over-act_energy, and the property-file-present-but-empty fallback. All 18 tests in the file pass, full suite passes (371 passed, 12 skipped — the skips are pre-existing, DFTB+/xtb-binary-gated), 100% patch coverage onorca.py.Closes #107