Skip to content

Scale cell.spin by nkpts in KUHF/KROHF electron-count identity - #3449

Open
shaneraphel wants to merge 1 commit into
pyscf:masterfrom
shaneraphel:kpoint-spin-nkpts
Open

shaneraphel wants to merge 1 commit into
pyscf:masterfrom
shaneraphel:kpoint-spin-nkpts

Conversation

@shaneraphel

@shaneraphel shaneraphel commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #3321.

Identity: when N = cell.tot_electrons(nkpts), Nalpha - Nbeta = cell.spin * nkpts.

tot_electrons(nkpts) already returns the electron count over the Monkhorst–Pack mesh. The nelec property still used unscaled cell.spin (2S per cell). Then Nalpha + Nbeta is odd whenever N is even and spin != 0, so any open-shell k-point calculation with nkpts > 1 raises RuntimeError: Electron number N and spin S are not consistent. get_occ already treats (nalpha, nbeta) as totals across k-points, so the spin must be scaled the same way N is.

Gamma-point pbc/scf/uhf.py and rohf.py correctly use cell.nelectron with unscaled spin (N_k = 1). Those modules are not this rewrite.

Unique change on the three k-point twins (kuhf.py, krohf.py, kuhf_ksymm.py):

nspin = cell.spin * nkpts
nalpha = (ne + nspin) // 2
nbeta = nalpha - nspin

Measured on pyscf 2.14.0, hydrogen in a cubic gth-szv/gth-pade cell (n_paired=5):

case nkpts N spin original nelec licensed Nalpha,Nbeta
H, spin=1, Γ 1 1 1 holds (1, 0) (1, 0)
H, spin=1 2 2 1 raises (2, 0)
H, spin=1 4 4 1 raises (4, 0)
H, spin=1 8 8 1 raises (8, 0)
H, spin=0 2 2 0 holds (1, 1) (1, 1)

Closed PR #3355 documented the workaround and did not change the identity. This this change does not rewrite gamma-point UHF/ROHF.

tot_electrons(nkpts) already returns N over the k-mesh, so
Nalpha - Nbeta must equal cell.spin * nkpts. Gamma-point UHF/ROHF
are unchanged.

Co-authored-by: Cursor <cursoragent@cursor.com>
@chillenb

Copy link
Copy Markdown
Contributor

Related: #3218

@jeanwsr

jeanwsr commented Sep 16, 2026

Copy link
Copy Markdown
Collaborator

Reproducible dest sha256 416f173f92861d304d19998f50eadc71f554115a28fff292cfcac2ea9deb861b (1326 B) against pyscf 40f0dd2. git apply is clean. Zero SGD; n_parameters=0.

Please stop posting those useless info.

@shaneraphel

Copy link
Copy Markdown
Contributor Author

fixed

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

KROHF/KUHF: cell.spin not scaled by number of k-points in electron-count consistency check

3 participants