Add FOMO-CASCI and CASCI with DFT embedding extensions

[arshadmehmood118]

Detailed Description

Overview

This PR introduces FOMO-CASCI (Floating Occupation Molecular Orbital CASCI) and DFT-corrected CASCI methods with full nuclear gradient support. These methods are useful for multireference calculations, particularly in photochemistry and excited state dynamics.

New Features

1. FOMO-SCF (mcscf/addons.py)

Implements fractional occupation SCF with:

• Gaussian smearing: n_i = 0.5 * erfc((ε_i - μ) / σ)
• Fermi-Dirac smearing: n_i = 1 / (1 + exp((ε_i - μ) / kT))
• Restricted fractional occupations to active space region
• Configurable temperature parameter

2. DFT-CASCI (mcscf/casci_dft.py)

CASCI with DFT-corrected core energy:

• Core energy: E_core = E_nuc + Tr[D_core * h] + 0.5*Tr[D_core * J] + E_xc[core]
• Active space uses HF-like embedding (J - 0.5*K) to preserve CI coefficients
• Supports LDA, GGA (PBE), and hybrid (B3LYP, PBE0) functionals

3. Nuclear Gradients (grad/casci_dft.py)

• Gradients for FOMO-CASCI, DFT-CASCI and FOMO-CASCI-DFT
• Analytical and numerical methods
• Numerical gradients verified against finite difference to ~10⁻¹⁰ Ha/Bohr precision

Verification Results

All numerical gradients have been verified against numerical differentiation:

Method	Max Difference	Status
FOMO-CASCI (LDA)	2.84×10⁻¹⁰ Ha/Bohr	✓ PASS
FOMO-CASCI-DFT (PBE)	4.97×10⁻¹⁰ Ha/Bohr	✓ PASS

Example Usage

from pyscf import gto, scf, mcscf
from pyscf.mcscf import casci_dft, addons

mol = gto.M(
    atom='''
    O   0.000   0.000   0.000
    H   0.000   0.757   0.587
    H   0.000  -0.757   0.587
    ''',
    basis='cc-pvdz',
    unit='Angstrom',
)

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

# FOMO-SCF
ncas, nelecas = 6, 6
ncore = (mol.nelectron - nelecas) // 2

mf_fomo = addons.fomo_scf(
    mf,
    temperature=0.25,
    method='gaussian',
    restricted=(ncore, ncas)
)
mf_fomo.kernel()

# FOMO-CASCI
mc_fomo = mcscf.CASCI(mf_fomo, ncas, nelecas).kernel()

# FOMO-CASCI-DFT
mc_fomo_dft = casci_dft.CASCI(mf_fomo, ncas, nelecas, xc='PBE')
mc_fomo_dft.kernel()
g_ana = mc_fomo_dft.Gradients(method='analytical').kernel()
print(g_ana)
g_num = mc_fomo_dft.Gradients(method='numerical').kernel()
print(g_num)

References

1. FOMO-CASCI: P. Slavíček and T. J. Martínez, "Ab initio floating occupation molecular orbital-complete active space configuration interaction: An efficient approximation to CASSCF", J. Chem. Phys. 132, 234102 (2010). https://doi.org/10.1063/1.3436501

2. DFT Core Embedding: S. Pijeau and E. G. Hohenstein, J. Chem. Theory Comput. 13, 1130-1146 (2017). https://doi.org/10.1021/acs.jctc.6b00893

Files Added

• pyscf/mcscf/addons.py - Updated with FOMO-SCF implementation
• pyscf/mcscf/casci_dft.py - DFT-CASCI energy
• pyscf/grad/casci_dft.py - DFT-CASCI gradients
• 6 example scripts in examples/mcscf/ and examples/grad/
• Unit tests in mcscf/test/ and grad/test/

Testing

All examples and unit tests pass. I'm happy to address any feedback or make modifications as needed.

Thank you for reviewing!

[jeanwsr]

Please don't copy entire mcscf.addons from pyscf. Since FOMO-SCF is still a kind of SCF, I guess it can be placed in some place like scf/fomoscf.py.

[jeanwsr]

I'm not very sure whether CASCI-DFT or DFT-CASCI are formal names of the method you implemented and cited? If not, I think some more formal name like "DFT-corrected CASCI" can be used in the code, comments, outputs and file names, to avoid confusion with other methods like CAS-DFT or CASCI on DFT orbitals (can be referred as DFT-CASCI in some context).

[arshadmehmood118]

Hi @jeanwsr,
Thank you very much for your quick review.

I've addressed both of your review comments:

Comment 1: Moved FOMO-SCF code from mcscf/addons.py to scf/fomoscf.py
Comment 2: Renamed casci_dft to dft_corrected_casci and updated all terminology to "DFT-corrected CASCI"

Changes include:

• Module reorganization (addons.py removed, fomoscf.py created in scf/)
• Renamed files throughout codebase
• Updated all imports, init.py files, tests, and examples
• Consistent use of "DFT-corrected CASCI" terminology in code, comments, and outputs

All local tests pass. Please let me know if you need any further changes.

Thank you!

[arshadmehmood118]

Thank you for your review and catching this!
I've removed the init.py files from pyscf/grad/, pyscf/mcscf/, and pyscf/scf/ directories.
I understand now that these would overwrite the core pyscf init.py files during installation.