SRHF

A from-scratch, symmetry-adapted Restricted Hartree-Fock (RHF) implementation that exploits molecular point-group symmetry — including genuinely degenerate, non-Abelian irreps (e.g. C3v's E, Td's T1/T2) — built on Psi4 for integrals/basis sets and MolSym for point-group detection and symmetry-adapted linear combinations (SALCs).

What's here

• SRHF (srhf/rhf.py) — first-order (DIIS) symmetry-adapted RHF.
• SO_RHF (srhf/sorhf.py) — second-order (Newton-Raphson/SOSCF) RHF, with a dense cross-irrep/cross-partner Hessian for real (non-C1) point-group symmetry. See docs/soscf_degeneracy.md for how second-order convergence interacts with degenerate-irrep exploitation.
• Degeneracy exploitation (options.exploit_degen) — compresses a degenerate irrep's SALCs down to one representative partner wherever the physics allows it, generalized into a reusable tensor-contraction abstraction (srhf/degen_tensor.py: DegenTensor/DegenIntegralFactory), documented in docs/degen_tensor.md — including a checklist for extending it to new post-HF methods.
• MP2 (srhf/mp2.py) — conventional and exploit_degen-aware correlation energy.
• Wavefunction stability analysis — SO_RHF.rhf_stability_analysis() and uhf_stability_analysis() diagonalize the real singlet (RHF→RHF) and triplet (RHF→UHF) TDHF/RPA stability matrices over the full, un-pooled occupied × virtual space (every irrep combination, every degenerate partner independent), validated against Psi4's own stability_analysis output.
• Mode following — SO_RHF.rhf_mode_follow() rotates the orbitals along an unstable mode and reconverges in a fresh, lower-symmetry job, the standard technique for escaping a symmetric saddle-point RHF solution.

Requirements

• Python 3.10 or 3.12 — the versions CI actually tests (see .github/workflows/workflow.yml); pyproject.toml declares a floor of 3.9, but that floor itself is untested, not a verified guarantee.
• Psi4 (conda-only — see environment.yml)
• MolSym
• NumPy, SciPy, QCElemental

Installation

conda env create -f environment.yml
conda activate srhf

This creates a conda environment with Psi4 and installs SRHF itself (and its Python dependencies) in editable mode.

Usage

from srhf.sorhf import SO_RHF
from srhf.options import Options

water = """
noreorient
0 1
units bohr
O 0.000000000000  0.000000000000 -0.143225816552
H 0.000000000000  1.638036840407  1.136548822547
H 0.000000000000 -1.638036840407  1.136548822547
"""

opts = Options(guess="sad", second_order=True, exploit_degen=True)
job = SO_RHF(water, "cc-pvdz", opts)
job.run()

result = job.rhf_stability_analysis()
job.report_rhf_stability(result)

Testing

pytest test/

Documentation

• docs/soscf_degeneracy.md — how second-order SCF convergence works with (and without) degenerate-irrep exploitation.
• docs/degen_tensor.md — the DegenTensor abstraction, what it's for, and a checklist for building new post-HF methods on top of it.

License

MIT