Selected-Route Integral Contract#

In MPPT, the selected route means MPPT_SELECTED=true: determinants produced for a selected-orbital PySCF/CASSCF dump are remapped into full-orbital numbering before DIAGPT. It does not mean a CIPSI-selected subset of individual integrals. DIAGPT always reads scalar and two-electron integrals from the HDF5 file selected by MPPT_HDF5_FILE (default pyscf_dump.h5); file presence and prefix-derived formatted files do not select an integral source or route.

MPPT_SELECTED selects only the HDF5 contract. The accepted true values are 1, T, t, TRUE, True, true, YES, Yes, yes, Y, and y. An unset or other value selects the full route.

Current DIAGPT Inputs#

Selected-mode DIAGPT consumes these root datasets:

int1e_full
aj_full_packed
ak_full_packed
jk_slice_indices_full
j_slice_full
k_slice_full
ppaa_pair
papa_pair
pacv_pair
cvcv_pair

It also requires root metadata including num_irrep, PotNEcor, E_frozen, n_select, selected_idx, n_orb_per_irrep, and the eri_blocks_selected_ncore/nact/nvir/nmo attributes.

The current consumer requires the four pair-packed ERI datasets. Older 4D ppaa_selected, papa_selected, pacv_selected, and cvcv_selected datasets are not accepted by the current DIAGPT loader.

Selected DIAGPT rebuilds Fock quantities from int1e_full and the compact J/K slices. It does not consume fock_full_packed or int2e_full.

Full-Route Contract#

Full mode is a separate contract rather than a fallback to selected blocks. It requires root attributes num_irrep, n_orb_per_irrep, n_occ_per_irrep, and e_vide_full, plus aj_full_packed, ak_full_packed, fock_full_packed, and int2e_full. The model-space orbital count and numbering must agree with that full orbital universe. DIAGPT loads int2e_full into dense packed bijkl; ai() remains the accessor for that storage. Full mode does not load selected pair-packed blocks.

Pair-Packed Blocks#

Let M be the full orbital count, C the core count, A the active/selected count, and V the virtual count. Define T(n) = n(n+1)/2, N_PA = (C+V)A, and N_CV = C*V.

Dataset

Integral family

Stored length

ppaa_pair

`(pq

ab)`, full pair by active pair

papa_pair

triangular nonactive-active pair table

N_PA(N_PA+1)/2

pacv_pair

nonactive-active by core-virtual pairs

N_PA * N_CV

cvcv_pair

triangular core-virtual pair table

N_CV(N_CV+1)/2

These families contain the ERIs required by selected-mode DIAGPT while omitting unrelated full four-index combinations.

Indexing Invariants#

  • The built-in writer stores selected_idx as one-based full-orbital indices.

  • HEFFSO preflight accepts an external raw selected_idx attribute whose range is consistently zero-based or one-based when length and uniqueness are valid. It does not rewrite that stored attribute, but workflow identities hash its normalized canonical one-based values. DIAGPT applies the same normalization before remapping determinants, and the DIAGPT-to-HEFFSO handoff always stores a one-based signed-int64 map.

  • The pair-block reader currently expects selected orbitals to be the contiguous interval immediately after the core orbitals.

  • C + A + V must equal M.

  • Every pair-packed vector length must match the formulas above.

  • YAML orbital labels are human-facing and one-based; cipsixx configuration is normalized to zero-based indices inside its native HDF5 group.

New dumps write /cipsixx@orbital_space as selected or full, and that explicit marker is authoritative. A selected route therefore remains selected when its map happens to contain every full-space orbital. For older external dumps without the marker, workflow preflight infers the route by comparing the model-space orbital count with the full and selected counts. A full-count match takes precedence in that legacy inference only; otherwise a selected-count match chooses selected mode, and an inconsistent count is rejected.

The DIAGPT-to-HEFFSO handoff records this distinction explicitly with the required scalar integer attribute selected_remap. Its value is 1 exactly when the canonical selected_idx dataset is present, and 0 for an unremapped full or legacy handoff. Route selection never relies only on comparing the two orbital counts. The selected map and final remapped determinant vectors are included in the required determinant_content_hash_fnv1a64, so a stale or modified catalog is rejected even when all dimensions still match.

Use mppt.diagpt.integral_space: auto for normal workflow operation. It follows the orbital-space contract stored in HDF5. Explicit full or selected is intended for controlled validation and must match the model-space numbering.

Model-Space Limits#

Current preflight rejects excitation rank above eight, DIAGPT dense model spaces with ncf > 46340, metat > 1000, or metat > ncf. When HEFFSO is enabled, it additionally rejects ncf > 35000 and packed excitation-slot count above 280001. DIAGPT also requires 2*norb + 1 and its packed excitation-slot count to fit signed 32-bit integers. These are hard validation errors; the workflow never truncates the determinant or state space to fit.

Producer Behavior And Limits#

The selected pyscf2mppt writer does not build or store the full-space s4/s8 MO integral table and does not create int2e_full. It obtains the required full-orbital J/K slices from bounded AO J/K batches, transforms the selected subspace integrals, and builds only the four pair-packed block families listed above. The non-selected route continues to produce int2e_full.

The built-in writer emits one canonical copy of each selected-route input. It does not duplicate the selected orbital map, one-electron matrix, compact J/K intermediates, or selected-subspace ERIs under *_selected dataset names. Selected metadata remains in the root attributes described above. Compatible external producers are validated against the canonical inputs rather than by their orchestration path.

This removes the full T(M)(T(M)+1)/2 integral vector from selected-route RAM, scratch, and final HDF5 storage. It does not make the route constant-memory: the J/K slices contain 2*M*T(M) values, and the pair-packed ERI block sizes follow the formulas above. mppt.max_mem_bytes bounds the AO J/K batch and AO-to-MO transformation buffers, while the required output datasets still need destination capacity.