How to Calculate Molecular Electronic Properties with Psi4: Energy, HOMO–LUMO Gap, and Dipole

Table of contents

• Scientific introduction
  • What an electronic-properties calculation answers
• Hartree–Fock in practical terms
• What the STO-3G basis means
• HOMO, LUMO, and the orbital gap
• Dipole moment and coordinate frames
• Test progress
• Demo user request
• Demo data
• Reproducibility
• Validated workflow
• Results and artifacts
• How to interpret and extend the calculation
• Limitations
• References
• Try this workflow

Electronic-structure calculations turn a molecular geometry, charge, multiplicity, method, and basis set into quantitative predictions about electrons and energy. This worked example uses Psi4 1.11 to perform a restricted Hartree–Fock single-point calculation with the STO-3G basis for neutral singlet water. The validated run reports a total electronic energy of −74.9630783753 hartree, a HOMO energy of −0.3912317659 hartree, a LUMO energy of 0.6053476877 hartree, a frontier-orbital gap of 0.9965794536 hartree, and a dipole vector of (0, 0, 0.6787236267) debye in the program’s molecular frame.

Those numbers are useful because every one of them can be traced to the same unchanged XYZ geometry and reopened from retained JSON, CSV, and text outputs. They are not a high-accuracy prediction of experimental water properties. RHF/STO-3G is deliberately inexpensive and pedagogical: it verifies the workflow while exposing the limitations of a minimal basis and a mean-field wavefunction.

Scientific introduction

What an electronic-properties calculation answers

A single-point calculation evaluates the electronic state at fixed nuclear coordinates. It does not optimize the geometry, sample conformations, calculate a reaction path, or simulate finite-temperature motion. Its central output is the electronic energy associated with the specified model. The same converged wavefunction can also provide molecular-orbital energies, density-derived multipoles, population analyses, and other properties.

The phrase “electronic properties” is broad. A scientifically complete request should therefore name the geometry source, charge, spin multiplicity, electronic-structure method, basis set, and required observables. If any of these are omitted, software may still run but the result can answer a different question. In this test, the geometry came from data/water.xyz, the charge was zero, the multiplicity was one, the method was restricted Hartree–Fock, and coordinates were not changed.

Water is a useful regression molecule because it is small, closed shell, and quick to calculate on a CPU. It is not used here because STO-3G is the recommended model for accurate water thermochemistry. A larger basis, electron correlation, careful geometry preparation, and possibly environmental effects would be needed for many research questions.

Hartree–Fock in practical terms

Hartree–Fock approximates the many-electron wavefunction by one antisymmetrized product of spin orbitals. Each electron moves in an average field generated by the nuclei and the other electrons. The orbitals and effective field are solved self-consistently: an initial density produces a Fock matrix, diagonalization produces new orbitals, the density is rebuilt, and the cycle repeats until energy and density changes satisfy convergence thresholds.

For a neutral water molecule in its ground state, ten electrons occupy five doubly occupied spatial orbitals. Restricted Hartree–Fock uses the same spatial orbital for paired alpha and beta electrons. That restriction is appropriate for this closed-shell singlet fixture. It would be inappropriate to apply blindly to many radicals, bond-breaking structures, transition-metal states, or systems with strong multireference character.

Hartree–Fock includes exchange exactly within its single-determinant model but omits dynamical electron correlation. Consequently, its absolute energies are not directly comparable with experiment, and differences between states can have systematic errors. The calculation remains important as a conceptual baseline and as a reference wavefunction for post-Hartree–Fock methods.

What the STO-3G basis means

A basis set represents molecular orbitals as combinations of atom-centred functions. STO-3G is a minimal basis: each occupied atomic orbital is represented by a contracted function built from three Gaussian primitives. Its small size makes calculations fast and predictable, which is ideal for a lightweight software test.

Minimal does not mean universally adequate. STO-3G has limited flexibility for polarization, diffuse electron density, hydrogen bonding, anions, excited states, response properties, and quantitative energy differences. A larger split-valence or correlation-consistent basis can substantially change the energy, frontier orbitals, and dipole. Basis-set convergence should be studied when numerical accuracy matters.

The method and basis must always be reported together. “Hartree–Fock energy” without a basis is incomplete because the variational space changes with the basis. Likewise, comparing orbital gaps from unrelated methods and bases as though they were directly equivalent is unsafe.

HOMO, LUMO, and the orbital gap

The highest occupied molecular orbital, or HOMO, is the occupied orbital with the greatest canonical orbital energy. The lowest unoccupied molecular orbital, or LUMO, is the first virtual orbital above it. In the retained calculation, the fifth orbital is the HOMO at −0.3912317659 hartree and the sixth is the LUMO at 0.6053476877 hartree.

The reported gap is calculated directly:

gap = LUMO − HOMO
    = 0.6053476876957781 − (−0.3912317658630167)
    = 0.9965794535587948 hartree

The validator recomputed this subtraction instead of trusting the stored gap field. It also matched the JSON values to the occupied and virtual rows in the CSV. This catches errors such as selecting the wrong orbital, mixing units, or writing stale summary data.

A Hartree–Fock HOMO–LUMO gap is not automatically an optical excitation energy or an experimental band gap. Canonical orbital energies belong to the chosen mean-field model. Koopmans-style interpretations can be useful under restrictive assumptions, especially for ionization, but orbital relaxation and electron correlation matter. Excitation energies generally require an excited-state method, while solids require concepts and boundary conditions different from this isolated-molecule example.

Dipole moment and coordinate frames

The electric dipole moment measures the first moment of charge distribution. For water, the bent geometry and unequal electronegativity create a nonzero molecular dipole. Psi4 evaluates electronic and nuclear contributions and reports the total vector in the active coordinate frame.

The retained vector is (0, 0, 0.6787236267) debye. Its x and y components vanish by the chosen orientation and molecular symmetry, while the z component is nonzero. Rotating the molecule would rotate the components without changing the vector magnitude. Therefore, comparing component signs across programs or differently oriented geometries is not meaningful unless coordinate frames are aligned.

The calculated magnitude is model dependent. Geometry, basis, correlation treatment, and environment affect it. The result verifies that a physically nonzero dipole was generated from the supplied bent water structure; it does not claim experimental accuracy.

Test progress

Demo user request

The real end-to-end request was conversational:

Load the neutral water geometry from data/water.xyz and calculate an RHF/STO-3G single-point energy without changing those coordinates. Report total energy, HOMO and LUMO energies, orbital gap, and dipole vector. Save JSON, orbital CSV, and complete Psi4 text output at the declared paths.

The XYZ file contains three atoms and explicit angstrom coordinates:

3
Neutral water geometry in angstrom
O  0.000000  0.000000  0.000000
H  0.000000  0.757160  0.586260
H  0.000000 -0.757160  0.586260

Supplying the actual file is essential. An earlier failed attempt said “supplied geometry” without attaching the data, so the agent invented coordinates and obtained an energy outside the expected regression interval. The failure was retained, the demo input and skill instructions were corrected, and a fresh attempt was run. This illustrates why successful program execution is not sufficient evidence of scientific correctness.

Demo data

The tracked water.xyz fixture contains only element symbols and Cartesian coordinates; it carries no private or restricted data. The comment line declares its scientific role, while the request supplies charge and multiplicity. Keeping the fixture separate from the calculation script proves that the conversational workflow reads user data instead of reproducing hard-coded coordinates.

Reproducibility

Psi4 1.11 was installed from conda-forge in a skill-owned Python 3.11 environment. A micromamba dry run resolved 101 packages with a fresh-host download total of 447,057,426 bytes, below the strict 500,000,000-byte automatic-test cap. The installed environment was retained for investigation and future regression tests.

The transparent command pattern is:

python scripts/tool.py info
python scripts/tool.py install
python scripts/tool.py probe
python scripts/tool.py run -- python calculation.py outputs

Users do not need to write these commands or the calculation script when using the conversational workflow described at the end of this article. They are shown so researchers can audit how package isolation, probing, and execution are connected.

For reproducibility, record the Psi4 version, Python version, platform, architecture, package source, molecular coordinates, coordinate units, charge, multiplicity, basis, reference, SCF options, memory, thread count, convergence criteria, and output checksums. A process exit code should never replace inspection of convergence messages and numerical results.

Validated workflow

The workflow read the XYZ file, constructed a neutral singlet molecule, disabled geometry optimization, selected RHF/STO-3G, limited execution to one CPU thread, and ran the self-consistent-field calculation. It then evaluated the dipole, read alpha-orbital eigenvalues, identified occupied and virtual orbitals from the electron count, and wrote three durable deliverables.

energy, wavefunction = psi4.energy(
    "scf", molecule=molecule, return_wfn=True
)
psi4.oeprop(wavefunction, "DIPOLE")
orbital_energies = wavefunction.epsilon_a().np

The semantic validator reopened every file. It asserted a plausible water energy interval, a lower HOMO than LUMO, exact arithmetic agreement for the gap, three finite dipole components with a nonzero molecular-axis component, occupied and virtual CSV rows, agreement between CSV frontier orbitals and JSON, and the expected RHF, basis, energy, and dipole sections in the complete Psi4 report.

Results and artifacts

The focused application screenshot shows the rendered scientific result and table rather than a file explorer, raw JSON editor, or unrelated sidebar. The other views are generated directly from retained artifacts, and their hashes and sources are recorded in provenance manifests.

How to interpret and extend the calculation

The strongest supported conclusion is narrow: Psi4 1.11 on Linux x86_64 CPU correctly consumed the tracked water geometry, converged the requested RHF/STO-3G wavefunction, and produced internally consistent energy, orbital, gap, and dipole outputs. The test demonstrates installation, natural-language orchestration, execution, artifact production, and semantic verification.

For quantitative research, first decide what observable is needed. Geometry optimization requires gradients and convergence criteria. Vibrational frequencies require a stationary point and Hessian calculation. Reaction energies require consistent methods and carefully defined states. Solvation needs an explicit or implicit environment. Accurate ionization, electron attachment, or excitation requires methods appropriate to those processes.

Convergence should be examined rather than assumed. Difficult systems can oscillate, converge to an unintended state, break symmetry, or depend on the initial guess. Spin contamination, basis linear dependence, near degeneracy, and multiple electronic solutions may need expert attention. Saving the complete text output is therefore as important as saving a compact JSON result.

Unit handling deserves explicit checks. One hartree is a large energy unit, and conversions to electronvolts or kilojoules per mole must distinguish absolute energies from energy differences. Dipole components should state debye or atomic units. XYZ files conventionally use angstrom, while many internal quantum-chemistry quantities use bohr. Silent unit assumptions can produce plausible-looking but invalid calculations.

Limitations

This case validates one closed-shell molecule, one geometry, one reference, one basis, and a small set of observables. It does not validate geometry optimization, correlated energies, density-functional approximations, excited states, open-shell references, periodic systems, relativistic effects, solvent models, large molecules, distributed execution, or GPU acceleration.

The fixture is intentionally lightweight. Agreement with the regression interval demonstrates correct software behavior, not chemical accuracy. The orbital energies and dipole should not be compared with experiment without understanding the theoretical approximation. Cross-platform numerical differences may occur, and macOS, Windows/WSL, ARM64, and other library builds require separate validation.

References

1. Smith et al., “Psi4 1.4: Open-source software for high-throughput quantum chemistry,” Journal of Chemical Physics 152, 184108 (2020).
2. Psi4 documentation.
3. Psi4 SCF documentation.
4. Psi4 basis-set documentation.
5. Szabo and Ostlund, Modern Quantum Chemistry: Introduction to Advanced Electronic Structure Theory.

Try this workflow

MindPlot has built-in support for this scientific skill. You can attach a molecular geometry and describe the desired energy, frontier-orbital, or dipole calculation in ordinary language. Users do not need to write the Python or shell commands shown above: the MindPlot agent prepares and runs the calculation, checks the outputs, and returns inspectable tables and files. Try it at mindplot.ai, or download the desktop version for a better experience and stronger local-data privacy.