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.