Pull Request for Multireference Methods Using Nonorthogonal Orbitals: GBCI, GB-PDFT, and XMS-GB-PDFT. - #200

M. Oh, J. Park, B. Kim, H. Lim, and S. Lee, Orbital-Relaxed Bath Theory for Charge-Transfer Processes in Transition-Metal Complexes, PCCP, 28, 13294 (2026)

Detailed Description

Overview

This PR introduces grouped-bath configuration interaction (GBCI) and
GBCI-based pair-density functional theory methods to PySCF-forge.

The previous pyscf.sfnoci implementation has been renamed and reorganized as
pyscf.gbci. In addition to the namespace change, routines that were previously
embedded in sfnoci.py and direct_sfnoci.py have been separated into reusable
modules, and new GBPDFT, MS-GBPDFT, and XMS-GBPDFT drivers are added.

Main Changes

1. GBCI core (gbci/gbci.py, gbci/direct_gbci.py)

Renames and reorganizes the previous SFNOCI implementation as GBCI:

• renames the user-facing sfnoci.py workflow to gbci.py
• renames direct_sfnoci.py to direct_gbci.py
• keeps the grouped-bath CI solver structure
• supports molecular-orbital, atom-based, and occupation-based grouping
• updates the C contraction library naming from libsfnoci to libgbci

2. Frozen active-space SCF utilities (gbci/fasscf.py)

Separates the frozen active-space SCF routines previously embedded in
sfnoci.py into a standalone reusable module.

This module is used by the GBCI orbital-relaxation workflow and includes:

• frozen active-space SCF updates
• relaxation of the complementary orbital space
• a Newton-based optimization path for the orbital-relaxed bath procedure

3. Density-matrix utilities (gbci/rdm.py)

Separates and extends the density-matrix routines previously embedded in
direct_sfnoci.py.

The previous state-specific spin-separated 1-RDM and 2-RDM routines were
refactored and optimized. This PR also adds transition 1-RDM construction
between GBCI states and exposes reusable intermediates for GBPDFT and
XMS-GBPDFT calculations.

These intermediates are important because GBPDFT avoids explicitly constructing
full 2-RDM/2-CDM objects when evaluating the translated on-top pair density.

4. GBPDFT and on-top pair density (gbci/gbpdft.py, gbci/otpd.py)

Adds GBCI-reference pair-density functional theory:

• translated on-top pair-density functional energies
• direct construction from an SCF object or an existing GBCI object
• on-top pair-density evaluation using GBCI intermediates
• C helper routines for efficient GBPDFT contractions

5. MS-GBPDFT and XMS-GBPDFT (gbci/msgbpdft.py, gbci/xmsgbpdft.py)

Adds multi-state GBPDFT variants:

• effective Hamiltonian construction in the GBCI model space
• GBPDFT diagonal energies
• XMS state-averaged Fock rotation
• final adiabatic state energies and effective Hamiltonian output

6. C library updates (lib/gbci/)

Updates and extends the C helper code:

• renames lib/sfnoci/SFNOCI_contract.c to lib/gbci/gbci_contract.c
• adds OpenMP parallelization to the GBCI contraction routines
• adds lib/gbci/otpd_contract.c for GBPDFT on-top pair-density contractions
• updates CMake configuration for libgbci and libgbpdft

Verification Results

The GBCI test suite was run locally:

env PYTHONPATH=/home/Qchem_OMS/pyscf \
    PYSCF_EXT_PATH=/home/Qchem_OMS/pyscf-forge \
    python pyscf/gbci/test/test_gbci.py

Result:

Ran 4 tests

OK

The tests cover:

• GBCI reference calculations
• GBPDFT calculations
• XMS-GBPDFT calculations
• molecular-orbital, atom-based, and occupation-based grouping modes

Example Usage

from pyscf import gto, scf
from pyscf.gbci import gbpdft

mol = gto.M(
    atom='''
    N  0.000000  0.000000  0.000000
    H  0.000000 -0.937700 -0.381600
    H  0.812100  0.468800 -0.381600
    H -0.812100  0.468800 -0.381600
    ''',
    basis='sto-3g',
)

mf = scf.RHF(mol).run()

mc = gbpdft.GBCI(mf, 'tPBE', ncas=4, nelecas=4)
mc.fcisolver.nroots = 2
e_tot, e_ot, e_gbci, e_cas, ci = mc.kernel()

xms = mc.multi_state((0.5, 0.5), 'xms')
e_xms, e_ot, e_gbci, e_cas, ci, mo_coeff, mo_energy = xms.kernel()

Additional examples are provided in:

• examples/gbci/00-gbci.py
• examples/gbci/01-gbpdft.py
• examples/gbci/02-xmsgbpdft.py

References

• SF-NOCI
  N. J. Mayhall, P. R. Horn, E. J. Sundstrom, and M. Head-Gordon,
  "Spin-flip non-orthogonal configuration interaction: a variational and almost black-box method for describing strongly correlated molecules",
  Phys. Chem. Chem. Phys. 16, 22694 (2014).

• SF-GNOCI (GBCI) / Grouped-Bath Ansatz
  J. Park and S. Lee,
  "Efficient grouped-bath ansatz for spin-flip non-orthogonal configuration interaction in transition-metal charge-transfer complexes",
  J. Chem. Theory Comput. 21, 2988–2997 (2025).

• Orbital-Relaxed Bath Theory (GBPDFT)
  M. Oh, J. Park, B. Kim, H. Lim, and S. Lee,
  "Orbital-relaxed bath theory for charge-transfer processes in transition-metal complexes",
  Phys. Chem. Chem. Phys. 28, 13294–13303 (2026).

• MC-PDFT
  G. Li Manni, R. K. Carlson, S. Luo, D. Ma, J. Olsen, D. G. Truhlar, and L. Gagliardi,
  "Multiconfiguration Pair-Density Functional Theory",
  J. Chem. Theory Comput. 10, 3669–3680 (2014).

• Multi-State PDFT / XMS-PDFT
  J. J. Bao, C. Zhou, Z. Varga, S. Kanchanakungwankul, L. Gagliardi, and D. G. Truhlar,
  "Multi-state pair-density functional theory",
  Faraday Discuss. 224, 348–372 (2020).

Files Changed

• pyscf/sfnoci/sfnoci.py → pyscf/gbci/gbci.py
• pyscf/sfnoci/direct_sfnoci.py → pyscf/gbci/direct_gbci.py
• pyscf/gbci/fasscf.py
• pyscf/gbci/rdm.py
• pyscf/gbci/gbpdft.py
• pyscf/gbci/msgbpdft.py
• pyscf/gbci/xmsgbpdft.py
• pyscf/gbci/otpd.py
• pyscf/gbci/test/test_gbci.py
• examples/gbci/00-gbci.py
• examples/gbci/01-gbpdft.py
• examples/gbci/02-xmsgbpdft.py
• pyscf/lib/sfnoci/SFNOCI_contract.c → pyscf/lib/gbci/gbci_contract.c
• pyscf/lib/gbci/otpd_contract.c
• pyscf/lib/CMakeLists.txt

Testing

The following tests and example scripts were run successfully:

python pyscf/gbci/test/test_gbci.py
python examples/gbci/00-gbci.py
python examples/gbci/01-gbpdft.py
python examples/gbci/02-xmsgbpdft.py

All tests and example scripts completed successfully.