A PySCF tutorial, taught by the diff

PySCF is built so that the basic quantum-chemistry calculations differ from one another by almost nothing — define a molecule, then bolt a method onto it with the same .kernel() verb every time. That makes it a perfect subject for a dictionary of programs: each step below changes one line or adds one method, and the diff is the lesson. Every program is complete and runnable; every number in the output panels is what PySCF actually printed when I ran it (water, run on your machine in seconds).

The chain goes: build a molecule → Hartree-Fock → change the basis → MP2 → CCSD → DFT. Step through with the arrows; changed lines are marked ▸. Hover a line with a left-bar for its rationale.

 from pyscf import gto
  
 mol = gto.M(
     atom="O 0 0 0; H 0 -0.757 0.587; H 0 0.757 0.587",
     basis="sto-3g",
 )
  
 print("electrons:", mol.nelectron)
 print("basis functions:", mol.nao)
 print(f"nuclear repulsion: {mol.energy_nuc():.6f} Ha")

electrons: 10
basis functions: 7
nuclear repulsion: 9.188258 Ha

Reading the energies

Three things the numbers teach, none of which needs you to trust me — they're in the output panels:

• Basis quality is variational (steps 2→3). One line changed sto-3g to cc-pvdz and the RHF energy fell by ~1.06 Ha. A bigger basis can only lower the Hartree-Fock energy toward the basis-set limit, never raise it. The diff isolates that single fact.
• Correlation is a ladder (steps 3→4→5). −76.027 (HF) → −76.231 (MP2) → −76.240 (CCSD). Each rung recovers more of the electron correlation HF averages away, at more cost. The code interface is identical at each rung — wrap the HF object, call .kernel() — which is exactly why the diff is so small.
• DFT is off the ladder (step 6). B3LYP's −76.420 looks "better" because it's lower, but DFT energies aren't variational bounds and don't sit on the same ruler as the wavefunction ladder. The minimal diff hides a conceptual jump; this is the one place the differential method can mislead if you read the number naively.

Stated as a citeable, falsifiable claim: increasing the basis-set size lowers (or holds) the Hartree-Fock energy, because HF is variational in the basis. The experiment is steps 2→3 above; it would be falsified by a basis enlargement that raised the RHF energy, which the variational principle forbids for a properly nested basis.

Read next

• Hartree-Fock — what scf.RHF(mol).kernel() is actually doing inside the SCF loop.
• RHF, UHF, and the ansatz ladder — why "restricted" and when to drop it.
• Ownership in C++, by the diff — the same differential-learning format applied to a different domain.
• Claims — the dictionary-of-programs idea this page is an instance of.