Exporting a converged periodic density

The public interface is vibeqc.output.periodic_density. It evaluates the returned density without a new SCF, diagonalization, occupation selection or interpolation of an existing grid. Current portable-state support is for 3D Gaussian AO densities. A successful export certifies its grid representation; it does not certify the electronic state’s stability or physical accuracy.

Save the state before refining the grid

Given the basis, system and converged result from run_periodic_job:

from vibeqc.output.periodic_density import (
    save_periodic_density_state,
    load_periodic_density_state,
)

save_periodic_density_state(
    "density-state.npz", basis, system, result,
    gamma_only=False,
    bvk_mesh=(2, 2, 2),  # actual producer mesh, not the desired grid
    expected_electrons=float(system.n_electrons()),  # subtract ECP core electrons
    producer_identity=producer_record,
)

# This can run in another process. There is no SCF call here.
state = load_periodic_density_state("density-state.npz")
for shape in [(96, 96, 96), (128, 128, 128)]:
    state.export(
        grid_shape=shape,
        path=f"density-{shape[0]}.npz",
        progress=lambda event: print(event, flush=True),
    )

producer_record is a JSON-compatible dictionary identifying the actual SCF source revision, native module checksum, package version, input hashes and matching numerical controls. Preserve the original job receipt externally. The serializer and exporter also record their observed package version and native/Python module checksums, separately from the caller’s producer record. These records identify software; checksums alone are not a scientific verdict.

Request returned lattice densities during the original multi-k run, for example with output_qvf=True on the supported 3D GDF runner. This request does not promise that its initial coarse density grid will pass. Save the returned converged state even if that optional output grid failed. Do not resubmit an already running SCF just to change its output options.

The state contains normalized contracted basis shells and structure, exact returned density blocks and integer cell indices, producer overlap, k points, weights and BvK mesh. Loading uses these saved arrays and shell coefficients; it does not look up a basis by name or reconstruct a density from orbitals. The portable NPZ uses JSON and numeric arrays, without pickle. Member and metadata checksums detect accidental alteration, not malicious replacement of both payload and checksums. It is an export state, not a general restart format.

For a live result, export_periodic_density_grid(basis, system, result, grid_shape=..., gamma_only=..., expected_electrons=..., bvk_mesh=..., path=..., progress=..., producer_identity=...) returns (rho, voxel_vectors). path is optional. A missing or unconverged state is refused. True multi-k exports require returned lattice density and verified mesh metadata; arbitrary per-k matrices are not silently inverse-folded into a fabricated cell domain.

Grid contract and progress

Lattice vectors are columns in bohr. Voxel vectors are rows, equal to lattice.T / shape[:, None]. The 3D primitive-cell origin is zero. The grid samples fractional i / n, excluding the periodic endpoint. Density units are electrons/bohr cubed. Integrate with rho.sum() * abs(det(voxel_vectors)).

The unchanged checks require analytic charge agreement within 5e-5 electrons, grid charge within 0.005 electrons, and successive AO-image grids within 1e-5 electrons in integrated absolute difference and 1e-6 electrons/bohr cubed pointwise. Images increase through at least radius three and at most eight. There is no density rescaling or relaxed tolerance on a coarse grid failure.

Progress callbacks report start, AO-image radius, completed point chunks, image integrals and completion. Counts describe one radius, not a prediction of overall elapsed time. Callbacks run synchronously and may cancel by raising. Each successful grid is atomically published independently. Existing files are never overwritten, including by concurrent writers. If a later grid fails or is interrupted, earlier grids remain available. A state file or progress event is not evidence that any grid passed; use the completed grid artifact.

What an existing QVF can establish

A QVF density volume preserves the sampled grid, not its underlying AO state. An all-k wavefunction section may retain orbitals and occupations for READ initial guesses. Neither guarantees the exact producer-returned lattice blocks, cell domain and overlap required by this interface. The exporter therefore does not accept an ordinary QVF as an exact density state. Inspect its sections and retain a separate export-state artifact when these operands are absent. A missing state cannot be recovered by relabeling a READ guess as converged.

Matching SR/LR GDF calculations across 0.18.x

Release 0.18.4 changes the SR/LR (gdf_method="rsgdf") fitting metric to Cholesky-first. A positive-definite metric keeps every mode if Cholesky succeeds and its minimum eigenvalue exceeds 64 * eps * n_aux * max(abs(eigenvalues)). Otherwise the absolute eigenvalue-cut policy is used. Whitening still uses the eigenbasis. Compensated-cell GDF, MDF and classic FFT builders are unchanged.

This change can affect an SR/LR LiH RHF or diamond PBE calculation using pob-DZVP-rev2. Its impact is determined by each actual auxiliary metric, not just the orbital basis name. STO-3G results do not quantify the effect on pob-DZVP-rev2. The retained modes differ only where the new branch admits modes that the old absolute cut discarded; fallback or an already full-rank old fit retains the old mode set for the same metric. A printed minimum eigenvalue of the AO overlap S(k) does not diagnose the auxiliary Coulomb metric. Do not claim unchanged energy or density without matched evidence. The private fitting leaf’s metric_decomposition argument is not a documented run_periodic_job keyword; do not pass it through an unsupported override.

For every accepted mesh or cutoff increment, keep the producer source/native identity and metric policy consistent. Record geometry and column-vector cell, charge/spin, method/functional, AO and auxiliary shell identities, k mesh/shift and weights, occupation policy, SCF criteria, Ewald and exchange-q0 conventions, SR/LR splitting and real/reciprocal cutoffs, integral screening, overlap and auxiliary thresholds, and XC grids for DFT. Record executed per-transfer metric mode/rank when available; a requested Cholesky policy can execute eigen fallback. Absent diagnostics are an evidence limitation, not permission to infer a rank.

Adopt a released 0.18.x runtime as a separately identified series; do not combine an older baseline with a newer producer into an accepted convergence increment. Existing matched series retain their original identities. Refining the export of one saved density changes neither its SCF producer nor its fitting policy; record exporter identity separately. No patch pin or new SCF campaign is required merely to retain existing evidence.