elfes.io.pyscf

Read the supported finite-molecule PySCF checkpoint protocol.

PyscfReader accepts an ordinary PySCF HDF5 checkpoint whose molecular data and requested AO matrices are stored explicitly. A default SCF checkpoint does not necessarily contain the final Fock, overlap, or density matrix, so setting mf.chkfile alone is insufficient for every reader method.

Checkpoint contents

/
├── mol                   PySCF `Mole` serialization
└── scf/
    ├── fock              final Fock matrix
    ├── overlap           AO overlap matrix
    └── dm                final `mf.make_rdm1()` result

/mol is required when constructing PyscfReader and supplies the geometry, Gaussian AO basis, and source AO ordering. The three matrix datasets are independent: read_hamiltonian(), read_overlap(), and read_density_matrix() require only their corresponding dataset in addition to /mol. Existing energies, molecular orbitals, occupations, and other standard checkpoint entries may remain, but ELFES does not use them to reconstruct a missing matrix or infer the SCF method.

A complete checkpoint can be produced after a converged calculation with PySCF-native APIs:

import numpy as np
from pyscf import lib

mf.chkfile = "calculation.chk"
mf.kernel()
if not mf.converged:
    raise RuntimeError("SCF did not converge")

dm = np.asarray(mf.make_rdm1())
fock = np.asarray(mf.get_fock(dm=dm))
overlap = np.asarray(mf.get_ovlp())

lib.chkfile.save_mol(mf.mol, mf.chkfile)
lib.chkfile.dump(mf.chkfile, "scf/fock", fock)
lib.chkfile.dump(mf.chkfile, "scf/overlap", overlap)
lib.chkfile.dump(mf.chkfile, "scf/dm", dm)

Supported calculations

Let n_ao be the number of spatial atomic orbitals. Supported source arrays are:

calculation   fock and density matrix       overlap
RHF / RKS     [n_ao, n_ao]                  [n_ao, n_ao]
UHF / UKS     [2, n_ao, n_ao]               [n_ao, n_ao]
GHF / GKS     [2 * n_ao, 2 * n_ao]          [2 * n_ao, 2 * n_ao]

ROHF and ROKS effective Fock matrices are outside this protocol because their two-dimensional packing cannot be distinguished from restricted data using the stored arrays. Four-component relativistic packing is also unsupported.

The molecule must be finite and use point nuclei with pure spherical Gaussian orbitals. Periodic Cell data, Cartesian GTOs, ghost atoms, ECPs, pseudopotentials, and atom-specific Gaussian functions that differ between atoms of the same atomic number are unsupported.

ELFES results

Geometry is returned in Å and the complete contracted Gaussian basis is converted to ELFES shell and real-spherical-harmonic order. General contractions are expanded into repeated shells. Hamiltonians are converted from Hartree to eV; overlap and density matrices remain dimensionless. Hamiltonians use spinless, 0z, or 0xyz components; density matrices use 0, 0z, or 0xyz; overlap remains spinless. All three are returned as Hermitian-half HermBlockSparseOrbMatrix objects.

PyscfReader(path: StrPath)

read_hamiltonian() -> HermBlockSparseOrbMatrix

read_overlap() -> HermBlockSparseOrbMatrix

read_density_matrix() -> HermBlockSparseOrbMatrix