Skip to content

Add conformer-ensemble thermochemistry helpers - #80

Merged
galjos merged 2 commits into
mainfrom
ensemble-thermochemistry
Jul 6, 2026
Merged

Add conformer-ensemble thermochemistry helpers#80
galjos merged 2 commits into
mainfrom
ensemble-thermochemistry

Conversation

@galjos

@galjos galjos commented Jul 6, 2026

Copy link
Copy Markdown
Member

What

Adds ThermoScreening.thermo.ensemble, three pure post-processing helpers that combine the absolute Gibbs free energies (Thermo.total_EeGtot(), in Hartree) of several conformers of the same molecule into ensemble properties. Compute each conformer with matching engine/conditions (generatextb_cli_thermo/…), then combine:

  • boltzmann_weights(thermos, temperature=298.15) — normalised conformer populations, evaluated with a min-energy shift for numerical stability.
  • ensemble_free_energy(thermos, temperature=298.15, unit="H") — the Boltzmann-averaged free energy -k_B T ln( Σ exp(-G_i / k_B T) ), which sits at or below the lowest conformer's free energy by the conformational mixing entropy. Units H/eV/kcal/kJ.
  • lowest_gibbs(thermos) — the single lowest-free-energy conformer (to carry a dominant structure forward, e.g. into reaction_free_energy).

All three are exported from ThermoScreening.thermo. This is the natural consumer of the existing conformer generation + screening features.

Refactor

Factors the shared Hartree → eV/kcal/kJ conversions out of reactions.py into a small private _units module (convert_from_hartree), so both post-processing modules use one source of truth. reactions.py public behaviour is unchanged.

Tests

Exact-math and physics checks: degenerate populations (0.5/0.5), single-conformer identity, normalisation + ordering, a known k_B*T-gap ratio (e:1), single-conformer ensemble = its own G, degenerate mixing entropy (G_ens = G - k_B T ln 2 < G), ensemble ≤ minimum, unit conversion, and edge cases (empty ensemble, non-positive temperature, unknown unit).

Docs

API-reference entries plus a "Conformer ensembles" usage section with a worked n-butanol example.

galjos added 2 commits July 6, 2026 22:48
Introduce ThermoScreening.thermo.ensemble with three pure post-processing
helpers that combine the absolute Gibbs free energies of several conformers
of the same molecule (each computed with matching engine/conditions):

- boltzmann_weights(thermos, temperature): normalised populations,
  computed with a min-energy shift for numerical stability.
- ensemble_free_energy(thermos, temperature, unit): the Boltzmann-averaged
  free energy -k_B T ln(sum exp(-G_i / k_B T)), at or below the lowest
  conformer by the conformational mixing entropy.
- lowest_gibbs(thermos): the single lowest-free-energy conformer.

All three are exported from ThermoScreening.thermo. Factor the shared
Hartree unit conversions out of reactions.py into a small _units module so
both post-processing modules use one source of truth. Adds exact-math and
edge-case tests, plus API-reference and usage documentation.
Address review nits: call G_ens the 'ensemble (Boltzmann) free energy'
rather than a literal average, and cover a negative temperature (not just
zero) in the guard test.
@codecov

codecov Bot commented Jul 6, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.92%. Comparing base (89dd177) to head (ba3c8ef).

Additional details and impacted files
@@            Coverage Diff             @@
##             main      #80      +/-   ##
==========================================
+ Coverage   96.85%   96.92%   +0.06%     
==========================================
  Files          26       28       +2     
  Lines        1655     1689      +34     
==========================================
+ Hits         1603     1637      +34     
  Misses         52       52              
Flag Coverage Δ
unittests 96.92% <100.00%> (+0.06%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@galjos
galjos merged commit 9882357 into main Jul 6, 2026
4 checks passed
@galjos
galjos deleted the ensemble-thermochemistry branch July 6, 2026 20:54
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