Python-Based Electronic Structure

PySCF

Build molecular electronic-structure workflows in Python, from molecule construction and SCF/DFT to geometry optimization and GPU acceleration.

Role: Programmable ab initio and DFT
Typical input: Python objects, geometry, basis
Typical output: Energies, density matrices, orbitals

1. Molecule construction

A Mole object defines atoms, units, charge, spin, basis, and symmetry. In PySCF, spin is the number of alpha electrons minus beta electrons, not the multiplicity.

Python

from pyscf import gto, dft

mol = gto.M(
    atom="O 0 0 0; H 0 -0.757 0.587; H 0 0.757 0.587",
    basis="def2-svp", unit="Angstrom", charge=0, spin=0,
)
mf = dft.RKS(mol)
mf.xc = "PBE0"
mf.kernel()

PySCF spin convention

Set spin to Nalpha minus Nbeta. A doublet has spin=1, a triplet spin=2, and a closed-shell singlet spin=0.

2. SCF and DFT objects

Choose restricted, unrestricted, or restricted-open-shell references to match the electronic state. Check convergence, orbital occupations, spin, and stability rather than treating a returned energy as sufficient.

mf = dft.RKS(mol).density_fit()
mf.xc = "PBE0"
mf.grids.level = 4
energy = mf.kernel()
if not mf.converged:
    raise RuntimeError("SCF did not converge")

3. Density matrices and properties

make_rdm1() returns a one-particle density matrix. Orbitals, populations, gradients, Hessians, and real-space fields can be accessed from composable Python objects.

4. Geometry optimization

PySCF interfaces with optimizers such as geomeTRIC. Optimize with explicit convergence criteria and verify stationary points with a Hessian or frequency analysis.

Python

from pyscf.geomopt.geometric_solver import optimize
optimized_mol = optimize(mf)

The optimizer calls gradients from the attached method. Recreate the electronic-structure object for the optimized geometry before subsequent properties, and verify the stationary point independently.

5. GPU4PySCF

GPU4PySCF accelerates supported mean-field, DFT, gradient, and Hessian operations. Confirm feature support, GPU precision, memory use, and numerical agreement with a CPU calculation.

Python

from gpu4pyscf.dft import rks

mf_gpu = rks.RKS(mol, xc="PBE0").density_fit()
mf_gpu.kernel()

Supported CPU objects can also be converted with .to_gpu(). GPU acceleration changes the implementation, not the theoretical method; compare representative CPU and GPU energies and gradients within a declared tolerance.

6. Google Colab

Colab is useful for reproducible notebooks, but runtime images and GPU availability change. Pin package versions, record the accelerator, and export inputs and results outside the temporary runtime.

!nvidia-smi
!pip install pyscf gpu4pyscf-cuda12x cutensor-cu12

Select a GPU runtime first. Installation commands depend on the CUDA image, so record the runtime and package versions in the notebook output.

7. Validation and provenance

Save coordinates, units, charge, spin, basis, ECP, functional, and integration-grid settings.
Check SCF convergence, occupations, and spin.
Verify optimized structures by gradients and frequencies.
Record PySCF, GPU4PySCF, CUDA, and optimizer versions.
Export numerical results from temporary notebook runtimes.

8. References

Last reviewed: August 4, 2026. Check the linked official documentation for syntax specific to the installed software version.