Quantum Chemistry

The pyqed.qchem package provides native quantum chemistry tools for molecular integrals, Hartree-Fock references, post-HF correlation methods, multiconfigurational methods, and excited-state calculations.

This page is a static overview. It avoids importing pyqed.qchem during the documentation build because some optional compiled backends, such as libxc and integral libraries, may not be available on Read the Docs.

Core Workflow

A typical native calculation follows this structure:

from pyqed.qchem import Molecule

mol = Molecule(
    atom="H 0 0 0; H 0 0 0.74",
    unit="angstrom",
    basis="sto-3g",
)
mol.build(driver="builtin", eri="auto")

mf = mol.RHF().run()
print(mf.e_tot)

Main Components

  • pyqed.qchem.mol defines the molecular object, basis setup, and integral construction paths.

  • pyqed.qchem.hf contains restricted and unrestricted Hartree-Fock drivers.

  • pyqed.qchem.hf.analysis contains orbital, charge, and bond-order analysis helpers.

  • pyqed.qchem.ci contains CI methods, including CISD and FCI utilities.

  • pyqed.qchem.mcscf contains CASCI, CASSCF, state-averaged CASSCF, and second-order orbital optimization paths.

  • pyqed.qchem.mp contains MP2 and orbital-optimized MP2 utilities.

  • pyqed.qchem.tddft contains linear-response TDDFT functionality.

  • pyqed.qchem.dft contains native DFT and grid functionality.

  • pyqed.qchem.semiempirical contains semiempirical method interfaces, including the in-progress OM2/MRCI API.

  • pyqed.qchem.dmrg contains DMRG and spin-adapted/non-Abelian development paths.

  • pyqed.gw contains dense molecular GW, eigenvalue-self-consistent GW, qsGW, and BSE reference implementations.

Integral Backends

The molecular build step can use different integral representations depending on the calculation:

  • driver="builtin" uses the native integral path.

  • eri="auto" uses compact eight-fold exact storage for small systems and prefers native RI factors for larger systems when an auxiliary basis is available.

  • eri="dense", aosym="s1" stores the four-index electron repulsion tensor explicitly.

  • eri="dense", aosym="s4" stores the tensor in unique AO-pair form.

  • eri="dense", aosym="s8" stores only unique AO-pair-pair values, exploiting the full eight-fold ERI permutation symmetry for memory.

  • eri="direct" avoids dense AO ERI construction and uses compact s8 storage for cartesian J/K builds.

  • eri="factors" stores a Cholesky/factorized representation when available.

  • eri="dense+factors" keeps both representations for algorithms that need dense tensors and factorized contractions.

  • eri="ri" builds native density-fitting factors from bundled auxiliary basis sets, without using PySCF. The default ri_purpose="jk" prefers JKFIT sets for SCF when available; use options={"ri_purpose": "ri"} to prefer RIFIT sets for correlation-style fitting.

  • eri="dense+ri" keeps the dense tensor and the native RI factors.

Auxiliary bases can be selected explicitly:

mol.build(
    driver="builtin",
    eri="ri",
    auxbasis="cc-pvdz-rifit",
)

The Cholesky and RI paths are useful for larger active-space and CASSCF workflows because they avoid materializing dense transformed electron-repulsion tensors when the solver can contract directly with factors. Cholesky factors are an exact low-rank decomposition of the AO ERI tensor up to the selected tolerance; RI factors are an auxiliary-basis approximation. Native RI builds three-center tensors in packed AO-pair form, uses full factor storage by default for the current faster RHF contraction path, supports ri_storage="packed" for memory-sensitive runs, applies a Cholesky-first metric solve with an eigenvalue fallback, and supports optional three-center screening via ri_screen_tol.

Multiconfigurational Methods

PyQED includes native CASCI/CASSCF implementations, including factorized integral support and second-order orbital optimization paths. See the dedicated guide for examples: