Engines · hf-energy

Hartree-Fock energy of a molecule, from an XYZ file and a basis name

Give it a molecule as an XYZ file and name a basis. It builds the Gaussian basis the way PySCF does, runs Hartree–Fock through lib/hf in your browser, and prints the energy and the orbital energies. Water in 6-31G takes about three seconds.

What it takes and gives

The engine is engines/hf-energy.viv, 114 lines of Viv that run lib/hf/scf. Its header says what it takes and gives:

#! engine hf-energy
#! title Hartree-Fock energy of a molecule, from an XYZ file and a basis name
#! program lib/hf/scf
#! input molecule: xyz
#! input settings: basis (sto-3g | 6-31g | 6-31g* | cc-pvdz | def2-svp), charge, spin, method (rhf | uhf | rohf), spherical or cartesian
#! output total-energy, orbital-energies
#! limit tab: elements H to Ar, up to an estimated 60 s in the interpreter; larger runs natively with viv run
#! validated water 6-31g: lib/hfref/water_631g.viv
#! validated water cc-pvdz: lib/hfref/water_ccpvdz.viv

input

molecule: xyz

input

settings: basis (sto-3g | 6-31g | 6-31g* | cc-pvdz | def2-svp), charge, spin, method (rhf | uhf | rohf), spherical or cartesian

output

total-energy, orbital-energies

limit

tab: elements H to Ar, up to an estimated 60 s in the interpreter; larger runs natively with viv run

validated

water 6-31g: lib/hfref/water_631g.viv

validated

water cc-pvdz: lib/hfref/water_ccpvdz.viv

What happens to your file

1. The XYZ file is read: symbols (or atomic numbers) and positions in ångström. The comment line may carry basis=, charge= and multiplicity= (or spin=, as N_α − N_β), which fill in the form above.
2. The basis is built as PySCF builds it: its library’s shells, every general contraction split into one shell per column, zero coefficients dropped, ångström converted with PySCF’s own bohr. For water, hydroxyl and ammonia the basis-set data it builds matches lib/hfref’s, number for number.
3. lib/hf runs: overlap, kinetic and nuclear-attraction integrals, the two-electron integrals, the optional transform to spherical functions, and RHF, UHF or ROHF, each stage using the implementation lib/hf uses by default. Then the converged Fock matrix is diagonalized once more for the orbital energies.

The cost estimate is c · P^a · n^b, where P counts primitive Cartesian functions and n basis functions, fitted to 9 runs from water in 6-31G (2.3 s) to ethanol in 6-31G* (374.1 s). It is within 29% of every one of them. A molecule estimated above 60 s, or with more than 60 basis functions, is not offered here.

How it is checked

When lib/hfref holds the same molecule, basis, charge, spin and method, its PySCF energy is handed to the program, which prints the difference; the tests of lib/hf require it to match PySCF to 10⁻⁹ hartree. The orbital energies of water and hydroxyl are compared with PySCF’s in the tests. These are the last recorded runs:

Seconds are timings under Node.js on the machine that ran the tests; a browser tab is usually a little slower. The XYZ reader and basis builder have their own tests: the basis arrays for every example, and inputs that must be refused, each with its reason.

The basis sets come from the Basis Set Exchange. PySCF 2.5.0 (Apache-2.0) is the reference the energies are compared with; no PySCF code is copied.

What it does not do

• Elements past argon, or basis sets other than sto-3g, 6-31g, 6-31g*, cc-pvdz, def2-svp.
• Geometry optimization, correlation, or properties beyond the energy and orbital energies.
• Large molecules in a browser. The integrals grow as the fourth power of the basis; a run estimated above a minute is refused.