vibe-qcDocumentation

AICCM analytic gradients: theory record

Status: experimental

Every gradient described here is an experimental library implementation. The Γ-CCM drivers emit AICCM2026DevAExperimentalWarning and the χ-CCM drivers AICCM2026DevBExperimentalWarning. The numbers are research output, not validated results, and none of these gradients is part of the release gate. The label vocabulary is defined in Methods: theory and status.

This page is the written derivation of the analytic nuclear gradients that exist for the AICCM energies and for their molecular reference implementations. Each equation is the one the code evaluates, in the code’s conventions, and each symbol is tied to the function or array that holds it. Where the code and its docstring disagree, the code is described.

The four-centre (union-and-weight lineage) gradients of periodic/ccm/gradient_analytic.py differentiate a different Hamiltonian and are documented in the four-centre gradient note; they are not repeated here.

Scope and status

Evidence level. Every gradient on this page is checked against central finite differences of the same energy, with the same thresholds and, for local methods, the same frozen selection, on small fixtures: H2, He2, H2 + He and LiH cells, and water, NH3, OH, NH2, CH2 and LiH molecules, in minimal or split-valence bases. Finite differences check the derivative; they say nothing about the accuracy of the energy. The only external comparison on record is for the molecular same-fit RI-MP2 energy: against ORCA 6.1.1 (RIJK with the same auxiliary basis, no frozen core) the Hartree-Fock energy agrees to 1e-10 Ha and the RI-MP2 energy to 3e-9 Ha at three geometries, and finite differences of the two programs’ energies agree to 3e-8 Ha/bohr (MP2 user guide). ORCA’s analytic gradient for that energy differs from those differences by 1.4e-4 Ha/bohr and is not used as a reference. No periodic gradient has an external reference yet.

What exists.

Line

Energy

Entry point

Section

molecular

same-fit RI-MP2, frozen core

compute_ri_mp2_gradient

RI-MP2

molecular

same-fit RI-UMP2

compute_ri_ump2_gradient

RI-UMP2

molecular

local MP2, frozen selection

compute_local_mp2_gradient

local MP2

molecular

same-fit RI-CCSD, RI-CCSD(T)

compute_ri_ccsd_gradient

CCSD and (T)

molecular

union-PNO CCSD(T), frozen selection

compute_union_pno_ccsd_gradient

union-PNO

Γ real-gamma

RHF, UHF, RKS, UKS

run_ccm_direct_gradient

Γ SCF

Γ real-gamma

RI-MP2

run_ccm_ri_mp2_gradient

Γ RI-MP2

Γ real-gamma

RI-UMP2

run_ccm_ri_ump2_gradient

Γ RI-UMP2

Γ real-gamma

DLPNO-MP2, frozen selection

run_ccm_dlpno_mp2_gradient

Γ DLPNO-MP2

Γ real-gamma

RI-CCSD, RI-CCSD(T)

run_ccm_ri_ccsd_gradient

Γ CCSD(T)

Γ real-gamma

union-PNO CCSD, CCSD(T), frozen selection

run_ccm_dlpno_ccsd_gradient

Γ union-PNO

Γ real-gamma, MANTA sources

RHF

manta_rhf_gradient, manta_real_gamma_gradient

Γ MANTA RHF

χ

RI-RHF without explicit controls

compute_aiccm2026dev_b_gradient

χ RI-RHF

χ

RI-RHF with ChiCoulombControls

compute_aiccm2026dev_b_gradient

χ RI-RHF

χ

RI-MP2 on the explicit-controls reference

compute_aiccm2026dev_b_mp2_gradient

χ MP2

χ

CCSD, CCSD(T) on the same reference

compute_aiccm2026dev_b_cc_gradient

χ CCSD(T)

χ

front-door forces and fixed-cell relaxation of the above

run_periodic_job(variant="chi", chi_gradient=True / optimize=True)

χ front door

What is not covered. Cell derivatives (stress) and Hessians; open-shell correlated gradients on either periodic line other than Γ RI-UMP2; Kohn-Sham references for any correlated gradient; symmetry-reduced meshes and fits; screened and double hybrids; effective core potentials in the correlated gradients; the χ per-pair DLPNO and translation-local energies; χ UHF, ROHF and KS SCF gradients; SR/LR, tailed and screened explicit χ sources. Each is refused with a message rather than replaced by another gradient. Front-door optimisation exists for the Γ SCF surface, for the Γ RI-MP2 surface (run_ccm_ri_mp2_optimize) and for the χ explicit-controls surfaces (RHF, MP2, CCSD, CCSD(T)); relaxation on MANTA sources stays refused.

Neither manuscript derives nuclear gradients, and the Lean development contains no gradient statement (see what Lean covers).

Common framework

Notation and the density fit

C holds the canonical orbitals of the fitted Fock matrix, n_o occupied columns of which the first n_f are a frozen core (c), the rest active (i, j, k, l), and virtual columns a, b. eps are the orbital energies, f = C^T F C the MO Fock matrix, and \(D = 2 C_o C_o^T\) the spin-summed closed-shell density. The molecular modules use one fit with three-index integrals T[P, mu, nu] = (P|mu nu) (compute_3c_eri), metric V_PQ = (P|Q) (compute_2c_eri) and coefficients \(c = V^{-1} T\) (_Fit.c):

\[(pq|rs) = \sum_P T_{P,pq}\, c_{P,rs}, \qquad J(M) = \sum_P T_P\, (c_P \cdot M), \qquad K(M)_{\mu\nu} = \sum_P (T_P\, M\, c_P)_{\mu\nu}.\]

The fitted closed-shell Fock matrix and its two-electron response are

\[F = h + G(D), \qquad G(M) = J(M) - \tfrac12 K(M) \;\big[\,-\tfrac12\,\xi\, S M S\,\big],\]

where the bracket is the exchange q = 0 term of the periodic torus. xi is the code’s BvK Madelung constant (ccm_exchange_q0_madelung, _madelung_for_kmesh, the madelung field of the gradient context); it depends on the lattice only, and it is the negative of the manuscripts’ signed self-potential (Paper 1 eq:seam).

The Lagrangian

Every closed-shell correlated gradient uses the functional

\[L = E_{\rm HF} + \sum_{pq} Q_{pq} f_{pq} + \tfrac12 \sum_{pqrs} \Gamma_{pqrs}\,(pq|rs),\]

with Q the symmetric, spin-summed one-particle density plus all orbital multipliers, and Gamma spin-summed with \(\Gamma_{pqrs} = \Gamma_{rspq}\) (assemble_ri_lagrangian_gradient, arguments P and gamma_fit). Gamma never reaches the AO basis: the assembly receives the map gamma_fit(c)[P, p, q] = sum_rs Gamma_pqrs c[P, r, s] and forms G3g = gamma_fit(c_mo), so that \(\tfrac12 \sum \Gamma (pq|rs) = \tfrac12 \sum G3g[P,p,q]\,(pq|P)\). MP2 is the special case Gamma_iajb = t~_ij^ab in the four occupied-virtual orderings, written in the code as \(2 \sum G3[P,i,a]\,(ia|P)\) with \(G3[P,i,a] = \sum_{jb} \tilde t_{ij}^{ab} c_{P,jb}\) and \(\tilde t = 2t - t^{\rm swap}\) (argument G3). The χ coupled-cluster module writes the same functional as \(\sum P f + \sum \Gamma'(pq|rs)\) with \(\Gamma' = \partial L / \partial (pq|rs)\), which is \(\Gamma/2\) of this convention (_real_torus_cc_lagrangian).

Orbital derivative and the connection term

With \(X = C^T \partial L / \partial C\) (X in _assemble of gradient/ri_mp2.py),

\[X = 2 f Q + 4\, \big[C^T G(C Q C^T)\, C_o\big]_{\rm occ\ columns} + 4 f_{:,\rm occ} + X^{\rm ns},\]

where the first two terms are orbital_derivative(Q), the third the Hartree-Fock reference (\(\partial E_{\rm HF}/\partial C_o = 4 F C_o\)), and \(X^{\rm ns}_{rp} = 2 \sum_{P,q} (rq|P)\, G3g[P,p,q]\) the non-separable part (the factor 2 because G3g is linear in the fit coefficients, which also depend on C). Orthonormality \(C^T S C = 1\) is not a free condition: the derivative at fixed coefficients (x) is corrected by the connection term,

\[\frac{dE}{dx} = L^{(x)} - \tfrac12 \sum_{pq} S^{(x)}_{pq} X_{pq} = L^{(x)} - {\rm tr}\big[W S^{(x)}\big], \qquad W = \tfrac14\, C (X + X^T) C^T .\]

overlap_gradient_contribution(basis, mol, W) returns \(-{\rm tr}[W S^{(x)}]\), and on the torus _compute_overlap_w_gradient_multik has the same sign.

Multipliers and when they are needed

Stationarity of L under a rotation kappa_pq reads \(X_{pq} - X_{qp} = 0\).

  • Occupied-virtual (Brillouin). The Z-vector multipliers \(Q_{ia} = Q_{ai} = z_{ia}\) solve \(X_{ai} - X_{ia} = 0\), that is \(2(\epsilon_a - \epsilon_i) z_{ia} + 4\,[C^T G(C Q(z) C^T) C]_{ai} = -(X^0_{ai} - X^0_{ia})\), with \(X^0\) evaluated before z (Handy and Schaefer, J. Chem. Phys. 81, 5031 (1984), doi:10.1063/1.447489, as cited in the code). The solver is a preconditioned conjugate gradient with diagonal \(2(\epsilon_a - \epsilon_i)\) (_pcg). An occupied-virtual block of the correlated density multiplies the vanishing \(f_{ai}\) and merges with z.

  • Same-class pairs fixed by a canonical condition. For two orbitals of the same class the two-electron part of X is symmetric (occupied) or absent (virtual) and of \(2 f Q\) only the pair survives, so \(Q_{pq} = (X^0_{pq} - X^0_{qp}) / (2(\epsilon_q - \epsilon_p))\) in closed form, independent of the other pairs and of z, to whose right-hand side it contributes (_Channel.constrained_pairs, canonical_multipliers). This is needed for the core-active pairs of a frozen core (the frozen orbitals are defined by \(f_{ci} = 0\)) and, for a functional that depends on canonical orbitals and their energies such as canonical (T), for all active-active and virtual-virtual pairs (canonical=True). A pair closer than _DEGENERACY_GAP = 1e-6 Ha gets no multiplier; its numerator must vanish to stationarity_tol, otherwise the gradient is refused.

  • Invariance instead of a multiplier. A functional that is stationary in its amplitudes (MP2, CCSD with full Fock blocks) is invariant to active-active and virtual-virtual rotations: the antisymmetry of X there is a measured property of the input (invariance_residual) and is refused above stationarity_tol.

  • Degenerate pairs on a torus. A torus has degenerate pairs by symmetry (characters k and -k), where the quotient form above is 0/0. The Γ canonical (T) gradient admits such a pair only when its numerator vanishes; the χ CCSD(T) gradient uses the orbital-invariant form of (T) instead, whose full Fock derivative replaces the quotient (χ CCSD(T)).

  • Localisation. A truncated local energy depends on the localised orbitals. The stationarity condition of the localisation functional \(r_{kl} = \sum_c \langle k|O_c|l\rangle (\langle k|O_c|k\rangle - \langle l|O_c|l\rangle) = 0\) receives multipliers \(\lambda_{kl}\) from a dense linear system (the Hessian of the functional, _localisation_terms, _multiplier_weights); a condition number above localisation_condition_max (1e8) is refused as a non-unique localisation. The condition number is the ratio of two numbers (_localisation_condition, one definition for the molecular and torus MP2 gradients and the union-PNO CCSD gradient). The denominator is the smallest singular value of the Hessian. The numerator is the larger of its largest singular value and the squared size of the localisation operators in the active orbitals. For Pipek-Mezey that size is the largest squared element of the atomic populations \(\langle k|O_A|l\rangle\), which cannot vanish because the populations of an orbital sum to one. For Foster-Boys it is the largest orbital spread in the basis, \(\max_k \sum_c \bigl(\sum_p \langle k|r_c|p\rangle^2 - \langle k|r_c|k\rangle^2\bigr)\) with \(p\) over all molecular orbitals, which does not change under a rigid translation. The ratio of the singular values alone is one for a single pair of active orbitals however small the Hessian is. Such a pair occurs when a frozen core leaves a degenerate pair under a threefold axis, or the \(\pm k\) pair of a three-cell torus, as the whole active block: the functional of two orbitals varies as \(\cos(4\theta + \varphi)\) with the rotation angle and is flat under that symmetry. Measured: Hessian 6.4e-13 against a spread of 8.9 bohr\(^2\) for three H2 on a ring, and 1.6e-14 against squared populations of 0.11 on the H2 (3,1,1) torus; both are refused (#1220).

The gradient is exact only for a stationary reference. The reference term \(4 f_{:,\rm occ}\) is added to X after the Z-vector solve, so a residual \(f_{ai}\) enters at first order; every driver gates brillouin_residual at stationarity_tol (1e-6 by default) and reports it.

The multi-k GDF drivers return the last-update orbitals with Rayleigh-quotient orbital energies rather than re-canonicalised ones (since 50f9951e, #601); the orbitals are canonical only to about 2e-7. A quantity that assumes exact canonicality of a returned multi-k reference therefore carries a residual of that order in the orbitals. On the χ MP2 gradient this moved the two correlation-energy re-evaluation residuals from 5e-17 to 6.6e-13 Ha/cell on the largest test fixture, well inside the gradient’s own gate of 1e-10 Ha/cell (χ RI-MP2).

Every two-electron derivative is a three-index and a metric weight

With \((pq|rs) = \sum_{PQ} T_{P,pq} [V^{-1}]_{PQ} T_{Q,rs}\) every two-electron term \(E = \sum \Gamma_{\mu\nu\lambda\sigma} (\mu\nu|\lambda\sigma)\) differentiates to \(\sum W3_{P,\mu\nu}\, T^{(x)}_{P,\mu\nu} + \sum \omega_{PQ} V^{(x)}_{PQ}\), contracted by compute_3c_eri_gradient_weighted and compute_2c_eri_gradient_weighted. With \(M = D/2 + Q_{\rm AO}\), \(m_P = c_P \cdot M\), \(n_P = c_P \cdot D\), the closed-shell weights of _assemble are

\[W3_P = n_P M + m_P D - M c_P D + 4\, C_a G3_P C_v^T + C\, G3g_P\, C^T,\]
\[\omega_{PQ} = -m_P n_Q + \tfrac12 \sum_{\mu\nu} (M c_P D)_{\mu\nu} c_{Q,\mu\nu} - 2 \sum_{ia} G3_{P,ia} c_{Q,ia} - \tfrac12 \sum_{pq} G3g_{P,pq} c_{Q,pq},\]

both symmetrised. The one-electron term contracts \(D + Q_{\rm AO}\) with \(h^{(x)}\) (one_electron_gradient_contribution), and the complete gradient is the sum of the nuclear, one_electron, overlap, three_center and metric components (Weigend and Häser, Theor. Chem. Acc. 97, 331 (1997), doi:10.1007/s002140050269, as cited in the code).

On the periodic fit the same reduction runs per momentum transfer q. A term is a functional \(E = \sum_q {\rm Re\,Tr}[A(q) H(q)]\) of the raw three-index sources T(q, k) and the truncated inverse metric \(H(q) = U h(\lambda) U^H\), with \(h(\lambda) = 1/\lambda\) on retained modes and 0 on dropped ones. It supplies metric_gram (A(q)) and tensor_weight (W3 with \(dE = {\rm Re} \sum dT \cdot W3\) at fixed metric), and _fit_weight_gradients_multik sums the weights of all terms before one derivative-kernel call per q and pair. The metric response is the divided-difference derivative of the truncated inverse, \(dH = U (h^{[1]} \circ U^H dM\, U) U^H\), with \(h^{[1]}_{ab} = -1/(\lambda_a \lambda_b)\) for two retained modes, \((h_a - h_b)/(\lambda_a - \lambda_b)\) for a retained and a dropped one, and 0 for two dropped ones, contracted as \(\Omega = \overline{U (h^{[1]} \circ U^H A U) U^H}\) (_fit_metric_weight; the tables are built in _build_multik_rsgdf_gradient_cache, _build_classic_gradient_cache_from_source and _signed_truncated_inverse_frechet). A metric eigenvalue on the threshold, or a retained and a dropped eigenvalue closer than the spectral tolerance, is refused: the retained rank is a frozen selection.

Molecular rungs

These are dense reference implementations on one density fit shared by the reference and the correlation. They are the molecular limits of the Γ correlated energies (Paper 1 eq:fit, eq:mp2ri, eq:pao, eq:pairdens, eq:ccsd) and the algebra the periodic gradients reuse.

Molecular same-fit RI-MP2

Energy: \(E = E_{\rm HF} + \sum_{iajb} \tilde t_{ij}^{ab} (ia|jb)\) with \(t = (ia|jb)/(\epsilon_i + \epsilon_j - \epsilon_a - \epsilon_b)\) on the shared fit. The Hylleraas functional is stationary in t, so L is differentiated at fixed amplitudes. Additional conditions: Brillouin (Z-vector) and, with frozen_core, the core-active closed form, which for MP2 is \(Q_{ci} = 4 \sum_{P,a} G3[P,i,a]\,(ca|P) / (2(\epsilon_i - \epsilon_c))\).

Term

Code

\(P_{oo} = -2 \sum \tilde t_{ij}^{ab} t_{kj}^{ab}\), \(P_{vv} = 2 \sum \tilde t_{ij}^{ab} t_{ij}^{cb}\), G3

compute_ri_mp2_gradient

X, Z-vector, core-active multipliers, W, W3, omega

_assemble via assemble_ri_lagrangian_gradient

integral derivatives

nuclear_repulsion_gradient, one_electron_gradient_contribution, overlap_gradient_contribution, compute_3c_eri_gradient_weighted, compute_2c_eri_gradient_weighted

Per-run checks: brillouin_residual under the fit (a reference from another fit is refused), canonical occupied block and a core-active gap of 1e-6 Ha with a frozen core, invariance_residual, Z-vector convergence. Finite differences (five-point, h = 2e-3 bohr, test bound 1e-8 Ha/bohr, tests/test_ri_mp2_gradient.py): measured 4.6e-11 to 7.2e-11 Ha/bohr for water and NH3, all-electron and frozen core, STO-3G/def2-svp-jk and def2-SVP/def2-svp-rifit. Omitting the core-active multipliers changes the frozen-core gradient by 1e-5 to 7e-5 Ha/bohr.

Molecular same-fit RI-UMP2

Energy: same-spin \(\tfrac12 \sum t^{ss}(ia|jb)\) with antisymmetrised amplitudes and opposite-spin \(\sum t^{ab}(ia|JB)\) on a fitted UHF reference whose Fock matrices are \(f^s = h + J[D_\alpha + D_\beta] - K[D_s]\). The assembly runs over spin channels of occupation 1 (_Channel), coupled only through the Coulomb response in orbital_derivative and therefore in one Z-vector over both spins; the frozen-core block is spin-diagonal. Code: compute_ri_ump2_gradient, assemble_ri_lagrangian_gradient_unrestricted. Checks: Brillouin residual per spin. Finite differences: OH and NH2 doublets and CH2 triplet, all-electron and frozen core, 1.4e-11 to 7.9e-11 Ha/bohr; on closed-shell orbitals the unrestricted gradient equals the restricted one to 1e-15 Ha/bohr.

Molecular local MP2, frozen selection

Energy (compute_local_mp2_energy, the definitions of run_dlpno_mp2): Foster-Boys localised active orbitals, projected atomic orbital (PAO) domains made non-redundant against S, pair natural orbitals (PNOs) from the semicanonical pair density, coupled first-order equations in the PNO bases, the semicanonical truncation correction and the dipole estimate of screened pairs. With AO amplitudes \(\theta_{ij} = V_{ij} T_{ij} V_{ij}^T\) and \(K_{ij}[\mu,\nu] = (i\mu|j\nu)\), the functional differentiated is the Hylleraas functional restricted to the pair spaces,

\[H = \sum_{ij} \Big\{ 2\langle \tilde\theta_{ij}, K_{ij}\rangle + \langle \tilde\theta_{ij}, F\theta_{ij} S + S\theta_{ij} F\rangle \Big\} - 2 \sum_{ijk} f_{ik} \langle \tilde\theta_{ij}, S \theta_{kj} S\rangle,\]

stationary in the amplitudes, so the correlation energy (iterated term plus domain minus PNO semicanonical terms, plus the dipole estimate) is differentiated at fixed amplitudes. Additional conditions: the Boys condition with multipliers \(\lambda\), core-active closed form, Z-vector, and the response of every space through its span.

Term

Code

explicit weights of the three Hylleraas-type functionals on F, S, the half-transformed three-index integrals and the occupied Fock block

_functional_weights

PNO eigenvector response through the pair density and the amplitude equation \(T = K/\Delta\)

_correlation_weights (with _density_amplitude_weight)

domain response: inside the span \(-\tfrac12 V (V^T G) V^T\) on S; outside it \(\sum_x \vert x\rangle\langle x\vert dA\vert r\rangle/(a_r - a_x)\) for \(A = P^T S P\)

_space_response

dipole estimate of screened pairs

_distant_terms, _correlation_weights

Boys multipliers, core-active, Z-vector, W3, omega

_assemble (this module’s own assembly)

dipole-integral derivative of the Boys term and of the estimate

_dipole_gradient_weighted (helper shells of angular momentum l + 1 and l - 1, fitted exactly and checked)

Per-run checks: Brillouin and canonical residuals, Boys stationarity below 1e-9, amplitude residual, lagrangian_residual, space_invariance_residual, coincidence of a kept and a dropped eigenvalue (PAO or PNO, relative 1e-9) refused, non-unique localisation refused (the N2 pi bonds are the test case). Finite differences of the frozen-selection energy (test bound 1e-8 Ha/bohr, tests/test_local_mp2_gradient.py): fixed pair list 4.4e-11 Ha/bohr on water; Mulliken domains, PNO truncation and screened pairs on the water dimer 1.3e-10 to 1.8e-10 Ha/bohr. The full-space route (compute_local_mp2_full_space_gradient, all pairs and the complete virtual space through the shared assembly) equals the canonical RI-MP2 gradient to 7.7e-12 Ha/bohr. The docstring of compute_local_mp2_gradient lists the refusals of the code: non-unique localisation, unseparated frozen core, the eigenvalue coincidences, and the options outside the covered set.

Molecular RI-CCSD and RI-CCSD(T)

Energy: canonical closed-shell CCSD, optionally with (T), on the shared fit. Lagrangian \(L = E_{\rm HF} + E_c(t; f, g) + E_T(t; \epsilon, g) + \sum m R(t; f, g) + \sum Q f\). Stationarity in m gives the CCSD equations and in t the Lambda equations \((\partial R/\partial t)^T m = -\partial E_c/\partial t - \partial E_T/\partial t\). \(E_c + mR\) is linear in \((f, g)\) and \(E_T\) is homogeneous of degree one in \((\epsilon, g)\) at fixed t, so the correlated part is exactly \(\sum P f + \tfrac12 \sum \Gamma (pq|rs)\) with \(P = \partial L/\partial f\), \(\Gamma_{pqrs} = \partial L/\partial (pq|rs) + \partial L/\partial (rs|pq)\) over the six blocks ovov, ovvv, ooov, oooo, oovv, vvvv; the diagonal of P carries \(\partial E_T/\partial \epsilon_p\). The densities are not coded term by term: one reverse sweep through the evaluated residual and energy with seeds (1, m) returns them. With (T), canonical=True gives \(f_{ij} = 0\) and \(f_{ab} = 0\) the closed-form multipliers. The formulation follows Scheiner, Scuseria, Rice, Lee and Schaefer, J. Chem. Phys. 87, 5361 (1987), and for the orbital-energy dependence of (T) Scuseria, J. Chem. Phys. 94, 442 (1991); the (T) expression is that of Raghavachari, Trucks, Pople and Head-Gordon, Chem. Phys. Lett. 157, 479 (1989), doi:10.1016/S0009-2614(89)87395-6, in the closed-shell form of Rendell, Lee and Komornicki, Chem. Phys. Lett. 178, 462 (1991) (all as cited in the code).

Term

Code

CCSD amplitudes, refined to the gradient threshold

_solve_ccsd

Lambda with the (T) source

_solve_lambda, cs_ccsd_energy_gradient, _triples_derivatives

P, block densities bar

_ccsd_lagrangian_derivatives (reverse sweep)

(T) energy and its derivatives in t, g, eps

_triples_energy, _triples_derivatives

orbital conditions and integral derivatives

assemble_ri_lagrangian_gradient with P, gamma_fit, canonical

Per-run checks: Brillouin and canonical residuals, cc_residual, lambda_residual, density_residual (the densities reproduce \(E_{\rm CCSD} + E_T\)), invariance_residual, canonical_residual. Finite differences (test bound 1e-9 Ha/bohr, tests/test_ri_ccsd_gradient.py): measured 4.3e-11 to 6.6e-11 Ha/bohr for water and NH3, CCSD and CCSD(T), all-electron and frozen core (2.5e-10 for frozen-core LiH, 4.3e-12 with the residuals at 1e-13); H2 CCSD equals the fitted full CI to 2e-14 Ha. Without the canonical multipliers the water (T) gradient is wrong by 3e-7 Ha/bohr and the assembly refuses it.

Molecular union-PNO CCSD(T), frozen selection

Energy (compute_union_pno_ccsd_energy, the molecular form of ccm_dlpno_ccsd): pair orbitals from Pipek-Mezey, Foster-Boys or canonical orbitals of the active block (a frozen core is the lowest canonical occupied orbitals and is not localised, #1183); full pair domains; first-order amplitudes in the canonical virtual space; legacy pair density \(D^{ij} = (T T^T + T^T T)/(1 + \delta_{ij})\) kept above tcut_pno; union space spanned by the eigenvectors of \(M = \sum_{i \le j} \Pi_{ij}\) above pno_lindep, made semicanonical; canonical CCSD(T) in {active occupied, union}. Additional conditions, solved in this order:

  • Lambda and densities in the subspace (as in the molecular CCSD rung).

  • Rotations inside the union: with \(G = \partial L/\partial B\) over the full virtual space, \(B^T G\) is symmetric for CCSD (checked); for (T) \(Q'_{rs} = ([B^T G]_{rs} - [B^T G]_{sr})/(2(e_s - e_r))\).

  • Retained-discarded rotations: \(G_\perp = (1 - BB^T) G\) is the derivative with respect to the subspace. It is propagated in reverse through the chain of spectral projectors: a weight \(W\) on the projector onto the leading eigenvectors of a symmetric A becomes the weight \(\sum_{r,x} |x\rangle\langle x|W|r\rangle\langle r| / (a_r - a_x) + {\rm h.c.}\) on A (_projector_weight), applied first to M and then to each pair density; then \(\partial L/\partial T = 2(W_D T + T W_D)/(1 + \delta_{ij})\) and, through \(T = K/\Delta\), weights on (ia|jb), on the pair-orbital Fock diagonal and on the virtual energies.

  • Localisation multipliers with an overlap (Pipek-Mezey) or dipole (Foster-Boys) derivative term, passed to the assembly as orbital_derivative. The localisation condition and its multipliers cover the pairs of active orbitals only. The core-active rotations carry the canonical condition of the assembly, with the multipliers \((X_{ci} - X_{ic})/(2(\epsilon_i - \epsilon_c))\) (#1183). Until then all occupied orbitals were localised together and the first frozen_core localised ones dropped, which is not a frozen core once the rotation mixes the two spaces.

  • Canonical, frozen-core and Z-vector conditions through assemble_ri_lagrangian_gradient(canonical=True), needed even without (T) because the pair amplitudes use canonical virtual energies.

Checks: subspace_rotation_residual, subspace_response (reported), localisation_residual, cc_residual, lambda_residual, density_residual, coincident kept and dropped eigenvalues refused (_RELATIVE_GAP 1e-9). Finite differences (test bound 2e-9 Ha/bohr, tests/test_union_pno_ccsd_gradient.py, counts verified unchanged over the stencil): water def2-SVP 6.7e-11 to 3.5e-10 Ha/bohr, LiH 1.2e-11 Ha/bohr; the subspace response alone reaches 8.5e-3 Ha/bohr. With a frozen core in the gauge of #1183: water Pipek-Mezey CCSD 4.8e-12, water Foster-Boys CCSD(T) 4.7e-11 and LiH Foster-Boys CCSD 3.1e-12 Ha/bohr (LiH has one active orbital, so nothing is localised there). The gradient is the derivative of the Foster-Boys energy too; the molecular Boys variant has no periodic counterpart (the torus refuses it).

Γ-AICCM: the neutral fitted torus

All Γ gradients are per unit cell, \(dE_{\rm cell}/dR\) per unit-cell atom, with every periodic image moving with its atom. The real-Γ supercell and the multi-k Bloch control evaluate one block-circulant Hamiltonian in two Fourier-related representations. The integral derivatives are always evaluated in the Bloch representation, through the gradient context the multi-k driver retains; the correlated Lagrangians are solved on the real supercell.

Γ SCF through the Bloch representation

Energy: Paper 1 eq:energy with eq:fock, eq:fit and eq:seam, per cell, \(E = E_{nn} + {\rm tr}[D h] + \tfrac12 {\rm tr}[D J(D)] - \tfrac\alpha4 {\rm tr}[D K(D)] - \tfrac{\alpha\xi}4 {\rm tr}[D S D S]\) with traces as mesh averages. It is variational, so no orbital response enters. run_ccm_direct_gradient runs the multi-k GDF control with compute_gradient=True and returns its gradient after a per-run identity:

Term

Code

Ewald nuclear repulsion, kinetic, Ewald-gauge V_ne, \(-{\rm tr}[W dS]\)

_compute_oneel_w_gradient_multik

fitted Coulomb

_compute_j_gradient_multik_rsgdf

fitted exchange, times alpha

_compute_k_gradient_multik_rsgdf

exchange q = 0 seam: overlap weight \(\tfrac12 \alpha \xi D S D\)

_compute_exxdiv_w_gradient_multik

composition (RHF, UHF; the KS assemblies add the XC term)

_compute_krhf_gradient_multik, _compute_kuhf_gradient_multik, _compute_krks_gradient_multik, _compute_kuks_gradient_multik

control_start="independent" converges the control from its own guess; control_start="direct" transforms the converged real-Γ density to the mesh, \(M(k) = N_c^{-1} \sum_{c,c'} e^{+ik\cdot(R_{c'} - R_c)} M_{\rm sc}[(\mu,c),(\nu,c')]\) (_bloch_mesh_from_torus, the inverse of _unbloch_mesh_to_torus on block-circulant matrices), and the control reads it, so the force belongs to the direct state. Checks: energy parity \(|E_{\rm direct}/N_c - E_{\rm control}|\) within parity_tol (1e-6 Ha/cell by default), matched exchange q = 0 convention (assert_matched_exchange_q0), matched XC image cutoff for KS; in seeded mode also unfold_residual within DIRECT_GRADIENT_UNFOLD_TOL (1e-8) and control_density_difference within DIRECT_GRADIENT_SEEDED_DENSITY_TOL (1e-5), and equal spin sectors. Finite differences of the real-Γ energy (H2 in a 6 bohr cube, (2,1,1), five-point, h = 1e-2 bohr, tests/test_ccm_direct_gradient_seeded.py): seeded RHF 3.0e-9 (STO-3G) and 1.3e-8 Ha/bohr (6-31G), PBE 2.1e-8 and 1.8e-8, triplet UHF 2.6e-8 (one cell) and 1.1e-8 Ha/bohr; seeded and independent modes agree to 5.3e-13 Ha/bohr where symmetry fixes the density. The KS values of tests/test_ccm_direct_gradient.py at h = 2e-4 are limited by the XC grid (1.26e-4 PBE, 9.6e-5 PBE0, test bound 5e-4).

Γ periodic fit derivative and the bilinear functional

The correlated Γ gradients reuse the SCF kernels through MultikGradientContext (retained with retain_gradient_context=True): the fit source, mesh, resolved lattice options, alpha_hf and madelung. compute_closed_shell_gradient_from_context evaluates the driver’s own functional at supplied D(k), W(k), S(k). The separable part of a correlated Lagrangian is the fixed-matrix derivative of the bilinear functional (compute_bilinear_gradient_from_context)

\[E_{nn} + {\rm tr}[P h] - {\rm tr}[W S] + {\rm tr}[M\, G(N)], \qquad G(N) = J(N) - \tfrac\alpha2 \big(K(N) + \xi S N S\big),\]

with \(P = D + Q\), \(W = \tfrac14 C(X + X^T)C^T\), \(M = D/2 + Q\) and \(N = D\); at \(P = N = D\), \(M = D/2\) it is the SCF functional.

Term

Code

one-electron, nuclear, overlap

_compute_oneel_w_gradient_multik with \(W + \tfrac{\alpha\xi}2 (N S M + M S N)\)

seam \(-\tfrac{\alpha\xi}2\, d\,{\rm tr}[M S N S]\)

the added overlap weight above

Coulomb \({\rm tr}[M J(N)] = {\rm Re}\, v_M^H H(0) v_N\), \(v_X = \sum_k w_k T(0,k) : X(k)^T\)

_BilinearJKFitTerm (A(0), W3(0))

exchange \({\rm tr}[M K(N)] = \sum_q {\rm Re\,Tr}[G(q) H(q)]\), \(G(q)_{PQ} = \sum w_i w_j {\rm Tr}[T_P N(k_j) T_Q^H M(k_i)]\)

_BilinearJKFitTerm (A(q), W3(q))

non-separable correlated terms

extra fit_terms in the same pass

metric response of the truncated inverse

_fit_metric_weight with the cache tables

The unrestricted counterpart (compute_unrestricted_bilinear_gradient_from_context) uses \(\tfrac12{\rm tr}[D_t J(D_t)] - \tfrac\alpha2 \sum_s {\rm tr}[D_s(K(D_s) + \xi S D_s S)]\): one Coulomb term on the total matrices and one exchange-only term per spin (_BilinearExchangeFitTerm, coefficient 2 alpha), each spin’s seam weight \(\alpha\xi(N_s S M_s + M_s S N_s)\). No unrestricted correlated torus gradient uses it yet. Only the uniform full mesh is accepted (every weight \(1/n_k\)). Measured: context against the driver’s gradient 1.9e-15 (SR/LR) and 3.7e-16 Ha/bohr (classic); bilinear functional against finite differences for random fixed matrices 1.4e-9 (closed shell) and 1.6e-9 Ha/bohr (unrestricted, limit 1e-8); the full multi-k KRHF composition against the driver energy 1.1e-8 Ha/bohr at h = 2e-4 (test_multik_krhf_full_scf_gradient_vs_fd, gate 1e-6); the signed truncated-inverse table against a dense difference within 1e-9 (test_signed_truncated_inverse_frechet_matches_dense_fd).

Γ RI-MP2

Energy: \(E_{\rm RHF}[{\tt run\_ccm\_rhf\_direct}] + E_c[{\tt run\_ccm\_ri\_mp2\_on\_reference}]\) per cell on the carried fit (Paper 1 eq:mp2, eq:mp2ri). The Lagrangian is the molecular one on the real supercell (_supercell_lagrangian) with \((pq|rs) = \sum_A L_{A,pq} L_{A,rs}\) from the folded real factors and the seam in G; the gradient per cell is \((1/N_c)[L^{(x)} - {\rm tr}(W S^{(x)})]\). The non-separable part uses the unfolded quantities \(\tau_q[S,i,a] = N_c^{-1/2} \sum_k C_i(k)^H T(q,k)[S]\, C_a(k+q)\), in which \((ia|jb) = \sum_q {\rm Re} \sum_{RS} \overline{\tau_q[R,i,a]}\, H(q)_{RS}\, \tau_q[S,j,b]\); the three-index weight is \(Y_q = 4 \sum \tilde t\, \overline{[H\tau_q]}\) unfolded per (q, k) and the two-index density \(2 \sum \tilde t\, \tau_q \overline{\tau_q}\) goes to the metric (_ThreeIndexFitTerm).

Term

Code

amplitudes, P_oo, P_vv, G3, Z-vector, core-active

_supercell_lagrangian

Bloch control seeded from the direct state, context

_bloch_control (run_ccm_direct_gradient(control_start="direct"))

real supercell matrices to the mesh

on_mesh (_bloch_mesh_from_torus)

Bloch orbital components \(C_p(k)\)

_bloch_orbitals

separable and non-separable derivatives

compute_bilinear_gradient_from_context(fit_terms=[_ThreeIndexFitTerm])

Per-run checks: Brillouin and invariance residuals; control seeded and parity within 1e-8 Ha/cell; control S(k), h(k) against the transformed direct ones within 1e-8; madelung and alpha_hf of the context equal to the direct ones; densities block-circulant within MP2_GRADIENT_UNFOLD_TOL (1e-7); Bloch correlation functional against the real-Γ energy within MP2_GRADIENT_ENERGY_TOL (1e-8 Ha/cell); bilinear functional at the HF matrices against the control gradient within scf_gradient_tol (1e-6). Finite differences (h = 1e-2 bohr, tests/test_ccm_ri_mp2_gradient.py): H2 cells 1.8e-9 to 3.0e-9 Ha/bohr, correlation part alone 5e-10 or better. run_ccm_ri_mp2_optimize relaxes on this surface and checks at the final geometry the energy identity with the front-door evaluation (MP2_OPTIMIZE_ENERGY_IDENTITY_TOL, 1e-10) and one five-point difference (MP2_OPTIMIZE_FD_STEP 1e-2, MP2_OPTIMIZE_FD_TOL 1e-6; measured 3.5e-9).

Γ RI-UMP2

Energy (run_ccm_ri_ump2_gradient): \(E_{\rm UHF}[{\tt run\_ccm\_uhf\_direct}] + E_{aa} + E_{bb} + E_{ab}\) per cell on the carried fit, with \(E_{ss} = \tfrac14 \sum [(ia|jb) - (ib|ja)]^2 / D_{ij}^{ab}\) and \(E_{ab} = \sum (ia|JB)^2 / D_{iJ}^{aB}\), the energy of run_ccm_ump2. The Lagrangian is the molecular unrestricted one (Handy and Schaefer, J. Chem. Phys. 81, 5031 (1984), doi:10.1063/1.447489, as cited in the code) on the real supercell: \(F_s = h + J(D_\alpha + D_\beta) - [K(D_s) + \xi S D_s S]\) per spin, with \(G3^\alpha = t^{\alpha\alpha} B^\alpha + t^{\alpha\beta} B^\beta\) and \(G3^\beta = t^{\beta\beta} B^\beta + (t^{\alpha\beta})^T B^\alpha\). Additional conditions: the Z-vector couples the two spins through the Coulomb response alone (the response of \(f^s\) to \(X_\alpha + X_\beta\) is \(J(X_\alpha + X_\beta) - [K(X_s) + \xi S X_s S]\)); a frozen core takes the same number of lowest bands in each spin with closed-form core-active multipliers; no localisation is involved. With \(P = D_\alpha + D_\beta + Q_\alpha + Q_\beta\), \(W = \sum_s C_s (X^s + X^{sT}) C_s^T / 4\), \(M_s = D_s/2 + Q_s\) and \(N_s = D_s\) the separable part is the unrestricted bilinear functional of the fit-derivative section.

Term

Code

amplitudes, per-spin P, G3, spin-coupled Z-vector, core-active

_supercell_lagrangian_unrestricted

UHF reference, spin-sector check

_direct_uhf_reference, _require_one_spin_sector

Bloch control seeded from the direct state

_seeded_unrestricted_control

separable derivatives

compute_unrestricted_bilinear_gradient_from_context

non-separable derivatives: $\sum t^{aa}(ia

jb)_{aa} + \sum t^{bb}(ia

Per-run checks: Brillouin residual per spin; the fitted UHF functional at the reference orbitals against the reference energy within UMP2_GRADIENT_REFERENCE_ENERGY_TOL (1e-8 Ha/cell); symmetry of X per spin (invariance_residual); correlation energy against run_ccm_ump2 and the Bloch correlation functional against the real-Γ energy within MP2_GRADIENT_ENERGY_TOL (1e-8); densities block-circulant within MP2_GRADIENT_UNFOLD_TOL (1e-7); one spin sector and one state in the direct state and the control; the bilinear functional at the HF matrices against the control gradient within scf_gradient_tol (1e-6). Scope: the sector that both producers execute (spin_state="per-cell", the unit cell’s populations on every cell, spins aligned); restricted open-shell, Kohn-Sham, symmetry-reduced meshes, screened exchange and DLPNO truncation are refused. Finite differences (five-point, h = 1e-2 bohr, tests/test_ccm_ri_ump2_gradient.py; the helper bounds are 1e-7 Ha/bohr total and 1e-8 correlation part): H3 doublet in a 6 bohr cube, STO-3G on (2,1,1) 3.2e-10 (correlation part 6.4e-11), 6-31G on (1,1,1) 3.3e-10 (6.8e-11), the classic fit source 3.2e-10 (6.9e-11), He + H + H2 doublet with the He 1s band frozen 2.7e-10 (5.7e-11). On closed-shell orbitals in both spin channels the gradient is the restricted Γ RI-MP2 one to 4.8e-14 ((1,1,1)) and 4.2e-13 Ha/bohr ((2,1,1)); the context reproduces the unrestricted driver’s gradient to 3e-15 Ha/bohr.

Γ DLPNO-MP2, frozen selection

Energy: ccm_dlpno_mp2 on the direct reference and its fit, in the dense differentiable form ccm_local_mp2_energy (Paper 1 eq:pao, eq:pairdens): canonical (localize="none", the default) or Pipek-Mezey occupied gauge over all occupied orbitals, all pairs, Mulliken domains, legacy pair density, coupled amplitudes with the non-diagonal occupied Fock block and the semicanonical truncation correction. The molecular Hylleraas weights and space responses are reused unchanged through _TorusReference, whose Fock response is \(2J(M) - K(M) - \xi S M S\) per spin. Differences from the molecular rung:

  • Gauge condition. Pipek-Mezey: \(r_{kl}\) with the populations \(q_A^{kl} = \sum_{\mu \in A} [C_{\mu k}(SC)_{\mu l} + C_{\mu l}(SC)_{\mu k}]/2\) over the active occupied orbitals; its integral derivative is an overlap weight. Canonical: \(f_{kl} = 0\) for all occupied pairs with closed-form multipliers \((X_{kl} - X_{lk})/(2(\epsilon_l - \epsilon_k))\), which contain the core-active ones; a degenerate pair is admitted only when its antisymmetry is below 1e-8 relative.

  • With localised orbitals the frozen core is still the lowest canonical occupied orbitals, and only the active block is localised (#1183). The core-active rotations carry the canonical condition with the closed-form multipliers above. The localisation condition and its multipliers cover the active pairs only.

  • The Lagrangian weights need not be translation invariant. The derivatives of the torus operators are block-circulant, so only the block-circulant projection of a weight contributes; it is taken and its size reported as translation_asymmetry. The explicit three-index weight runs over localised occupied and all supercell orbitals (_ThreeIndexFitTerm).

Term

Code

gauge orbitals connected to the recorded ones

_gauge_orbitals

energy and selection

_build, CCMLocalMP2Selection

explicit weights, PNO and domain response

_correlation_weights (molecular)

gauge multipliers, Z-vector, AO weights

_assemble (this module)

integral derivatives

compute_bilinear_gradient_from_context with _ThreeIndexFitTerm

Per-run checks: as for Γ RI-MP2, plus lagrangian_residual within stationarity_tol, the Bloch value of the explicit three-index functional against its real-Γ value within DLPNO_GRADIENT_FIT_TOL (1e-8 Ha/cell), net_force reported. Measured: zero thresholds against the Γ RI-MP2 gradient 7.5e-13 Ha/bohr or better; finite differences of the frozen-selection energy 1.3e-11 to 9.2e-10 Ha/bohr for the admitted gauges on H2 + He (1,1,1) and two H2 (2,1,1), correlation part 2.7e-12 to 3.6e-11; truncation moves the gradient by 3.1e-5 to 2.5e-3 Ha/bohr (Γ-CCM reference).

Γ RI-CCSD(T)

Energy: \(E_{\rm RHF} + E_{\rm CCSD}\,(+E_T)\) per cell, canonical in the complete virtual space on the carried fit, the energy of run_ccm_ri_ccsd_on_reference (Paper 1 eq:ccsd); ccm_ri_ccsd_energy evaluates it at any geometry. The CCSD, Lambda and reverse-sweep machinery is the molecular one (_amplitude_response); the general-density orbital Lagrangian is solved on the real supercell with the seam in the Fock response (_density_lagrangian), with canonical=True for (T). The two-particle density goes to the fit as the linear map \(c \mapsto \sum_{rs}\Gamma_{pqrs} c_{rs}\) over all orbital pairs (_FitContractedTerm, which receives Gamma / 2).

Per-run checks: Brillouin and canonical residuals, cc_residual, lambda_residual, density_residual, invariance_residual, canonical_residual, lagrangian_residual; densities block-circulant within CC_GRADIENT_UNFOLD_TOL (1e-7); Bloch two-particle functional against its real-Γ value within CC_GRADIENT_FIT_TOL (1e-8); CCSD and (T) energies against run_ccm_ccsd within CC_GRADIENT_DRIVER_TOL (1e-7 Ha/cell, not made with a frozen core). Finite differences (6-31G, h = 1e-2 bohr, tests/test_ccm_ccsd_gradient.py): totals 9.3e-10 to 2.0e-9 Ha/bohr, limited by the Hartree-Fock part; correlation part 7.2e-12 to 6.4e-11 Ha/bohr.

Γ union-PNO CCSD(T), frozen selection

Energy (ccm_union_pno_ccsd_energy, the dense differentiable form of ccm_dlpno_ccsd; the torus counterpart of the molecular union-PNO rung): pair orbitals from Pipek-Mezey or canonical supercell orbitals, full pair domains (tcut_mkn must be zero), legacy pair density kept above tcut_pno (at least one per pair), union space spanned by the eigenvectors of the summed pair projectors above pno_lindep and made semicanonical, canonical CCSD(T) in {active occupied, union} on the carried fit. At tcut_pno = 0 the union space is complete and the energy is the canonical one. The frozen decisions are the number of PNOs per pair and the union dimension (UnionPNOSelection). Additional conditions beyond the molecular rung are those of the Γ canonical rung: the torus Fock response with the seam, the orbital-invariant (T) density (no canonical multipliers inside the union, so the semicanonical condition is not a constraint and stationarity under rotations inside it is the check subspace_rotation_residual), and the canonical conditions only for the pair construction (closed-form multipliers \((X_{pq} - X_{qp})/(2(\epsilon_q - \epsilon_p))\); two canonical orbitals closer than 1e-6 Ha get none and a pair with a rotation gradient above stationarity_tol is refused).

Term

Code

union energy, selection

ccm_union_pno_ccsd_energy, _union_energy

CCSD, Lambda, reverse sweep in the union space

_amplitude_response (molecular machinery)

union-space rotations, retained-discarded response, localisation multipliers

_subspace_lagrangian (vibeqc.gradient.union_pno_ccsd)

orbital Lagrangian with the torus Fock response

_density_lagrangian

two-particle density to the fit through all orbital pairs

_FitContractedTerm

integral derivatives

_periodic_gradient with compute_bilinear_gradient_from_context

Per-run checks: those of the Γ canonical rung, plus subspace_rotation_residual, CCSD and (T) energies and the union dimension against ccm_dlpno_ccsd when the selection is decided here (verify_driver_energy; a difference above 1e-7 Ha per cell raises; driver_ccsd_residual, driver_triples_residual), the smallest separations min_pno_gap and min_union_gap (a coincidence of a kept and a dropped value is refused), and localisation_multiplier. Refused: Foster-Boys pair orbitals, Mulliken pair domains, a non-unique localisation, a truncated energy that distinguishes degenerate canonical orbitals, and what the canonical rung refuses. Not detected: two canonical orbitals closer than 1e-6 Ha without symmetry degeneracy, whose multiplier would be finite. Finite differences of the frozen-selection energy with counts verified unchanged over the stencil (tests/test_ccm_ccsd_gradient.py, 6-31G, h = 1e-2 bohr; (2,1,1) at 2.5e-3 bohr): the dense energy equals ccm_dlpno_ccsd to 3.2e-12 Ha (CCSD) and 1.7e-14 Ha ((T)) or better; at zero thresholds the gradient is the canonical one to 4.4e-14 (Pipek-Mezey), 8.4e-14 (canonical orbitals), 1.8e-13 (CCSD) and 2.2e-13 Ha/bohr (two H2 on (2,1,1)), and to 4.5e-14 when the pairs are truncated but the union is still complete; truncated, H2 + He (1,1,1) with one PNO per pair and a union of 3 of 4 virtual orbitals 9.2e-10 (correlation part 4.9e-12), the truncation moving the gradient by 3.6e-4 Ha/bohr; canonical pair orbitals 9.2e-10 (4.6e-12); the lowest canonical orbital frozen 9.3e-10 (6.2e-12), and 1.4e-13 from the canonical frozen-core gradient at zero thresholds; two H2 on (2,1,1) with a union of 6 of 12 virtual orbitals 4.5e-10, the truncation moving the gradient by 3.4e-3 Ha/bohr. That fixture uses pno_lindep = 0.1: at the default the union would keep a direction at an eigenvalue of 2.3e-6, the sensitivity described under the properties of the energy definitions.

Γ MANTA-source RHF forces

Energy: the closed-shell real-Γ RHF energy of run_ccm_rhf_direct run on MANTA’s periodic sources (MANTAFitSource, MANTAOneElectronSource); no correlated energy. It is variational, so

\[dE = {\rm Tr}[D\,dh] + d(E_J + E_K)|_D - \tfrac14 \xi\, d\,{\rm Tr}[DSDS]|_D - {\rm Tr}[W\,dS] + dE_{nn}, \qquad W = \tfrac12 D F D,\]

with the seam coefficient \(\xi\) position independent. Each term is MANTA’s own producer evaluated on a basis that carries the centre-derivative shells of every function (\(\partial_{A_x}[x^a y^b z^c e^{-\alpha r^2}]\) is a combination of shells of angular momentum \(l + 1\) and \(l - 1\) on the same centre, derivative_basis), so the image lists, the Ewald split, the reciprocal vectors and every finite selection are those of the energy; the derivatives with respect to a nuclear or auxiliary centre follow from exact translation invariance of each retained term. No native kernel is added.

Term

Code

centre-derivative shells

derivative_basis

nuclear repulsion

manta_nuclear_repulsion_gradient

overlap, kinetic, Ewald nuclear attraction

manta_one_electron_gradient

fitted Coulomb and exchange at fixed density: SR image tiles, reciprocal part, metric, fixed positive eigenprojector of each kept channel

manta_fit_gradient (_projector_weights)

assembled forces, energy recomposition

manta_rhf_gradient

forces of a front-door run

manta_real_gamma_gradient

selection census

manta_selection_census

Frozen selections: MANTA’s finite sources are sums over members chosen by hard geometric cutoffs (AO pairs, nuclear images, auxiliary images, metric images). The gradient is the derivative with the membership fixed at the reference geometry; manta_selection_census lists each member’s distance to its cutoff, and the tests require identical membership at every stencil point. Per-run checks (manta_rhf_gradient): the energy is recomposed from the differentiated objects and compared with the SCF energy (recomposition_tol 1e-8 Ha per torus), the rebuilt overlap and core Hamiltonian, the translational sum and the SCF commutator (commutator_tol 1e-5). Refused: open-shell and Kohn-Sham references, correlated energies, screened integrals (integral_screen_error > 0), coupling approximations, a Wigner-Seitz truncated block cderi, non-3-D cells, Libint-backend runs, and relaxation (#637, #994). Evidence (tests/test_ccm_manta_gradient.py; the file states bounds, not measured values, except where noted): derivative-shell overlap and kinetic matrices against MANTA’s molecular derivative tiles 9e-16 (module docstring; test bound 1e-13); each term at a fixed density against five-point differences of that term within 1e-9 Ha/bohr, for a full-rank and a truncated metric projector and for a +q/-q channel pair on (3,1,1); the assembled gradient against five-point differences of the converged SCF energy within 1e-8 Ha/bohr (step 2e-3 bohr) on (1,1,1) and (2,1,1) with the checks above at 1e-10 (energy recomposition), 1e-13, 1e-12, 1e-12 and 1e-9; the front-door forces equal the library gradient within 1e-9 Ha/bohr. The test source is a cheap finite one whose cutoffs are not commensurate with the 6 bohr cell, not an accuracy setting.

χ-AICCM: the finite character mesh

All χ gradients are per primitive cell on the complete unreduced Γ-centred character mesh, with every image moving with its atom.

χ RI-RHF

Energy: Paper 2 eq:energy with the fitted operator of eq:real_cderi.

Without explicit controls (gradient_case="driver-reentry"). The χ ri RHF energy is the energy of run_krhf_periodic_gdf on the character mesh, so _compute_ri_rhf_gradient re-enters that driver with the recorded arguments, restarted from the χ density, and returns its gradient only if the executed fit-source identity is reproduced exactly, the energy agrees within energy_tolerance (1e-9 Ha/cell), the densities within density_tolerance (1e-6) and the forces sum to zero within translation_tolerance (1e-7 Ha/bohr). Measured against five-point differences at 5e-3 bohr: 1.2e-11 Ha/bohr (He2) to 2.7e-10 Ha/bohr (H2), the H2 value being the stencil error (2.7e-11 at half the step).

With ChiCoulombControls (gradient_case="explicit-controls"). The driver refuses a gradient for this finite source, so it is assembled term by term on the χ state (_compute_controls_rhf_gradient):

\[E = E_{nn} + \sum_k w_k {\rm Re\,Tr}[D(T + V)] + E_J + E_K + E_{x0},\]

Term

Executed definition

Derivative

T

AO pairs within the one-electron cutoff, Bloch summed

_compute_kinetic_gradient_multik

V

explicit Ewald sum: erfc images within the nuclear cutoff of each pair midpoint, executed reciprocal vectors, gauge constant times S

_compute_v_ne_gradient_multik with the executed alpha, pairs and vectors

E_nn

Ewald sum with the same controls

ewald_nuclear_repulsion_gradient

E_J

\(\tfrac12 v^H H v\) at q = 0, zero mode omitted, retained modes

_compute_j_gradient_multik_rsgdf

E_K

\(-\tfrac14 \sum_q {\rm Re\,Tr}[G(q)H(q)]\)

_compute_k_gradient_multik_rsgdf

E_x0

\(-\tfrac14 \xi \sum_k w_k {\rm Re\,Tr}[DSDS]\)

_compute_exxdiv_w_gradient_multik

W

\(W = DFD/2\) with F rebuilt from D

_compute_overlap_w_gradient_multik

Per-run checks (_prepare_controls_gradient_state): rebuilt S(k), Hcore(k), F(k) within operator_tolerance (1e-9); cell lists, reciprocal vectors and retained modes equal to the record and every fit factor reproduced bit for bit; energy recomposed from the terms within energy_tolerance (1e-9 Ha/cell); \(\max|FDS - SDF|\) within stationarity_tolerance (1e-7); translation within 1e-7 Ha/bohr; nuclear_source_screen_residual_ha reported (the value drops erfc images below 1e-16 Ha per element that the derivative keeps). Measured: 1.7e-11 to 2.7e-10 Ha/bohr on H2 and He2 cells, including reduced metric rank (tests/test_chi_controls_rhf_gradient.py, test bound 1e-8). _controls_bilinear_gradient_components is the general-matrix form of this assembly, the analogue of the Γ bilinear functional, used by the χ correlated gradients.

χ RI-MP2

Energy: \(E_{\rm RHF} + N^{-3} \sum \tilde t\,(ia|jb)\) per cell (evaluate_same_source_mp2) on the explicit-controls reference. The Lagrangian is solved in the exact real finite-torus form of the χ state (Paper 2 eq:real_cderi, eq:real_eri_identity): _TorusTransform folds S, h, F to the N-cell torus, aiccm2026dev_b_lpq_to_real_supercell transforms the retained factors to real torus factors, the real canonical orbitals are the eigenvectors of the folded Fock matrix, and _real_torus_lagrangian is the molecular MP2 Lagrangian with the seam in the response. The densities are transformed back to the characters and differentiated by _controls_bilinear_gradient_components with the three-index term _ThreeIndexDensityTerm (the same algebra as the Γ _ThreeIndexFitTerm).

Per-run checks: all explicit-controls reference checks; real-torus transforms without imaginary part or symmetry defect above _REAL_TORUS_TOLERANCE (1e-9); real-torus orbital energies and Fock matrix within operator_tolerance; real-torus correlation energy and the functional on the differentiated raw source within correlation_energy_tolerance (1e-10 Ha/cell); Brillouin, canonical occupied, invariance, core-active and Z-vector residuals within stationarity_tolerance; frozen bands separated by _CORE_GAP (1e-6 Ha) over the mesh. Since 50f9951e (#601) the multi-k GDF drivers return the last-update orbitals with Rayleigh-quotient energies, so the reference orbitals are canonical only to about 2e-7; the two correlation-energy re-evaluation residuals (correlation_energy_residual_ha, fit_functional_energy_residual_ha) went from 5e-17 to 6.6e-13 Ha/cell on the largest test fixture. The gate stays 1e-10, and the test bounds on both were moved from 1e-13 to 1e-11 (be84ef53). Measured (five-point, 5e-3 bohr, tests/test_chi_mp2_gradient.py): 2.0e-11 to 2.7e-10 Ha/bohr, correlation part 4.3e-12 or better.

χ CCSD and CCSD(T)

Energy: χ spin-orbital CCSD and the Hermitian spin-orbital triples correction (evaluate_same_source_cc, Paper 2 eq:ccsd_ansatz), which are the closed-shell CCSD and (T) energies of the real torus divided by N; both are recomputed per run. The Lagrangian is that of the molecular RI-CCSD rung on the torus (_cc_densities, _real_torus_cc_lagrangian). The triples correction is differentiated in its orbital-invariant form \(E_T = \tfrac13 L \cdot \hat D(f)^{-1} R\), where \(\hat D(f)\) applies \(f_{oo}\) to each occupied and \(-f_{vv}\) to each virtual index of the numerator tensors L, R (_triples_numerators). With \(x = L/\Delta\), \(y = R/\Delta\),

\[\frac{\partial E_T}{\partial f_{il}} = -\tfrac13 \sum x_{i\cdots}\, y_{l\cdots}, \qquad \frac{\partial E_T}{\partial f_{ad}} = \tfrac13 \sum x_{\cdots a}\, y_{\cdots d},\]

summed over the three index positions (_triples_fock_density). This is a full occupied-occupied and virtual-virtual density: its diagonal is \(\partial E_T/\partial \epsilon_p\) (checked against the canonical derivatives to 1e-10) and its off-diagonal elements are the multipliers of \(f_{ij} = 0\) and \(f_{ab} = 0\), defined also for degenerate pairs. The whole functional is then invariant in both blocks and the antisymmetry of X there is a measured check. Only the Z-vector and the core-active closed form remain. The matched-eri zero mode adds \(\xi\,\delta_{pq}\delta_{rs}\) to the integrals; in an orthonormal basis its explicit overlap derivative and its orbital derivative cancel and it adds a symmetric matrix to X, so it enters the amplitudes and the energy checks only.

Per-run checks: as for χ MP2, plus CCSD and triples energies on the torus against the χ values, densities against the correlation energy, CCSD and Lambda residuals within amplitude_tolerance (1e-11). Measured (tests/test_chi_cc_gradient.py): 1.9e-11 to 2.8e-10 Ha/bohr for CCSD and CCSD(T), correlation part 3.1e-11, triples part 2.8e-12 for triples gradients up to 4.7e-6 Ha/bohr; without the off-diagonal triples densities the gradient is wrong by up to 5e-7 Ha/bohr and the invariance check refuses it.

χ front-door forces and relaxation

run_periodic_job(method="aiccm", variant="chi", ...) reaches the χ gradients above through chi/optimize.py: chi_gradient=True returns the analytic gradient of the energy the single point reports, and optimize=True (optimize_cell=False) relaxes the unit-cell atoms in the fixed cell on that energy surface. The surfaces are exactly the cases differentiated:

Surface

Energy and gradient

Entry

chi-ri-rhf/reentry

χ RI-RHF without explicit controls; forces only

compute_aiccm2026dev_b_gradient

chi-ri-rhf/explicit-controls

χ RI-RHF on the classic physical-pair source

compute_aiccm2026dev_b_gradient

chi-ri-mp2/explicit-controls

canonical χ RI-MP2 on that reference

compute_aiccm2026dev_b_mp2_gradient

chi-ri-ccsd/explicit-controls, chi-ri-ccsd(t)/explicit-controls

canonical CCSD, CCSD(T)

compute_aiccm2026dev_b_cc_gradient

Every other request fails before the SCF (require_chi_derivative_request); optimisation needs the explicit controls and tight SCF thresholds. Each step is the front-door pipeline at that geometry, so the value minimised is the front-door energy and the gradient is its analytic gradient. The step control is that of the real-Γ fixed-cell optimisers (L-BFGS-B on the fractional coordinates, the Cartesian \(\max|dE/dR|\) gate as the verdict, no Γ-CCM code imported). At the start and final geometries the optimiser’s energy is compared with an independent front-door evaluation within CHI_OPTIMIZE_ENERGY_IDENTITY_TOL (1e-10 Ha/cell), and at the final geometry a five-point difference along the largest remaining component must agree with the analytic one within fd_tol (step CHI_OPTIMIZE_FD_STEP 5e-3 bohr, bound CHI_OPTIMIZE_FD_TOL 1e-6 Ha/bohr).

Interim selection-change policy (#1139). The explicit source selects by sharp cutoffs, so the gradient is exact while the selection digest is unchanged (frozen selections). Until the maintainer decides, the optimisation continues with the re-decided selection, records every change (step index, digests before and after, energies at both geometries, the energy change of the step; the energy at the new geometry under the old selection is not evaluated, because the library has no frozen-selection energy), reports the count, and fails the run if a change falls in the final convergence window: the last selection_window (CHI_OPTIMIZE_SELECTION_WINDOW, 2) accepted steps, the final geometry and the finite-difference stencil must lie on one selection.

Evidence (tests/test_chi_front_door_gradients.py): the front-door forces equal the library gradient of the returned result within the 1e-12 Ha/bohr acceptance, measured at most 4.4e-16, on the four explicit-controls surfaces (the re-entry surface has its own test); relaxations of H2 along z in a 6.5 bohr cube from R = 1.50 bohr, (2,1,1), with no selection change: RHF (STO-3G) 4 steps, final \(\max|dE/dR|\) 1.4e-7 Ha/bohr, five-point check 3.0e-10, bond 1.42205 bohr; RI-MP2 (STO-3G) 3 steps, 5.4e-7, 2.8e-10, bond 1.44266 bohr; CCSD(T) (6-31G) 3 steps, 8.1e-7, 2.0e-10, bond 1.53251 bohr; energy identities 2.9e-15 or better. In the 6 bohr cube of the force tests the one-electron cell set changes at R = 1.487 bohr, which is where the RI-MP2 optimum sits, so the relaxation fixture uses the larger cube (1.36 to 1.56 bohr stay on one selection by a digest scan recorded in the test).

Screening, truncation thresholds and frozen selections

A local or screened energy contains integer decisions that are piecewise constant in the geometry. Every gradient here differentiates the frozen-selection energy: the decisions are taken once, recorded, and held fixed while orbitals, spaces and integrals follow the geometry. It is the exact derivative of that energy, and at a geometry where no decision sits at its threshold it equals the derivative of the energy whose decisions are made afresh. It carries no information about the steps where a decision changes, which no gradient describes.

Method

Frozen decisions

Record

Proximity to a change

molecular local MP2

pairs, screened pairs, pair and orbital domains, PAO counts, PNO counts, Boys solution followed

LocalMP2Selection

min_pao_gap, min_pno_gap

molecular union-PNO

PNO count per pair, union dimension, localiser solution followed (all pairs always)

UnionPNOSelection (n_pno, n_union)

min_pno_gap, min_union_gap, pair_occupations, union_eigenvalues

Γ DLPNO-MP2

gauge, frozen count, pairs, Mulliken domains, PAO and PNO counts

CCMLocalMP2Selection (same_decisions)

min_pao_gap, min_pno_gap

every Γ and χ fit

retained metric modes per q

cache keep_mask

refused on the threshold or at a retained/dropped degeneracy

χ explicit controls

AO pairs within the one-electron and pair cutoffs, nuclear images per pair midpoint, real and reciprocal Ewald sets, reciprocal vectors and retained modes per q

frozen_selection_sha256, aiccm2026dev_b_gradient_frozen_selections

the digest of a displaced geometry differs

The displaced geometries of the local energies follow the recorded orbitals: the localiser starts from the reference orbitals projected onto the displaced occupied space (localisation_reference, gauge_reference), so pair labels keep their meaning. The finite-difference tests verify that the counts decided afresh over the stencil equal the frozen ones. The one measured crossing is χ: on a 6 bohr H2/STO-3G cell on (3,1,1) with nuclear_real_cutoff_bohr=8.3 one nuclear image lies 8e-4 bohr outside its sphere, a 5e-3 bohr displacement changes the digest, and the five-point difference across it deviates from the analytic gradient by 1.4e-6 Ha/bohr (2.8e-6 at half the step: it does not converge with the step). These deviations are quoted from a commit record and the χ user guide; no test pins them: the test records only that the digest changes.

Properties of the energy definitions exposed by the gradients

  • Foster-Boys on the torus. The Boys functional of the Γ local drivers uses the dipole integrals of the supercell basis without images, which are not a periodic operator. A rigid translation changes them by the translation times an overlap that is not the torus overlap, so a truncated energy depends on where the atoms sit: its exact gradient carried a net force of 3e-6 to 7e-6 Ha/bohr on H2-class cells. refuse_boys_on_torus refuses localize="boys" in ccm_dlpno_mp2, ccm_dlpno_ccsd and run_ccm_dlpno_mp2_gradient; the Boys branches that the Γ gradient module once carried for reference have been removed. Pipek-Mezey with torus-overlap populations has no position operator.

  • The union space keeps small eigenvalues at full weight. Both the molecular union and _union_pno_virtual_space keep every eigenvector above pno_lindep with full weight. A kept eigenvalue far below one is a direction fixed by small differences between PNOs of different pairs, and the frozen-selection energy can then change rapidly with geometry: 0.47 Ha/bohr was measured for water in def2-SVP with canonical pair orbitals at a smallest kept eigenvalue of 4e-6, where finite differences reach the analytic value only below a 1e-4 bohr step. This is a property of the energy definition; whether to change it is a maintainer decision that is pending.

  • Defaults. The Γ DLPNO-MP2 default gauge is canonical (localize="none"); ccm_dlpno_ccsd and the molecular union default to Pipek-Mezey. With canonical orbitals and full domains the Γ DLPNO-MP2 energy is canonical RI-MP2 at any tcut_pno.

  • Two DLPNO-CCSD(T) approximations. The Γ ccm_dlpno_ccsd merges all PNOs into one semicanonical union space and solves canonical CCSD(T) once there; the χ DLPNO routes run a separate PNO space per pair (Paper 2 eq:pno_density, eq:dlpno_r2, eq:tno_domain). Their thresholds are not interchangeable, and their PNO densities differ (Γ and the union use the legacy density; run_chi_local_mp2 uses the spin-adapted "mp2" density). Only the molecular union-PNO energy has a gradient.

  • Short smoothness scale of weak pairs. On a (2,1,1) torus the weak pair of an orbital and its own translate has close occupation numbers that change by a factor of two over 0.04 bohr; a frozen count that separates two of them is near a crossing, and finite differences need a small step.

What Lean covers and what it does not

The Lean development proves energy-side statements at fixed geometry and fixed fit. It contains no statement about nuclear derivatives.

Proved, and used by the gradients as the justification of a structure:

  • Density derivative of the fitted torus RHF energy: per_cell_directional_derivative (\(dE_{\rm cell}(D + tX)/dt = \langle X, F(D)\rangle / N_c\), HasDerivAt), with fitted_per_cell_derivative supplying the ERI symmetries of the fit, and the seam bookkeeping seam_energy_split, corrected_fock, code_sign_translation and total_half_fock (proof bridge). This is the variationality the SCF gradients rely on (no orbital response) and the identification of the Fock response G used in every Z-vector operator.

  • Stationarity: bvk_quadratic_fock, bvk_orbital_stationary_iff, bvk_fock_stationary_iff and bvk_rhf_fock_iff (orbital stationarity is \(FDS - SDF = 0\) for the operator that belongs to the energy), behind the commutator gates.

  • Representation transport: bvk_stationary and bvk_rhf_variational (stationary points and minima correspond between the cell and mode representations), behind the use of the Bloch control for the real-Γ state.

  • Energy-side definitions the correlated gradients differentiate: the PAO and PNO projector algebra of the Γ local energies (gamma_q_idempotent, gamma_whiten_metric, gamma_selected_projector, gamma_zero_projector, gamma_finish_integral; Γ PAO contract), the χ character-to-cell integral identities (chi_fitted_integral, chi_cell_eri, chi_real_cell; χ MP2), and the seam shift of the occupied spectrum and MP2 denominators (seam spectrum). The proved pair-density bounds (chi_pair_gram and following) are for the spin-adapted density; the Γ and union energies use the legacy density, which they do not cover.

Resting on numerical verification only: every derivative with respect to a nuclear coordinate. That includes the one-electron, Ewald and integral derivative kernels, the three-centre and metric derivatives of the fit, the truncated-inverse response, the seam overlap derivative, the Z-vector and canonical multipliers, Lambda and the reverse-sweep densities, the orbital-invariant triples density, the PAO, PNO and union eigenvector responses, the localisation multipliers and the dipole-derivative helper basis, the Bloch transforms of non-invariant weights, the seeded control and the frozen-selection digest. The finite-difference records above are their evidence.

Refusals and open work

Every gradient raises rather than substitute another energy’s derivative. The common refusals: a reference not stationary for the fit, non-canonical orbitals where canonical ones are required, an unseparated frozen core, degenerate orbitals whose rotation the energy distinguishes, a non-unique localisation, coincident kept and dropped eigenvalues, a metric mode on the threshold, a failed same-Hamiltonian identity, and every scope listed under what is not covered.

Issue

Open work

#1105

real-Γ SCF gradient assembled on the real-Γ state without the second (Bloch) SCF; today the seeded control still runs

#1106

χ UHF, RKS, UKS SCF gradients and the four_center backend

#1107

front-door exposure of the Γ DLPNO-MP2 and RI-UMP2 gradients; unrestricted DLPNO-MP2

#1108

χ per-pair and TNO CCSD(T), UCCSD(T)

#1136

the Γ SCF loops on the shared eigensolver interface

#1137

symmetry-reduced meshes in the gradient context and symmetrised forces

#1138

open-shell correlated gradients on both lines

#1139

front-door gradients and optimisation on the Γ surfaces other than SCF and RI-MP2; the maintainer decision on a selection that changes between optimisation steps (the χ front door applies an interim policy)

#1140

validation through the job queue against external references (CRYSTAL, CRYSCOR, ORCA molecular limits) on LiH-class cells

Provenance: written against the sources on main at 7d8cee15; the rungs were added in e8f6d2f0, e982d46c, 3c37e8b7, a9bd6cf6, 7c2fde2d, 40e49255, 3de4d2b0, 68e76b89, ca531554, 98f116ee, b6ac3f42, badb0f12, da2af19f and 067eecab, and the Foster-Boys refusal in 2eb72a59.