vibe-qcDocumentation

PBC production: CRYSTAL23, CRYSCOR and periodic coupled cluster¶

Updated 2026-11-03. Development issue #593 is the programme authority; #508 remains the molecular/periodic local-correlation authority. The maintainer has explicitly expanded the earlier ground-state goal to full CRYSTAL23 and CRYSCOR feature parity. This does not reopen completed QC 0.18 or its bounded #557 evidence, assign a release version, or authorize a release.

The order of success criteria is:

Correct, scientifically qualified CRYSTAL23 and CRYSCOR features and production workflows.
Measured leadership in time to solution, memory and parallel scaling on the same accepted problems and accuracy thresholds.
Broader methods on the same infrastructure, with periodic DLPNO-CCSD(T) as the gold-standard single-reference target.

Useful performance work and coupled-cluster groundwork can proceed in parallel with feature development. They do not replace missing numerical acceptance. No general fastest-code claim follows from a kernel benchmark, and DLPNO-CCSD(T) still needs an explicit single-reference applicability and local-approximation error envelope.

Current readiness¶

The CRYSTAL23 inventory has 61 broad rows: five with scoped numerical acceptance, 21 source-tested, seven implemented, 16 unverified and 12 unsupported. These heterogeneous counts are not a completion percentage. Some accepted rows use independent references other than CRYSTAL; a source-tested row can include a correct refusal. The CRYSCOR inventory adds 19 rows and does not claim broad production numerical acceptance. Both inventories retain the evidence and limits of each row. Their broad categories still need version-specific manual subfeature coverage before full parity can close.

Area	Implemented foundation	Remaining production evidence or implementation
HF/DFT/hybrid SCF	Multi-k routes, explicit finite-source controls, physical terminal-state checks and bounded external comparisons	Broader matched spin, cell, basis/ECP, functional and k-mesh matrix; reference convergence and current remeasurement of outstanding failures (#573/#647/#648)
Exchange and k parallelism	Threaded ordered k-pair contractions, deterministic accumulation and bounded completed-worker results	Fourier construction cost, real IBZ execution, certified skew WS, physical-domain SR symmetry and measured whole-SCF scaling (#762/#763-776)
Fock, MANTA and symmetry	Shared operator/source/frame contracts and scoped provider/state integrations	Complete-method source admission and actual reductions; a shared class or provider name is not a scientific certificate (#472/#577/#617)
Geometry and derivatives	Several derivative routes; WS fixed-cell finite-difference optimization and NEB	Broad analytic atomic/cell derivatives, ECP envelopes, stress and qualified bulk relaxation (#578/#579/#770/#772/#773)
Periodic correlation	Gamma/full-mesh real BvK adapters to shared molecular CC; representative-pair MP2; restricted translation CCSD residual evaluator	Optimized periodic locality, physical/reference accuracy, iterative translation CCSD, named triples and cost; IBZ-only and uncertified sources remain refused (#508/#572/#580-592)
Full reference-program features	Some molecular/GAPW property and response building blocks	Periodic response, lattice dynamics/thermodynamics, spinor/noncollinear methods and correlated property packages listed below

Current code and the latest issue evidence take precedence over historical defect titles. In particular, completed-worker exchange memory was bounded in c87cf461; fixed-cell WS FD forwarding is implemented. These do not resolve the remaining Fourier, skew-cell, open-shell or derivative work.

Literature baseline and distinctions¶

Reference	Implementation consequence
Erba et al., CRYSTAL23, and the manual	The feature baseline includes response, lattice dynamics and spinor/noncollinear methods in addition to SCF. Pin the actual reference version and input capability for every claim.
Pisani et al., CRYSCOR, sections II-VI	Closed-shell nonconducting local MP2 uses Wannier occupieds, PAO virtuals, local fitting and coupled amplitudes; density/momentum properties and periodic CIS are separate capabilities.
Usvyat, periodic LMP2-F12, section II; OSV-LMP2	F12 is a specific geminal/projector approximation, not basis extrapolation. Published CIS/F12 implementations are verified; contemporary distributed input support remains to be pinned.
Nejad et al., periodic DLPNO-MP2 I, sections II-VI	Explicit BvK normalization, Wannier/IAO, PAO/OSV/PNO spaces, coupled residuals and charge/dipole treatment must survive translation and factor adapters.
Zhu et al., periodic DLPNO-MP2 II, equations 22-36	Megacell embedding is a different finite construction. Its convergence and adsorption numbers cannot silently qualify a BvK source.
Ye and Berkelbach, periodic local CCSD(T), equations 10-26 and triples SI	This is LNO-CCSD(T), not DLPNO. Local spaces, triples and additive MP2 corrections need their exact algorithm names and independent convergence.
Sundararaman and Arias, WS exchange, equation 12 and appendix A	The finite WS interaction and its quadrature are not universally identical to CRYSTAL direct-exchange truncation. Skew geometry and arbitrary band momenta need their own derivation.

Reuse the canonical literature library and its issue-literature, massive-parallel and tensor-engine collections dated 2026-11-02. A requested 2024-2026 follow-up should supply exact equation/SI anchors, current distribution evidence, corrections and implementation recommendations. Preprints remain labelled as such; a bibliography entry alone is not a validated algorithm or numerical benchmark.

Work packages and dependency order¶

Existing issues retain their owners, jobs and numerical thresholds. Each new package includes a bounded first implementation, primary references, mathematical conventions and acceptance checks. A missing backend does not block a qualified feature on another supported route, but an unsupported required physical feature remains a parity gap.

Stage	Owning issues	Concrete next outcome
Ground-state accuracy	#573/#647/#648, #657/#658, #462/#488	Executable accepted configurations with actual physical/source identity, functional/spin coverage and independently converged references
Exchange and symmetry	#763-776, #577, #762	Certified skew WS, complex k-star transport, same-source screening and arbitrary-k operators; retain explicit refusals until derived
CRYSCOR LMP2/locality	#572/#580/#581/#582/#585/#589/#591/#592	Optimized translation-covariant occupied gauge, PAO/OSV/PNO and dual-basis contracts, SCS and distant-pair convergence, physical 1D/2D/3D qualification
MP2 density/properties	#835	Unrelaxed then relaxed periodic MP2 density, charge conservation and matched correlated observables
Periodic CIS	#836	One source-attested excitation-momentum block, full-space sigma action, local acceleration and reference excitations
Periodic LMP2-F12	#850	Named 3*A geminal/projector correction with a finite-source oracle, then local fitting and basis convergence
Electric response	#837	Static periodic CPHF/CPKS first; higher-order/dynamic and mixed derivatives each have separate acceptance
Harmonic lattice dynamics	#838	Qualify existing GAPW Hessian, shared force constants, q-resolved phonons and harmonic properties
Elasticity/EOS/QHA	#839, #175/#773	Accepted strain/volume points, clamped/relaxed elastic tensors and volume-dependent phonon thermodynamics
Anharmonic vibrations	#840	Explicit PES/modal approximation, VSCF and VCI convergence on bounded periodic examples
Spinor SOC/SOREP	#841	Shared complex spinor state and SOREP integrals, then self-consistent periodic GHF and symmetry
Noncollinear/SCDFT	#842	Variational noncollinear XC and named spin-current functional extensions; collinear limits alone are insufficient
Self-consistent hybrids	#843, #837	Dielectric-dependent outer fixed point with individually accepted SCF/response states
Dispersion/composites	#844	Exact periodic D2/D3/gCP and sol-3c bundles, parameter identity, lattice sums and derivatives
Geometry/symmetry workflows	#846	Reproducible builders, space/layer/rod/helical descriptors and symmetry-distinct solid solutions
Real-space properties	#847, #386/#547	Periodic Hirshfeld-I, topology and local observables with density, ECP and operator-specific limits
Wannier/polarization	#848, #582/#589	Shared occupied-space localization and branch-aware Berry polarization
Reciprocal properties	#849, #176/#776	Accepted-state structure factors, momentum/Compton operators and qualified band transport
Performance	#574/#591/#638/#639/#747-758/#793/#818-826	Same-accuracy total cost, memory and strong/weak scaling, with no hidden full-mesh/factor replication
DLPNO-CCSD(T)	#508/#582/#586/#587/#588/#589/#590/#591	Iterations over the delivered CCSD residual, explicit triple-orbit plan and named triples; canonical recovery before locality and spin extensions

Shared architecture and mathematical contracts¶

Use the unified Fock matrix/state infrastructure, not a new method-specific Fock abstraction. The physical evaluated Fock, density, retained overlap frame, occupations, source and generation form one reference. DIIS, level-shifted or provisional operators cannot replace the accepted physical operator. Correlation additionally requires qualified factors, their metric and auxiliary domains, frozen/active projectors and a same-source receipt. MANTA source substitution is qualified through #581/#629/#635; a mean-field MANTA PASS is not a periodic correlation certificate.

For a complete uniform mesh of N characters, declare the Fourier convention V(R,k) = exp(i k.R)/sqrt(N) and per-cell normalization. Doubles conserve k_i + k_j - k_a - k_b = G. Complex conjugation and phases remain explicit until an admitted real BvK fold. PAOs project out all occupied states, including frozen core: Q = I - C_occ C_occ^dagger S; local metrics and cross-pair overlaps carry virtual-space transport. Unique-pair multiplicity belongs in scalar energies; it does not replace complete contracted occupied sums in coupled residuals.

For a coefficient action C_t = U C_s, density transport is D_t = U D_s U^dagger, with conjugation of the source for an admitted antiunitary operation. Covariant operators use the corresponding inverse or pullback action in the shared symmetry contract. Cartesian AO actions are not necessarily Euclidean-unitary. Geometry symmetry alone does not certify the finite supports, factors, grid, spin state or frozen subspaces.

Parallelize over admitted k targets and source q/pair tiles with #821/#822; use the common tensor engine #793 and resource ledger. Keep global Fermi filling and convergence decisions, deterministic or quantified reductions, bounded in-flight outputs and partition-independent restart identity. Correlation pair residuals are coupled, so distributing independent pair jobs is not a CCSD algorithm. Gamma jobs need additional intra-target parallelism. Share one CPU/thread budget among outer tasks, OpenMP and BLAS.

Evidence required for each accepted row¶

Record method and spin/reference; physical dimension and cell; resolved basis/ECP and charge; actual k/q coordinates, order and weights; J/K and factor source; real/reciprocal physical supports; fitting/XC settings; zero-mode convention; orbital/SCF/correlation thresholds; reference program and native/source identities; raw outputs and measured setup/iteration/ terminal cost and memory. Numerical parity requires a matched calculation, not only input translation or a converged flag.

Keep four error questions separate:

Does the algebra reproduce an independent canonical calculation on the identical finite source?
What error does localization, pair/domain/PNO/TNO truncation introduce relative to that source?
Are the physical support, grid, fit, basis and cell/k limits converged?
Does a genuinely matched external reference agree at the original threshold?

Preserve the existing #591 full-space 2e-9 Ha/cell, residual 1e-11 and energy-change 1e-13 gates, plus any stricter case-specific contracts. The CCSD residual tests under #586 retain atol=rtol=2e-11 and absolute per-cell energy 2e-12. New observables need predeclared, justified thresholds, not a universal borrowed energy tolerance. Match KMP2 and KRCCSD Fock conventions by actual reference version; their defaults differ.

Reuse #743’s independent WS Gamma evidence without advertising acceptance against its unstable original CRYSTAL reference. Keep #35’s ECP scope, #534’s derivative scope and #555’s dense-cell refusal scope unchanged. Neither a molecular limit nor an ECP force preview qualifies general bulk GPW exchange, dense-cell COSX or general ECP gradients.

For cost, include setup, factors, locality preparation, SCF/CC iterations, final confirmation, communication and peak live memory. Distinguish cold and warm scenarios, hardware/ranks/threads, timing uncertainty and every required case. #574 retains its declared same-accuracy time ratio target of at most one versus CRYSTAL23; correlation has its own reference matrix. SKALA uses its actual checkpoint/reference because CRYSTAL is not a same-functional oracle. No scheduling or fleet maintenance is required to implement these contracts.

Completion and development policy¶

Full parity requires implemented and scientifically accepted required features, documented supported configurations and measured production cost. Correct refusals protect users but leave the corresponding required feature open. Chapter/subfeature inventory reconciliation and current CIS/F12 distribution verification remain explicit programme tasks. There is no defensible completion percentage or calendar estimate from issue counts.

Claim bounded files on the existing issue, preserve active owners and reuse valid evidence. Land tested increments promptly with CI skipped. The same chat may implement and assess its smallest decisive vq/reference calculation; no independent reviewer or second chat is mandatory. Source landing and scientific acceptance are reported separately. Full CI and release decisions remain with release qualification, outside this roadmap update.