vibe-qc/Documentation

CRYSCOR capability inventory

This inventory belongs to the broader #593 parity programme and #508 local correlation work. It does not reopen the completed QC0.18 release. The machine-readable rows use the same evidence states as the CRYSTAL23 matrix. A component test, a successful SCF or a full-space identity for one finite Hamiltonian does not establish physical periodic accuracy or whole-method parity.

The published CRYSCOR baseline is local MP2 for closed-shell nonconducting systems, its density/property corrections, and the published periodic CIS and local MP2-F12 extensions. The CRYSTAL23 manual explicitly excludes open shells, conductors and very-small-gap semiconductors from its CRYSCOR description. Periodic DLPNO-CCSD(T) is our subsequent extension beyond this baseline, not a feature attributed to CRYSCOR. The sources below do not establish a general analytic MP2 force/stress capability; energy scans and a correlated density do not establish that derivative implementation. C12, C23, p120

C12 documents the CIS implementation at zero exciton wavevector, with finite-wavevector excitation accessed through a supercell. This is a publication-level feature target: this audit has not verified a shipped CRYSTAL23/CRYSCOR command or contemporary executable for it. C23’s general CRYSCOR paragraph establishes MP2, not a complete current CIS interface. Keep that distinction in any reference-calculation request. The 2015 OSV-LMP2 paper explicitly identifies the earlier local MP2-F12 implementation with CRYSCOR; F13 supplies its method definition. Current shipping/version support for that extension also needs executable evidence.

Primary references and reading anchors

The catalogue and PDFs in the configured canonical literature library are the local literature source. The identifiers below also give portable references for developers without that checkout.

Key	Source	Relevant sections
C12	Pisani et al., CRYSCOR: a program for the post-Hartree-Fock treatment of periodic systems, PCCP 14, 7615-7628 (2012), 10.1039/c2cp23927b	II: WF/PAO local MP2; III: surfaces and asymptotic corrections; IV: parallelism and applications; V: MP2 density and momentum properties; VI: periodic CIS.
C09	CRYSCOR09 User’s Manual, institutional copy	5: integrals/equations; 6: dual basis; 7 and 11.3: MP2 density; 10.1.10: spin-component scaling; 10.1.13: pair-tail extrapolation. SCS is also explicit in Maschio’s official features lecture.
C23	CRYSTAL23 User’s Manual, official PDF	p120: CRYSCOR reference/dimensionality boundary; p349: PMP2 property consumers.
L08	Pisani et al., periodic local MP2, 10.1002/jcc.20975	WF/PAO local equations and infinite periodic domains.
L15	Usvyat et al., periodic local MP2 with orbital-specific virtuals, 10.1063/1.4921301	OSV compression of periodic local correlation.
F13	Usvyat, Linear-scaling explicitly correlated treatment of solids: Periodic local MP2-F12 method, 10.1063/1.4829898, institutional PDF	Local 3*A fixed-amplitude F12 ansatz, local strong-orthogonality spaces, density fitting, translation/site-group symmetry and LiH convergence.
D25-I	Nejad et al., DLPNO-MP2 for periodic systems. I, 10.1063/5.0290816	II-VI: finite BvK Hamiltonian, Wannier/PAO/OSV/PNO construction, coupled residual, charge/dipole-corrected periodic DF.
D25-II	Zhu et al., DLPNO-MP2 for periodic systems. II, 10.1063/5.0290819	Distinct megacell embedding; translation reuse of integrals, pair spaces and residuals.
CC24	Ye and Berkelbach, Periodic Local Coupled-Cluster Theory for Insulators and Metals, 10.1021/acs.jctc.4c00936	LNO-CCSD(T), not DLPNO: local densities/active spaces, CCSD/(T) contributions and separately named MP2 composite correction.

The C09 institutional server rejected a direct PDF fetch during the 2026-11-03 audit; its indexed table of contents and the official lecture verify the SCS/dual-basis entries. The locally held C12 and C23 PDFs supplied the baseline feature/property audit. New version-specific claims require the corresponding manual or executable evidence.

Capability rows

Updated 2026-11-03; 19 rows.

State	Rows	Meaning
numerically-accepted	0	A matched reference comparison passed on a recorded source/native runtime within a stated tolerance, for the bounded scope named in the evidence; not whole-method parity.
source-tested	5	Implemented and covered by focused repository tests of source functionality, refusals or internal identities; no matched external numerical reference.
implemented	0	A public route exists and runs; no focused repository test or reference comparison is claimed for this row.
unverified	5	Implemented, but an open numerical defect, a failed or contradictory comparison, or a missing reference comparison is on record.
unsupported	9	Absent or explicitly refused; a precise refusal is an acceptable release boundary, not a parity claim.

Reference and dimensionality

Row	CRYSCOR capability	vibe-qc route	State	Evidence	Remaining gap	Issues
closed-shell-reference	Closed-shell insulating Hartree-Fock reference; open shells, conductors and very small gaps excluded (C23 p120)	GDF Gamma/full-mesh source adapters retain physical Fock, integer occupations and same-source fit; separate chi/CCM sources declare their finite Hamiltonian	source-tested	tests/test_periodic_dlpno_gamma.py checks source identity, changed-Fock refusal and occupied-space preservation; tests/test_chi_translation_mp2.py checks finite-source refusals and translation identities	Match a converged CRYSTAL/CRYSCOR HF reference including orbital spectrum, exchange zero mode, supports, auxiliary metric, basis and frozen core; SCF termination alone is insufficient	#508, #572, #573, #591
lmp2-3d	3D periodic local MP2 energy per cell (C12 sections II and IV)	Finite-source translation-local MP2 and GDF selected-pair adapters; public periodic DLPNO-CCSD(T) route remains a separate preview	unverified	tests/test_chi_translation_mp2.py has raw full-space independent-canonical checks; tests/test_periodic_dlpno_gamma.py compares GDF translation MP2 with dense/character forms; no matched CRYSCOR production row is recorded here	Demonstrate a matched insulating bulk MP2 row and independent convergence of HF mesh, correlation range, orbital basis, fitting basis and local thresholds	#508, #582, #591, #593
lmp2-2d	Genuinely 2D periodic local MP2 for surfaces (C12 sections II and III)	The public same-source periodic DLPNO front door refuses dim<3; finite megacell/CCM research workflows are distinct Hamiltonians	unsupported	python/vibeqc/periodic_dlpno.py and tests/test_periodic_dlpno_gamma.py enforce the dimension boundary	Provide and qualify a 2D same-source Coulomb/reference/factor contract; a 3D vacuum slab or finite cluster is not automatically the same 2D operator	#508, #572, #591, #721
lmp2-1d	1D periodic local MP2 for chains and nanoscrolls (C12 section IV A; C23 p120)	Finite-chain megacell calculations exist; the public same-source periodic DLPNO front door refuses dim<3	unsupported	tests/test_periodic_megacell_mp2.py checks molecular-limit and finite-chain bookkeeping; these do not certify the infinite 1D periodic Hamiltonian	Qualify an explicit 1D periodic source and controlled chain/domain limits with the same reference and correlation operator	#508, #572, #591

Local spaces and integrals

Row	CRYSCOR capability	vibe-qc route	State	Evidence	Remaining gap	Issues
wannier-localization	Localized, symmetry-adapted occupied Wannier functions spanning the HF occupied manifold (C12 section II)	Pipek-Mezey localization in folded GDF preview; compact cyclic occupied selection and optional cosine seeds in translation-local sources	source-tested	tests/test_periodic_dlpno_gamma.py checks occupied-span preservation; tests/test_chi_translation_mp2.py checks cyclic selection, phase covariance and seed/full-space limits	Occupied-projector identities and seeds do not prove localization quality; add production periodic Wannier optimization, locality convergence and symmetry transport	#582, #584, #589, #848
pao-pair-domains	Projected atomic orbitals, orbital domains and coupled local pair amplitudes (C12 section II; C09 section 11.1)	Periodic PAO projectors, domain/PNO selection and translation-local MP2 coupled residual with cross-pair transport	source-tested	tests/test_periodic_pao.py checks orthogonality, completeness and Fock spectrum; tests/test_chi_translation_mp2.py separates domain/PNO experiments and raw canonical limits	Measure domain and pair-screening error independently of PNO, fit and finite-size error on real crystals; PNO truncation is an additional approximation, not a CRYSCOR acceptance shortcut	#580, #582, #585, #591
osv-local-mp2	Published OSV local MP2 with diffuse-PAO augmentation for long-range dispersion (L15 sections II A and II B)	Translation-local domains use explicit spatial/population criteria; no qualified periodic OSV-MP2 plus diffuse-PAO route	unsupported	python/vibeqc/dlpno/translation_driver.py and translation_domains.py explicitly distinguish their current selection from OSV domains	Implement diagonal-pair OSV selection and the long-range virtual-space augmentation, or demonstrate equivalent controlled accuracy with the admitted PNO route; compare short- and long-range pair energies separately	#582, #591, #593
local-density-fitting	Local density fitting and direct/reciprocal integral techniques for WF-PAO products (C12 sections I and II)	Retained GDF factors, bounded factor providers and MANTA source interfaces feed the shared local-correlation consumers	source-tested	tests/test_periodic_dlpno_gamma.py checks SCF-fit identity; tests/test_chi_translation_mp2.py checks streamed/dense equality, metric null modes and allocation limits; #581/#592 track producer integration/storage	Certify each admitted producer’s kernel, rank, lattice supports and source epoch; a unified Fock receipt alone does not certify correlation factors or physical bulk convergence	#581, #592, #591
distant-pair-tail	Multipolar distant-pair integrals and asymptotic dispersion-tail extrapolation (C12 sections II and III B; C09 section 10.1.13)	Finite domain and PNO/weak-pair corrections exist in local-correlation workflows; no CRYSCOR-matched infinite pair-tail result is established	unverified	Translation-local tests report raw energy separately from semicanonical corrections; no accepted bulk/slab dispersion-tail comparison is recorded here	Implement or certify the named multipole/tail model with a range ladder and dimensionality-aware asymptote; discarded-pair and PNO corrections do not substitute for a physical long-range tail	#582, #591, #721
dual-basis	Dual basis: enlarge correlation virtual space without repeating HF in the enlarged basis (C09 section 6; C12 section IV)	Current retained-fit source ties orbital/auxiliary basis identities to its HF reference; no admitted CRYSCOR-equivalent dual-basis local-MP2 route	unsupported	docs/design_dlpno_correlation_source.md specifies basis/projector/source identity; independent basis substitution is not permitted by that contract	Define the occupied embedding, enlarged virtual projector and Fock/factor construction; include the dual-basis singles contribution where the theory requires it and label the approximation explicitly	#508, #572, #582
space-group-pairs	Translation and point-group reduction of local occupied pairs (C12 sections II and III A)	Unique-home-cell translation-local algebra exists; the folded public DLPNO route refuses symmetry-reduced input	source-tested	tests/test_chi_translation_mp2.py checks translation covariance and canonical equality; tests/test_periodic_dlpno_gamma.py checks IBZ refusal	Use shared certified symmetry unfolding and pair transport, including antiunitary phases and correct multiplicities; geometric cell symmetry alone cannot authorize an electronic reduction	#584, #589, #591

Energy variants and applications

Row	CRYSCOR capability	vibe-qc route	State	Evidence	Remaining gap	Issues
lmp2-f12	Published periodic local MP2-F12 with the 3*A fixed-amplitude ansatz (F13; L15 introduction); current shipped interface not verified	F12 orbital/CABS basis files exist; no admitted periodic local MP2-F12 energy implementation	unsupported	Basis availability is not an F12 method; no periodic explicitly correlated result is recorded in the correlation-source evidence	Implement the named geminal ansatz, strong-orthogonality/projector domains, auxiliary/CABS spaces and local F12 integrals; qualify LiH basis/domain convergence independently of ordinary LMP2	#850, #508, #593
scs-lmp2	Spin-component-scaled MP2 correlation energy (C09 section 10.1.10; Maschio’s official CRYSCOR features lecture)	Same/opposite-spin energy components and scaling exist in molecular/CCM UMP2 consumers; no matched closed-shell periodic CRYSCOR SCS row	unverified	python/vibeqc/dlpno/ump2.py and python/vibeqc/periodic/ccm/dlpno_ump2.py expose scaling; this does not establish SCS coverage for every periodic source	Expose and compare SS/OS components and coefficients on an admitted closed-shell periodic route; distinguish spin components from CRYSCOR’s printed singlet/triplet pair decomposition	#508, #582, #591
cohesive-adsorption-energy	Cohesive/adsorption energies with BSSE control and surface/long-range extrapolation (C12 sections III and IV)	Finite megacell correlation and thermodynamic-limit helpers; CO/MgO DLPNO-MP2 literature benchmark tracked separately	unverified	tests/test_periodic_megacell_mp2.py checks finite-chain behavior and extrapolation functionality; #721 retains a published matched CO/MgO target, not a measured vibe-qc pass	Record ghost/fragment domains, counterpoise, basis/cell limits and separate raw/corrected energies; converge lateral size and slab thickness independently for adsorption	#591, #721, #593

Correlated density and properties

Row	CRYSCOR capability	vibe-qc route	State	Evidence	Remaining gap	Issues
relaxed-mp2-density	Lagrangian MP2 correction to the HF one-particle density matrix (C12 section V; C09 sections 7 and 11.3)	No qualified periodic relaxed local-MP2 density consumer is documented; source density factors and HF densities are different objects	unsupported	The periodic local-correlation guide documents energies and source provenance, not a correlated periodic response-density result	Derive amplitude/orbital response consistently with domains, fitting and symmetry; verify trace, Hermiticity, translation covariance and one-body finite-field derivatives before property use	#835, #508, #593
correlated-real-space-properties	MP2-corrected charge density, Mulliken populations and X-ray structure factors through PMP2 (C23 p349)	Periodic SCF analysis exists; no accepted adapter from a relaxed periodic MP2 density to these properties	unsupported	An HF/DFT property implementation is not evidence for the PMP2 correction; no scoped correlated comparison is recorded here	After the density contract passes, reuse existing property consumers and compare density integrals, populations and matched reciprocal structure factors	#835, #847, #508, #593
correlated-momentum-properties	MP2 momentum density, directional Compton profiles and autocorrelation (C12 section V; C23 p349)	No qualified periodic correlated momentum/Compton consumer	unsupported	No matched periodic MP2 momentum-density or Compton result is recorded in the local-correlation evidence	Fourier-transform the admitted AO density with explicit normalization, units and directional integration; validate electron-number sum rules and matched CRYSCOR profiles	#835, #849, #508, #593

Excited states

Row	CRYSCOR capability	vibe-qc route	State	Evidence	Remaining gap	Issues
periodic-cis-exciton	Published periodic CIS excitonic gaps at q_exc=Gamma, finite-q through supercells (C12 section VI); current shipped interface not verified	Molecular excited-state machinery is not a certified periodic CIS response with lattice Coulomb/exchange	unsupported	No matched periodic CRYSCOR CIS gap with the same HF reference and basis is recorded here	Implement a matrix-free periodic singles response on the same source, with momentum/phase and Coulomb zero-mode conventions; validate finite-cell canonical and matched periodic limits	#836, #508, #593

Performance and parallelism

Row	CRYSCOR capability	vibe-qc route	State	Evidence	Remaining gap	Issues
parallel-time-to-solution	Parallel local MP2 integral/residual work and symmetry savings (C12 section IV and Figure 6)	Bounded translation-local work, compiled contractions and shared tensor-engine integration; measured whole-method production scaling remains open	unverified	tests/test_chi_translation_mp2.py checks bounded allocation and streamed identities; docs/user_guide/periodic_local_correlation.md reports small loaded-laptop preview timings, not a CRYSCOR performance comparison	Measure identical-accuracy total wall time, peak memory and setup/SCF/source/localization/solve costs; distribute k/transfer/pair work under one resource budget and retain deterministic reductions	#190, #591, #592, #593

Dependencies for implementation

1. Bind each reference to the shared physical Fock, overlap/rank projector, occupations, frozen partition, ordered full k mesh, geometry/basis/ECP, supports and exchange zero mode (#572/#580). Bind correlation factors to the same kernel, metric/rank and source epoch (#581/#592). MANTA must supply the admitted factor producer; a Fock action is not itself a four-index correlation certificate. Preserve explicit refusals until the matching contract is available.

2. Build translational occupied Wannier functions and virtual PAOs before calibrating domains (#582). D25-I Eqs9-16 define the transforms and pair multiplicities, Eqs22-23 the Bloch-IAO Pipek-Mezey objective, and Eqs26-28 the PAO projector. Keep occupied-space preservation, achieved locality and electronic symmetry as separate checks. Shared symmetry provides certified full-mesh unfolding and pair transport (#589).

3. Separate OSV screening, pair selection, PNO truncation and residual convergence. D25-I Eqs30-41 define the local spaces and corrections; Eqs42-44 require occupied-Fock couplings and cross-pair overlaps in the unique-home-cell residual. An independent-pair denominator formula is not the coupled noncanonical MP2 method. Use the existing shared local solvers; retain raw energies and every correction separately. L15 section II B shows why diagonal-pair OSVs alone miss long-range dispersion and augments them with diffuse PAOs. Validate long-range pair behavior explicitly rather than treating compactness or an OSV label as an accuracy guarantee. The current translation-domain selector is explicitly not an implementation of those OSV domains.

4. Treat periodic integral construction and finite-size control as part of the scientific method. D25-I Eqs45-65 define fitting, charge projection and common-origin dipole terms. D25-II Eqs22-36 define a different megacell construction. Neither source’s exactness nor asymptotic cost transfers automatically to the other. Independently converge the HF spectrum, correlation volume, local spaces, fit and orbital basis.

5. Extend the admitted amplitudes to the CRYSCOR Lagrangian one-particle density (#835) and shared real/reciprocal property consumers (#847/#849). Validate the response density with particle number, Hermiticity, translation covariance and one-body finite fields. Periodic CIS (#836) requires its own momentum-resolved singles operator; reusing a molecular eigensolver alone does not supply that operator. F13’s local MP2-F12 (#850) requires the explicitly correlated ansatz, its auxiliary/projector spaces and new integral contractions; having F12 basis files or extrapolating ordinary MP2 does not implement it.

6. Extend the same source and shared compiled residual machinery to unique translation-local CCSD (#586), then a precisely named triples method (#587), independent-spin sources (#588/#590) and qualified production thresholds/cost (#591). CC24 Eqs10,12,14 define the alternative LNO local Hamiltonian and CCSD/(T) energies; Eq17 is a separate MP2 composite correction; Eqs20-26 define local-density selection and DF. Its LNO partition must not be relabelled as pair-PNO DLPNO.

Acceptance and performance boundary

Existing periodic DLPNO evidence includes small H2 GDF/BvK full-domain comparisons with PySCF KRCCSD(T), with keep_exxdiv=True, and NormalPNO errors of 23 and 4 microhartree per cell on two meshes. Preserve those reference identities and tolerances. They do not establish CRYSCOR local-MP2/property parity or production crystal thresholds. The current public folded route refuses BIPOLE, reduced/shifted k-point objects, smearing and lower-dimensional cells; finite-source translation-local work has its own admission contract.

The folded preview uses the shared molecular iterative CCSD engine. Its closed-shell default triples_mode="t1" is a canonical (T) contraction on rotated local amplitudes; "local" selects its local (T0) kernel and "exact" the exact mode. The open-shell preview has its separately named spin-orbital modes. These are inherited supercell algorithms, not evidence that #586’s translation-native CCSD iteration or #587’s bounded triples is production complete. Solver convergence, full-space equivalence, finite local approximation error and physical finite-size convergence must each be reported. A converged CCSD result does not establish the correctness or cost of every triples option.

For each new numerical claim record source/native commit, method/reference, cell/dimension, basis/ECP and auxiliary basis, ordered k coordinates/weights, J/K and correlation source, physical supports, zero-mode convention, frozen partition, all local/fitting/solver thresholds, raw and corrected energy, reference identity, tolerance and measured cost. Preserve #591’s original raw full-space exactness/residual tolerances. Compare CRYSCOR/CRYSTAL or another justified independent calculation only when the physical reference and mathematical quantity match; identify the limitation otherwise.

Performance work follows numerical equivalence at the stated accuracy. Report end-to-end time and peak memory alongside source setup, SCF, localization/domains, amplitude iterations and triples. Parallel k/transfer and pair scheduling must respect one shared resource budget and avoid nested oversubscription. An O(1) or linear scaling statement from a paper depends on its translation/domain assumptions; no such whole-method performance claim is accepted for vibe-qc by this inventory.

Regenerate or check the table without importing the native package:

python scripts/crystal23_capability_matrix.py --target cryscor --write
python scripts/crystal23_capability_matrix.py --target cryscor --check