Restricted k-point SCF ownership¶
The first #821 increment distributes independent dense k solves and density
construction for run_krhf_periodic_gdf(..., kpoint_mpi=True). It supports
three-dimensional, full Gamma-centered tuple meshes with at least two points,
restricted zero-temperature native SR/LR RSGDF Hartree-Fock, and max_iter >= 1. The
existing serial entry remains the default. KS, smearing, Gilat integration,
IBZ-native execution, explicit fitted support, gradients and NOITER are
refused before numerical setup. A tuple is deliberately required: custom
weights and shifted/reduced meshes need separate end-to-end qualification.
Scientific sequence and evaluated state¶
For each k, the existing canonical orthogonalizer defines X^H S X = I in
the retained space. The existing dense operator solver diagonalizes
X^H F X, returning all retained bands and C = X U. No eigenvector
truncation, alternative solver, overlap cutoff or occupation tolerance is
introduced. Rank k % ranks owns that solve, including the initial guess,
PATOM seed, plain-Fock occupation convergence check and terminal solve.
Owners contribute the eigenvalues and coefficients into disjoint global k
slots. All ranks receive the spectrum in canonical k order. Rank zero applies the serial
_occupations_per_k zero-temperature path to determine one global chemical
potential, with its existing roundoff-degenerate Fermi-group convention:
N = sum_k w[k] sum_i occupation[k,i], 0 <= occupation <= 2
D[k] = C[k] diag(occupation[k]) C[k]^H
The occupations already include restricted spin multiplicity. Density construction does not multiply by two or by a k weight. Owners build their own densities; these are replicated for the established GDF J/K builder and SCF accelerators. This increment does not select #822’s fixed-density exchange consumer or change the fit source, exchange approximation or q=0 convention.
At an iteration the damped/accepted D_used selects the physical GDF Fock.
Owner contributions retain the serial energy per cell and the native
retained-space residual, including the native error blocks used by DIIS:
E = E_nuc + sum_k w[k] (Tr(D_used[k] H[k]) + Tr(D_used[k] F_2e[k])/2)
R[k] = X[k]^H F[k] D_used[k] S[k] X[k] - adjoint
R_weighted = sqrt(sum_k w[k] ||R[k]||_F^2)
R_max = max_k ||R[k]||_F
The native residual evaluates the projected product directly and zero-pads the retained error to the AO shape. The MPI path calls that same routine on each owned k; it does not substitute the unprojected AO commutator. Weighted terms are assembled into disjoint slots and accumulated in canonical order. The maximum is diagnostic; it does not replace the weighted stopping rule. Energy change, residual threshold, warmup and global occupation self-consistency checks retain their serial meanings.
A converged or iteration-capped result owns the physical unshifted Fock,
D_used, energy, residual and iteration of one evaluated state. DIIS,
FMIXING and level shift only prepare a subsequent trial. Terminal canonical
orbitals and their global refill belong to that physical Fock. On a capped
return the refill is diagnostic and need not reconstruct the evaluated
mixed density. canonical_refill_is_diagnostic, evaluated_density_epoch,
termination_reason and residual_max make this explicit on opted-in
results. They do not assert stationarity of a capped calculation. Ordinary
output retains the output layer’s rank-zero ownership.
Participation, admission and limits¶
The initializing/main thread enters the existing #820 BoundedSumPhase
contract on the validated world. No worker thread calls MPI. All live ranks,
including empty k owners, participate in every phase, in the same order.
There are no new communicators, tags, progress threads or asynchronous
callbacks. The initialization frame fingerprint includes k order, coordinates,
weights, retained S/X and electron count. Every operation agrees on sequence,
frame and its replicated inputs before payload reduction. A stale mesh,
Fock or density on one participant is a contract refusal. The solver must
return every retained band; insufficient global band capacity is refused.
Each phase prepares a zero-filled float64 vector with disjoint owner slots; complex coefficients, densities and error blocks use real/imaginary pairs. The bounded sum publishes only after completion. Local eigensolver, fill, density or residual exceptions are collective refusals; exception details stay on their originating rank. Empty ranks retain refusal rights. A refused operation returns no result and a completed refusal permits subsequent use. Transport errors retain/poison the phase according to #820 and require job termination. Lost ranks, hung native calls, unmatched collective participation and arbitrary failures in the pre-existing setup/Fock/output stages are not made recoverable by this seam. See runtime protocol.
Small replicated arrays comprise k coordinates, weights, full eigenvalue and occupation lists, chemical potential, electron count, scalar energy/residual terms and phase controls. Large replicated floors remain: all F/S/H/X, coefficients, densities, error blocks, DIIS history and the existing fit/Fock storage. This is one rank per k task with empty excess ranks, not a within-k distributed solver or a memory-scalable complete SCF.
For a packed vector of L float64 elements, #820 retains 144 control bytes
plus 16 L transport bytes per rank (send and result), with one request.
Caller preparation/decoding buffers, input fingerprints, replicated state,
Python objects and MPI internal allocations are additional. Eigenpair payload
length is sum_k (bands_k + 2 AO_k bands_k); density payload is
sum_k 2 AO_k^2; energy/residual payload is 2 Nk + sum_k 2 AO_k^2.
The fill distributes 2 + sum_k bands_k elements (occupations, chemical
potential and entropy); only rank zero computes it. These are logical payload/transport bounds,
not measured wire traffic or RSS. No performance benefit is claimed.
Primary basis and checks¶
Yu et al., Computer Physics Communications 256, 107459 (2020), DOI 10.1016/j.cpc.2020.107459, sections 2.2-2.4, especially equations 13-16, separates independent eigenproblem solves from the coupled global electron constraint. We adopt this separation with one rank per k task and replicated full dense matrices. No ELSI library, block-cyclic redistribution or alternative density-matrix solver is used. Bush et al., Proceedings of the Royal Society A 467, 2112-2131 (2011), DOI 10.1098/rspa.2010.0563, sections 2-4, distinguishes lattice Fock building, k solves, Fermi filling and density reconstruction. Its published scaling curves are not predictions for this implementation. The configured massive-parallel study’s evidence, model, benchmark, software and gap reports inform these stated limits.
The existing tests/test_mpi_kpoint_multirank.py launches real 1/2/3-rank
checks with bounded timeouts. A three-k solve checks a 2:1 split. A two-k weighted spectrum with band overlap
and a Fermi-degenerate variant compare occupations and density to an
independent energy-order enumeration, including uneven and empty owners.
The fixture checks a nonzero retained residual with a discarded AO direction,
stale frames/Focks, insufficient bands, local owner and empty-rank failures,
and successful reuse. Complete #819 H2 serial/MPI SCFs compare densities,
occupations, physical Focks, energy, residual, iteration count and stop reason,
including a capped return. No arbitrary eigenvector-column comparison is used.
Source acceptance, complete vq/reference acceptance and scaling measurements are separate #821 records. The fixture’s older attested native/source hashes are not acceptance of a new implementation. CRYSTAL direct HF is also not the same finite auxiliary approximation; model differences must be reported alongside any comparison. Later increments include spin/smearing, broader mesh admission, within-k pools, distributed Fock/storage, timings and scaling.