Getting Started

seamm_thermochemistry is the shared atomic reference-energy database and formation-energy arithmetic for SEAMM. A raw total energy from Gaussian, ORCA, Psi4, or VASP has an arbitrary, code-dependent zero – meaningless to a non-expert user, and not comparable across codes. Re-expressing it as an energy or enthalpy of formation (relative to the elements in their standard states) fixes both problems at once, and this package is the single place that logic and its underlying reference data live, replacing what used to be an independent, largely-duplicated copy in each of gaussian_step, psi4_step, and vasp_step.

Installing

The core library only depends on seamm-util:

pip install seamm_thermochemistry

Two optional extras add more:

• seamm_thermochemistry[import] – pulls in pandas/openpyxl so the legacy Excel/CSV master-file importers in importers are usable.

• seamm_thermochemistry[installer] – pulls in seamm-installer so the seamm-thermochemistry-installer console script can fetch the published reference database from Zenodo.

Fetching the reference database

The reference database itself (thermochemistry.db) is not shipped inside the Python package – it is a growing dataset published separately on Zenodo, with a version DOI for every release. Fetch the local copy with:

seamm-thermochemistry-installer install

which downloads the latest version, verifies it against Zenodo’s own checksum, and registers its location in ~/.seamm.d/seamm.ini’s [thermochemistry] section. seamm_thermochemistry.DEFAULT_DB_PATH then resolves to that location automatically.

seamm-thermochemistry-installer update (which seamm-manager update runs) brings the copy up to the latest published version – but only if the local file is exactly one of the published versions. A database you have edited, for instance with curated or recomputed reference energies, is kept as it is and reported; to replace it with the published version anyway, run seamm-thermochemistry-installer update --force, which saves the old file as thermochemistry.db.bak-<date> first. Every replacement keeps such a backup, and a download is checked before it replaces anything. install never overwrites an existing database, and uninstall leaves one with local changes in place unless given --force.

A quick example

from seamm_thermochemistry import ThermoDB, formation_energy

with ThermoDB("my_reference.db") as db:
    db.add_element(1, "H", dfH0_0K=216.034, standard_state="1/2 H2(g)")
    db.add_element(8, "O", dfH0_0K=246.79, standard_state="1/2 O2(g)")
    db.add_atom_energy("H", "gaussian", "CBS-QB3", -1312.0)
    db.add_atom_energy("O", "gaussian", "CBS-QB3", -197400.0)

    dfE = formation_energy(
        {"H": 2, "O": 1}, system_energy, db, "gaussian", "CBS-QB3"
    )

Two reference conventions, one schema

The ref_type column on atom_energy distinguishes:

• "atom" – the isolated gas-phase atom (Gaussian/Psi4/ORCA’s convention). Pairs with an experimental anchor (element.dfH0_0K/dfH0_298K) to give a true, cross-code-comparable energy/enthalpy of formation.

• "element_phase" – energy per atom of the element’s standard-state phase (bulk metal, graphite, O2(g), …) – VASP’s existing convention, needing no experimental anchor, and useful as a fallback reference for elements (e.g. Mn) where the free atom is a poor DFT target.

formation_energy(..., anchor=True) matches the existing gaussian_step/psi4_step enthalpy-of-formation arithmetic exactly (and gives an energy of formation, not an enthalpy, when the system energy excludes the zero-point energy and the 0 K anchor is used). formation_energy(..., anchor=False) matches vasp_step’s existing DfE0 convention exactly.

Importing ORCA results

Production ORCA atom-energy scans (one CSV per method, covering many basis sets and elements) are imported with:

seamm-thermochemistry-import-orca results.csv

Each value is vetted against its expected total spin (S^2) before being added, and duplicate values already in the database are left alone unless they conflict – see seamm_thermochemistry.importers.import_orca_atom_results() for the full vetting and conflict-resolution rules, including --prefer-lower-energy for the hard-atom case where two runs converge to different, equally spin-clean self-consistent solutions.