How to Calculate Electronic Reaction Energy with Psi4 and Compare Basis Sets

Table of contents

• Scientific introduction
• The reaction-energy equation
• Test progress
• Demo user request
• Demo data
• Installation and reproducible execution
• Calculated species energies
• Results and artifacts
• How to interpret basis-set sensitivity
• Reproducibility and artifact audit
• Limitations
• References
• Try this workflow

Scientific introduction

Reaction energies connect molecular electronic structure with chemical change. At the simplest quantum-chemical level, an electronic reaction energy is the stoichiometric difference between product and reactant electronic energies. Although the arithmetic is short, a defensible calculation requires balanced stoichiometry, consistent molecular charge and multiplicity, explicit geometries, the same electronic-structure method across every species, converged self-consistent-field solutions, transparent unit conversion, and careful language about what the number does and does not represent.

This worked example studies the fixed-geometry fluorination reaction H₂ + F₂ → 2 HF with restricted Hartree–Fock calculations in Psi4 1.10.2. It deliberately compares STO-3G and 6-31G. The small molecules make a CPU test practical, while fluorine makes basis-set sensitivity conspicuous. The purpose is not to propose a production thermochemistry protocol. It is to demonstrate an auditable calculation in which every molecular energy, electron count, basis-function count, reaction sum, conversion, native log, table, and figure can be independently checked.

Electronic energy is only one contribution to chemical thermodynamics. A fixed-geometry SCF energy difference omits geometry relaxation, zero-point vibrational energy, thermal vibrational and rotational terms, translational contributions, pressure–volume work, entropy, solvent effects, and standard-state corrections. It is therefore ΔE_elec, not automatically an enthalpy ΔH, Gibbs free energy ΔG, activation barrier, or experimental heat of reaction. This distinction is a core validation requirement rather than a footnote.

The reaction-energy equation

For a reaction with stoichiometric coefficients νᵢ, the electronic reaction energy is ΣᵢνᵢEᵢ, using positive coefficients for products and negative coefficients for reactants. For this case, ΔE = 2E(HF) − E(H₂) − E(F₂). Every term must use the same method, basis set, geometry convention, charge convention, and numerical settings. Mixing levels of theory would make the subtraction difficult to interpret even if each isolated energy converged.

Atom balance is checked before expensive computation. Both sides contain two hydrogen atoms and two fluorine atoms. Charge and spin also matter: H₂, F₂, and HF are represented as neutral closed-shell singlets, so restricted Hartree–Fock is internally consistent with the supplied states. The wavefunction metadata provides an additional audit: nα + nβ equals the total electron count for all six species/basis calculations.

Psi4 returns energies in Hartree. The workflow converts the reaction difference with 1 Hartree = 627.509474 kcal/mol. Conversion is applied after the stoichiometric sum, and both units are retained. Keeping the Hartree value makes the relation to native output transparent; kcal/mol is convenient for chemical interpretation.

Test progress

The original real chat attempt already produced valid artifacts. Because it predated the current publication schema, a separate semantic validator was added rather than assuming that a green lifecycle label implied scientific correctness. That validator re-read the retained JSON and CSV files, checked exact numerical tolerances, verified six calculation records, checked electron arithmetic and basis counts, and required substantial native Psi4 and visualization files.

Demo user request

Use the installed reaction-energy skill and hydrogen-fluorination.json to calculate the fixed-geometry electronic reaction energy for H₂ + F₂ → 2 HF with Psi4 1.10.2. Validate atom balance, charges, multiplicities, electron counts, and basis-function counts. Run RHF with STO-3G and 6-31G, preserve the native calculation log, report Hartree and kcal/mol values, compare basis sensitivity, and generate JSON, CSV, PNG, and SVG deliverables. Do not describe the result as enthalpy, Gibbs free energy, activation energy, or experimental heat.

This is a natural-language scientific request, not a hard-coded expected-output script. In the E2E, the agent reads the installed skill and input, authors a task-specific program, executes it through the managed Psi4 environment, then opens and interprets the resulting artifacts. The prompt defines the scientific contract while leaving implementation and tool use to the agent.

Demo data

The fixture hydrogen-fluorination.json stores Cartesian coordinates, molecular labels, charge, multiplicity, reaction coefficients, methods, basis sets, and conversion settings. Explicit coordinates make the calculation reproducible and expose the fixed-geometry boundary. They are demonstration structures rather than optimized minima at either basis set.

A production study should document where geometries came from, whether they were optimized, whether frequency analysis confirmed minima, and whether the same theoretical level was used for optimization and final energy. This compact test intentionally holds coordinates fixed so the energy and bookkeeping paths can be tested quickly on CPU.

Installation and reproducible execution

The skill uses a managed Python 3.11 environment with Psi4 1.10.2. The package boundary prevents an unrelated system installation from silently satisfying the test. Detection invokes both the managed interpreter and Psi4 rather than checking only for a directory. Developers can reproduce the managed boundary with the following commands:

python scripts/install.py
python scripts/tool.py probe
python scripts/tool.py run -- reaction_energy_analysis.py

Interactive users do not need to write these commands or the Python analysis. The agent writes and runs the task-specific program from the chat request. The commands are shown for auditability, troubleshooting, and independent reproduction.

Calculated species energies

Six restricted Hartree–Fock computations converged. Increasing the basis from STO-3G to 6-31G increases the number of basis functions for every molecule and lowers each total electronic energy. Total energies are not compared across different species as standalone stability scores; they enter only through the balanced stoichiometric combination.

The independent validator confirms that each α plus β count equals the expected total. It also confirms positive basis-function counts rather than trusting labels copied into a table. These structural checks catch mislabeled rows, wrong multiplicities, and partial output parsing that can otherwise yield plausible-looking reaction numbers.

Results and artifacts

Both values are negative, but their large separation is the main lesson. The minimal STO-3G basis and split-valence 6-31G basis represent electron distributions differently, especially for fluorine. The comparison demonstrates basis sensitivity; it does not establish that 6-31G is converged or experimentally accurate. A credible production protocol would investigate polarization and diffuse functions, electron correlation, geometry optimization, vibrational corrections, and uncertainty against a suitable reference.

The focused capture presents the scientific result and deliverables inside the chat surface. File explorers, raw JSON editors, and unrelated panels are excluded so the evidence emphasizes the reaction values, basis comparison, and scope warning.

The primary plot was generated from the retained calculation output. It visually communicates that the predicted electronic reaction energy changes substantially with the basis. The JSON and CSV values remain authoritative; the plot is an interpretation aid.

This secondary visual is generated from retained machine-readable results and linked through a SHA-256 provenance manifest. It is not a fabricated scientific image.

How to interpret basis-set sensitivity

A basis set limits the one-electron functions available to represent molecular orbitals. STO-3G uses a compact minimal representation, while 6-31G splits valence flexibility. Because reaction energies subtract large total energies, uneven basis error among reactants and products can strongly affect a comparatively small difference. Fluorine bonding and lone-pair density make this demonstration particularly sensitive.

The more negative 6-31G result should not be called “more correct” solely because the basis is larger. Hartree–Fock neglects electron correlation, the structures are fixed, and neither basis includes all functions needed for a basis-set-limit result. Systematic improvement requires a planned hierarchy and, where appropriate, correlated methods. Basis-set superposition error and size consistency may also matter in other reaction classes.

Reproducibility and artifact audit

Reproduction requires the exact coordinates and stoichiometry, Psi4 version, method, basis labels, SCF reference and algorithm, convergence thresholds, memory and thread settings, unit conversion constant, generated program, and native output. The retained JSON records these settings, while species-energies.csv and reaction-energy-summary.csv provide reviewable tables. The native log establishes that Psi4 actually ran.

The semantic validator checks scientific relationships rather than only file existence. It confirms balance, numerical tolerances, record counts, electron arithmetic, and substantial log and image sizes. A future regression that writes empty files, swaps basis labels, or uses a generic sequence calculation will fail even if the process exits zero.

Independent review should recompute the reaction sum directly from the species table rather than trusting the reported summary column. It should also compare the conversion factor with the recorded constant, inspect the final SCF convergence messages, and confirm that every species used the intended basis. These inexpensive cross-checks are valuable because reaction energies are differences of large numbers: a row-selection mistake can produce a chemically plausible value. Machine-readable JSON supports exact checks, CSV supports quick review, and the native log preserves the evidence needed when a result changes after a software upgrade.

Reviewers should additionally confirm the sign convention by reading the displayed equation and coefficients. Here, products are positive and reactants negative, so a negative value means lower product electronic energy within the stated model. That statement is narrower than spontaneous reaction behavior. Kinetics, entropy, environment, and competing pathways can reverse practical expectations, which is why the equation and scope must accompany every exported number.

Limitations

This case does not optimize structures, perform frequency calculations, add zero-point or thermal corrections, estimate entropy, model solvent, define a standard state, locate a transition state, or compare against experiment. It is not a benchmark of Psi4 accuracy. It tests the key mechanics of balanced fixed-geometry electronic reaction energy on a small CPU-compatible system.

A stronger thermochemistry study would optimize each species at a justified level, verify minima with frequencies, compute ZPE and thermal contributions at the target temperature, apply appropriate standard-state corrections, test correlated methods and basis convergence, and quantify uncertainty. For open-shell species, unrestricted or restricted-open-shell references and spin contamination require additional review.

References

• Psi4 documentation
• Psi4 1.4 open-source molecular electronic structure paper
• Basis Set Exchange
• NIST Computational Chemistry Comparison and Benchmark Database
• Psi4 project repository

Try this workflow

MindPlot includes built-in support for this scientific workflow. Attach molecular geometries and describe the reaction in ordinary language; the agent writes and executes the managed calculation, retains the native and publication artifacts, validates the bookkeeping, and explains the scientific limits. Try it online at mindplot.ai or download the desktop version for stronger privacy and local retained environments.