vibe-qcDocumentation

Molecular MPI residual and owner iteration

The experimental Python entry point is vibeqc.dlpno.mpi_residual.evaluate(problem, owners, local, epoch=..., max_bytes=...). It computes one raw, closed-shell PNO-space R1/R2 evaluation and reports the owned energy contribution in its ledger. The owner iteration below adds Jacobi updates and global diagnostics. Use prepare(captured_rhf_source, LocalCCSDOptions(residual_domain="pno", ...)) to obtain the serial factors and ordered pair spaces before the CC iteration. This increment admits the native evaluated molecular RHF/DF adapter. It does not change the molecular driver default or support periodic sources.

Every rank enters on the MPI initializing thread with the same static problem, ordered owner vector and positive amplitude epoch. Number pairs in the preparation’s insertion order. Supply a local dictionary of Amplitude(problem.fingerprint(), epoch, owner, key, values) records: (i,j) for retained doubles with i <= j and (i,) for singles on the diagonal owner. Use real C-contiguous FP64 arrays. Keep all provider buffers unchanged for the duration of the call. A result is a dictionary with just the owned keys and a separate local transport ledger.

For target ij the complete native kernel reads retained kl with both occupied indices in its coupling set. Only remote blocks in that neighborhood are sent, one unpadded block per ticket. The owner builds the serial intermediates on this subgraph and calls the same doubles kernel and, for ii, singles kernel as the serial solver. The native ordered-pair transpose and rectangular PNO overlap projections stay inside those kernels. Only the verification harness reads the full amplitudes and reference residual. See Riplinger et al., section II, and Schwilk et al., section 8.1 for sparse domains and scheduling of coupled pairs; the latter paper uses different equations.

The cap covers the logical transport controls, schedule metadata, active payload slot, owned residuals, native amplitude import allowance, and retained ghost allocations and leases. The peak is this ledger’s high-water mark in bytes. It excludes the static provider, caller-owned input amplitudes, Eigen contraction workspace, Python object overhead, MPI internals and RSS. The ledger reports both remote numerical payload and total packet bytes, including the frame/placement digest, epoch, target/source keys, generation and checksum. Neither counter includes MPI control traffic or receipts. A receipt retires the packet; its private ghost remains leased through the target contraction. A recoverable refusal discards all private output. As in the MPI protocol, a fatal MPI error requires job termination.

For verification, run tests/fixtures/molecular_mpi_residual.py pin FILE.npz in serial, then mpiexec -n 2 python tests/fixtures/molecular_mpi_residual.py verify FILE.npz with one thread per rank and MPI4PY_RC_THREAD_LEVEL=funneled. The pin holds the evaluated source and frozen occupied, factors, maps, ordered PNOs and overlaps, fixed amplitudes and raw serial blocks. Three ranks exercise an empty participant. The declared absolute component and difference tolerance is 2e-11 Ha. ORCA converged energies do not provide these arbitrary-amplitude, identical-gauge residual blocks.

Distributed DIIS history requires separate work. Molecular (T0) is described below. The owner iteration preserves the serial initial guess, equations and fixed domains. A solver-wide memory census and complete-method timing remain necessary before claiming capacity or performance.

Owner iteration at fixed domains

initialize(problem, owners, max_bytes=...) prepares semicanonical MP2 T2 = K / (Fii + Fjj - ea - eb) and zero diagonal-frame singles at epoch 1. advance(problem, owners, state, max_bytes=...) applies one undamped Jacobi update. solve(problem, owners, max_bytes=..., max_iter=100, conv_tol_energy=1e-9, conv_tol_residual=1e-7) repeats it. These experimental molecular-only entry points reuse the captured RHF source and fixed preparation; they do not change the molecular driver’s default.

The denominators are the serial localized occupied Fock diagonals and semicanonical pair virtual energies. Update doubles with R2 / D2, then symmetrize diagonal doubles; update singles with R1 / (Fii - ea). There is no damping or DIIS. The serial oracle uses diis_size=1, which keeps one history vector and performs no extrapolation. Reference, retained pair layout, static native neighborhood transforms and rectangular overlaps are prepared once and retained across amplitude epochs. The prepared native consumer imports only its current neighborhood and retires those amplitude copies and dynamic intermediates before returning.

Each target contributes its raw correlation energy using singles projected into that pair frame: tau = T2 + ti tj^T, contracted with 2K - K^T. Multiply an off-diagonal pair contribution by two, a diagonal by one, and add 2 sum_i Fia ti^a once on diagonal owners. The scalar reduction includes empty participants. This is the iterated retained-pair CCSD energy, before screened pair, PNO-truncation or perturbative triples corrections.

The serial r_norm is the global maximum absolute amplitude change after symmetry, over all singles and doubles. It is an amplitude norm, not a raw residual in hartree. Stop after at least two updates when both the energy change and that norm are strictly below their respective tolerances. A Solution carries converged, stopping_reason (converged or max_iter), history and state. The state includes the independently refreshed R1/R2 and their global maximum absolute component raw_residual at the returned amplitudes, including for a deliberately iteration-capped result.

Every owner constructs private new blocks while preserving the previous state. A collective admission completes on every rank before those blocks can serve as the next epoch’s neighbor inputs. Residual and energy evaluation of that agreed candidate must then complete everywhere before advance returns a state. A recoverable owner computation, stale-input or budget failure publishes no state on any participant; the caller retains the previous epoch. Fatal MPI process or transport failures retain the runtime protocol’s job-termination limits; this does not implement process-failure recovery.

The iteration cap additionally charges simultaneous old amplitudes, old residuals, new amplitudes, the new pending residuals, four largest owned blocks of update/denominator/symmetry scratch, and 1024 bytes of scalar control allowance. Remote snapshots, leases, native amplitude import allowance and packet slots remain charged by evaluate. The solution reports the maximum of initialization and epoch ledger peaks. As for the fixed evaluator, this is a logical solver/transport allocation ledger, not total RSS. Replicated reference/factors, retained static neighborhood transforms/overlaps, Eigen contraction intermediates, Python object overhead and MPI implementation storage remain outside this cap. Retaining extra caller checkpoints adds storage outside the two-state operation. No capacity or speedup claim follows.

Verification and triples state

tests/fixtures/molecular_mpi_iteration.py pins the unchanged native serial solver before MPI, compares every first-update and terminal block and every energy/update-norm history entry, and reevaluates returned-state energy and raw residual with the complete serial evaluator. It exercises swapped owners, an empty rank, iteration capping, stale neighbors and owner failures after a successful update. Full-amplitude collection exists only in this harness. The focused test compiles the production molecular binding and solver without requiring unrelated native engines.

The molecular (T0) consumer accepts solution.state only when solution.converged is true: the immutable source/frame identity is state.frame == problem.fingerprint(), placement is state.owners, and the agreed iteration identity is state.epoch. The state’s local mapping associates owned (i,j) and (i,) keys to authenticated Amplitude records in problem.frames. Reversed doubles use a transpose; singles retain their diagonal frame. state.residual, state.raw_residual, state.r_norm and state.correlation_energy describe this same returned state. A triples consumer must request remote blocks at that exact epoch through an admitted bounded transport; no global amplitude array is supplied. DIIS, iterative (T1) and periodic local correlation remain separate increments.

Distributed molecular closed-shell (T0)

vibeqc.dlpno.mpi_triples.evaluate_t0(problem, owners, solution, max_bytes=..., tcut_tno=0., lindep=1e-9, occ_dist=None, coupling_radius=0.) is an experimental collective interface. It consumes only a converged Solution from the owner solver above. It verifies the problem fingerprint, pair owners, amplitude keys and epoch on every rank, and agrees on the complete triples options and state before work. Supply the same occupied distances and screening radius as the intended serial run; zero radius disables screening. It does not change the driver’s default.

The contract is the actual serial ccsd_local_solver.py local dispatch into triples_local.local_triples_correction, selecting the native dlpno_ccsd_local_triples kernel in dlpno_ccsd.cpp. Distinct sorted occupied keys have one, two or three members. A singleton represents (i,i,i); a two-member key represents all six ordered triples containing both members; a three-member key represents its six permutations. Every pairwise distance must be at most a positive screening radius. No additional multiplicity is applied to the native per-key energy, which already sums these permutations.

One key has exactly one executor, the owner of its first occupied’s diagonal pair. The executor fetches only doubles with at least one endpoint in the key and singles for the key’s occupieds. The connected occupied sum still includes all available partners, including occupieds outside the key and outside a CCSD residual neighborhood. It uses stored i<=j blocks; the unchanged native tord(a,b) transposes reversed doubles. Ghosts carry the common frame/options/placement digest, epoch, target and source identity, transfer sequence and checksum through the existing bounded W=1 transport. Receive snapshots and native read leases survive packet retirement through the key’s last use. There is no production full-amplitude gather or dense global T2.

TNOs are the orthonormal union of retained internal pair spaces, including diagonal pairs. The existing relative singular-value cutoff removes linear dependence. At positive tcut_tno, the existing projected density sum(T T^T + T^T T) selects occupations strictly above the cutoff, retaining the largest if none survive. The retained space is diagonalized against Fvv. Integrals are transformed from the same localized-occupied/canonical-virtual DF factors, not projected from pair integrals. Denominators use diagonal localized Foo and these TNO Fock eigenvalues. The native connected X, six-image W, disconnected singles V and closed-shell energy expression are unchanged.

The primary basis is Riplinger et al., Theory Eqs. (1)-(15), Implementation and Semicanonical triples correction. The serial implementation uses radius screening, the density above and retained pair lists rather than the paper’s weak-pair selection and averaged contravariant density. This distribution preserves those choices. In particular, this interface and its T0Result.model explicitly say (T0). It implements neither iterative (T1) nor periodic triples.

The cap charges all numerical FixedPNO factors, frames, orbital data, energies and exchange blocks, plus the supplied state’s owned amplitudes and residuals. It also charges logical controls, pending per-key results, active packets and ghost leases. Before fetching or computing a key it reserves a conservative numerical envelope for simultaneous native imports, TNO QR/SVD and fallback, density/eigensolves, DF transforms, projected amplitudes, occupied sums, cached X cubes, W/V and contraction scratch. The envelope uses the full virtual dimension as the pre-truncation bound. Rank-local peaks are logical numerical admission bounds, not measured RSS. Python/allocator headers, BLAS and MPI implementation storage, extra caller checkpoints and cached CCSD evaluators are excluded. Retire the caller’s CCSD evaluator cache with problem._evaluators.clear() or account for it separately. This is not a solver-wide capacity or performance qualification.

T0Result returns only executor-local contributions and n_tno, the collectively reduced e_t0, frame, epoch and per-rank transport/peak ledger. It publishes after every key, count check and energy reduction succeeds. Recoverable refusals discard pending energies everywhere. The caller’s converged state stays intact and can be reused at the admitted cap. Fatal transport failures keep the existing job-termination limits. The caller reports RHF, raw CCSD, (T0), separately applied pair/PNO corrections and their sum; e_t0 contains only the triples correction.

Reproducing the distribution check

The verification harness pins the same-source serial solver and native/Python (T0) before running MPI, and compares every key, the reduced correction and final energy at absolute 2e-11 Ha, relative tolerance zero. It alone may gather full amplitudes. The accepted water fixture with radius 0.6 bohr is retained as a singleton-only zero-correction regression. A separate full-coupling water fixture retains that reference and the unequal PNO spaces while enabling a nonzero correction with cross-owner dependencies. Two spatial virtuals can host opposite-spin triples; their TNO rank does not imply zero correction.

python tests/fixtures/molecular_mpi_triples_prepare.py water.npz
python tests/fixtures/molecular_mpi_triples.py baseline water.npz
MPI4PY_RC_THREAD_LEVEL=funneled mpiexec -n 2 python \
    tests/fixtures/molecular_mpi_triples.py verify water.npz

Preparation uses a healthy full native RHF runtime, selected explicitly with VIBEQC_RHF_NATIVE when needed; its native SHA-256 is recorded. It runs HCORE conventional RHF at energy/gradient thresholds 1e-14/1e-13, then captures the evaluated source, Boys orbitals, one frozen occupied, STO-3G, def2-SVP-RIFIT, full Mulliken domains, TCutPNO=1e-4 and diagonal scale 0.03. The complete-check fixture applies no screened-pair or PNO energy correction; its reported total is RHF plus raw retained-pair CCSD plus (T0).

The harness supports the focused current-source native module through VIBEQC_MOLECULAR_NATIVE. Run with one numerical thread per rank. Three ranks exercise an empty participant; owner maps are exchanged. Checks include nonzero TNO cutoffs, screening, unconverged/wrong-frame/wrong-owner/wrong-epoch state, stale remote blocks, a kernel failure after private work, exact caps, one byte below a cap and successful reevaluation after refusal. Per-rank JSON records beside the fixture include every energy contribution and ledger. Physical-node verification additionally requires T0_REQUIRE_TWO_NODES=1. An external ORCA comparison must verify the semicanonical triples variant actually executed and retain the known pair-space/correction differences; only identical-domain serial results are distribution equality gates.