DF Integral Export#

YAML and Python export inherit exact/DF from the selected reference. Enable density_fit: true on that SCF, CASCI or CASSCF stage to export ordinary MPPT/CIPSIXX integrals from its Coulomb DF approximation. Python adapters capture the completed object’s own with_df. Selected DF uses factorized CVCV storage; the other selected families retain their pair-packed format.

What DF Changes#

The AO-to-MO transformation operates on three-centre DF factors. Pair products then reconstruct the ordinary four-index MO integrals required by MPPT. DIAGPT and HEFFSO continue to read materialized integrals, not DF factors.

This avoids the exact four-centre AO-to-MO transformation and reduces its intermediate storage: MO factors occupy 8 * Q * M * (M+1)/2 bytes for M orbitals and auxiliary rank Q. It can reduce transformation time and memory substantially; the gain depends on dimensions, available RAM and disk access. It is a Coulomb DF approximation, not a numerically identical implementation of exact integrals. Accuracy depends on the auxiliary basis.

All ERI families, full J/K slices, aj/ak, Fock, vacuum energy, frozen-core Hamiltonian/constant, and native v_pair use the same DF approximation. Fock is rebuilt using downstream occupations, not copied from source SCF eigenvalues. Source energies remain orbital-analysis provenance.

The complete reference hcore_ao and scalar constant remain authoritative, including embedding and ECP/GRPP contributions. Requested SO/property providers, orbital-analysis metadata and reference provenance are unchanged. Coulomb DF does not replace the one-electron Hamiltonian or its relativistic operators.

Each stage keeps its own density_fit and auxbasis. Export follows the selected reference, not the last executed stage. Explicit integral_mode is a consistency assertion in both interfaces: a mismatch fails rather than changing the source approximation. For a separate comparison on fixed orbitals, construct ReferenceData with the intended with_df provider (None for exact).

Requirements#

Use a completed or correctly restored reference with finite, real, restricted spatial MOs and the C1 contract. Complex orbitals and unrestricted alpha/beta coefficient pairs are unsupported. Array validation does not certify SCF or CASSCF convergence; check the source calculation separately.
A supplied DF provider must be native CPU molecular pyscf.df.DF, using the full Coulomb operator and real float64 packed AO factors. Periodic, spinor/GPU/custom DF classes, range-separated caches and incompatible Cartesian settings are rejected.
The provider’s molecule must be the identical object as reference.mol, not merely have the same dimensions. Do not mutate its molecule or auxiliary definition after cache generation, or attach unrelated raw factors. Identity and layout checks cannot certify the contents of a manually altered cache.

Enable DF#

These are configuration/API fragments, not standalone calculations. The numerical window below assumes a prepared reference with 117 downstream occupied orbitals and at least 126 retained MOs. It selects one-based orbitals 107-126 as a technical example, not a universal or validated Ce active space.

YAML Fragment#

For an SCF reference, use these sections within an otherwise complete input:

scf:
  density_fit: true
mppt:
  orbitals: scf
  N_select: 20
  N_start: 107
  delete_from: 0

The YAML workflow still owns its configured SCF/CASSCF stages; this fragment is not a no-SCF launch or restart recipe. To export an already completed reference without another SCF/CASSCF calculation, use the public API below.

Public Reference API#

completed_mf must already contain the required completed or correctly restored SCF data, its native with_df, and final Hamiltonian. Adapting and exporting it does not run SCF:

from pathlib import Path
from pyscf2mppt import ExportConfig, dump_reference, reference_from_scf

reference = reference_from_scf(completed_mf)
output = dump_reference(
    reference,
    ExportConfig(
        output_path=Path("df-integrals.h5"),
        integral_mode="df",
        n_select=20,
        n_start=107,
        delete_from=0,
    ),
)

For completed CASSCF data, use reference_from_casscf(completed_mc) instead. See External PySCF References for supplying complete Hamiltonian, scalar and SO/property data. If AO property tensors are supplied, also set write_property_integrals=True; otherwise export rejects them rather than silently ignoring them.

The strict legacy mode values are exact and df, without case conversion or boolean coercion. Omit the option or use null/None to inherit at either boundary. Inputs that previously omitted it now inherit DF when selecting a DF reference. CLI --resume validates saved input and resources; it does not reconfigure an already saved dump. Use a new --output-dir for changed scientific inputs, or an explicit ExportConfig for a separate export from completed data.

Keep All Reference MOs#

All retained MOs with a selected window is not the full-ERI route. With delete_from=0, every reference coefficient column is retained. The selected MOs belong to that full space; they are not extra orbitals added to it.

YAML / API control	Meaning
`N_select` / `n_select`	Positive count selects one contiguous window inside the retained full space. Zero requests the full-ERI route, with much larger materialized outputs.
`N_start` / `n_start`	Exact positive one-based first selected MO; defaults to 1. The window must contain a downstream occupied orbital and fit inside the retained MO space.
`delete_from`	Zero keeps all reference MOs. Do not use a virtual-tail trim merely to make this all-MO target fit.

For example, N_start: 1, N_select: 25 selects MO 1–25. YAML and Python inputs reject nonpositive starts; export rejects a range exceeding the retained MOs.

Keep the reference’s actual occupied count; leave downstream_nocc unset unless a validated downstream convention requires an override. Check the exported n_orb_per_irrep, one-based selected_idx and source-orbital map under /mppt/orbital_analysis. The selected interval must fit within the retained space. Any removal of demonstrated linear dependencies needs explicit evidence and a recorded map, not a silent truncation.

Choose The Auxiliary Source#

YAML borrows the selected calculation’s own with_df without building or resetting it. An exact active-space stage does not fall back to an earlier DF-SCF provider. The external API’s reference_from_casscf retains its explicit-export behavior, preferring the CASSCF provider and then its underlying SCF provider. Resolved atom-label auxiliary mappings preserve distinct labels for the same element.

For CASSCF charge/spin overrides, DF export uses the actual CASSCF AO provider while retaining the original SO provider and source occupation metadata. Resuming before a DF dump reconstructs that context and its configured auxiliary basis from the saved input, without rerunning SCF or CASSCF kernels. Direct helper calls with only CASSCF arrays must supply a provider context rather than fall back to SCF.

For a caller-chosen auxiliary basis, supply a compatible native provider already configured with that basis or atom-label mapping. It may have a cache or be unbuilt. Construct ReferenceData with with_df=resolved_with_df, or use reference.model_copy(update={"with_df": resolved_with_df}) on an existing reference, keeping resolved_with_df.mol is reference.mol.

For explicit API DF export without a provider, export uses PySCF’s normal RHF density_fit() auxiliary choice without running SCF. That automatic choice is not an accuracy guarantee or a substitute for an explicitly chosen basis. There is no separate dump auxbasis setting. Borrowed providers are not serialized with ReferenceData; reattach the correct provider when restoring a reference that needs one.

Ordinary Output#

Selected DF export writes the ordinary one-electron/J/K data and ppaa_pair, papa_pair, pacv_pair, cvcv_factors, plus native selected v_pair. It does not write int2e_full. The full route still writes int2e_full in DIAGPT order and native v_pair in final-MO order. DIAGPT streams CVCV factors and consumes bounded GEMM tiles with the original a0006 equations. Update Python and DIAGPT together for this representation; old packed files remain readable. See Selected Route for the physical HDF5 contract. DF integral payloads remain float64; choosing storage is not a precision switch.

For N_CV=C*V, CVCV payload changes from 8*T(N_CV) to 8*N_CV*Q bytes. It is smaller only when N_CV+1 > 2*Q; tiny test inputs can grow. Factors are written directly from the existing whitened MO store, not obtained by decomposing a materialized CVCV matrix. The exporter still owns full-MO factors temporarily; this change does not eliminate their scratch or compact J/K costs.

The added /mppt/approximation group records integral_mode=df, metric=coulomb, factor_rank, auxbasis, ao_cache_reused and mo_factor_storage (owned_ram or owned_hdf5). The last attribute reports the actual automatic choice; it is not an input flag. Existing exact artifacts and their numerical producer are unchanged.

Matched-DF checks establish assembly/roundoff agreement within the same approximation, not DF-versus-exact errors. Auxiliary-basis accuracy, orbital/model-space suitability, downstream capacity and large-system performance need separate validation; neither accuracy nor speedup is promised.

Memory And Storage#

MO factors use RAM automatically when the modeled export phases fit, otherwise an admitted HDF5 store. This changes storage, not factor rank, precision, MOs or output datasets. Caller caches and other resident arrays still consume memory.

Setting	Role
`molecule.max_memory` / `reference.mol.max_memory`	Total planning hint in decimal PySCF MB, subject to current availability and lower visible limits. Not a hard process-RSS cap.
`mppt.max_mem_bytes` / `ExportConfig.max_mem_bytes`	Omitted or `null`/`None` keeps automatic workspace planning. An explicit positive byte cap limits temporary work, not persistent arrays or final output size.
`PYSCF_TMPDIR` (standalone API)	Scratch location; set before importing the package and provide enough free capacity for owned scratch as well as the final output.

The CLI instead owns scratch under <output-dir>/scratch and places the dump below <output-dir>/data. Choose --output-dir on a filesystem with enough capacity; the standalone API example above writes to its explicit output_path. Both interfaces retain caller-owned caches.

See shared memory units and failure guidance for the common YAML/API cap semantics. DF’s phase model is separate from the exact-export implementation.

There is no public flag to force DF MO factors to disk. force_transform_outcore=True applies to the exact full-route transform, not DF storage. Setting exact_half_block_size with DF is an error. DF adds no user tile or separate memory-budget controls.

Full DF export (N_select: 0 / n_select=0) still materializes large native pair and packed/reorder arrays. A disk flag cannot remove those allocations. Selected export avoids the full ERI table but still has substantial J/K, native selected and final-family storage requirements. Neither automatic storage nor a memory hint guarantees a fit within 50 GB or any other process limit.

Errors And Ownership#

Unsupported providers, incompatible settings and insufficient modeled memory or disk fail explicitly. Native integral and I/O errors propagate; export does not silently switch to exact, reduce the orbital space or resume partial output. Review the reported requirement, available resources and intended route rather than trying an exact-only force flag.

Owned AO/MO scratch is cleaned on success and exceptions; caller-owned caches are never removed or reset. The public exporter publishes atomically only after a complete artifact is written. An existing destination is rejected unless overwrite=True; a failed overwrite preserves it. A successful overwrite replaces the entire file, including any downstream results stored there.

For phase formulas, native workspace estimates, lifetimes, storage algorithms and the existing test coverage map, see DF Export Internals.