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 |
|
|
molecular |
same-fit RI-UMP2 |
|
|
molecular |
local MP2, frozen selection |
|
|
molecular |
same-fit RI-CCSD, RI-CCSD(T) |
|
|
molecular |
union-PNO CCSD(T), frozen selection |
|
|
Γ real-gamma |
RHF, UHF, RKS, UKS |
|
|
Γ real-gamma |
RI-MP2 |
|
|
Γ real-gamma |
RI-UMP2 |
|
|
Γ real-gamma |
DLPNO-MP2, frozen selection |
|
|
Γ real-gamma |
RI-CCSD, RI-CCSD(T) |
|
|
Γ real-gamma |
union-PNO CCSD, CCSD(T), frozen selection |
|
|
Γ real-gamma, MANTA sources |
RHF |
|
|
χ |
RI-RHF without explicit controls |
|
|
χ |
RI-RHF with |
|
|
χ |
RI-MP2 on the explicit-controls reference |
|
|
χ |
CCSD, CCSD(T) on the same reference |
|
|
χ |
front-door forces and fixed-cell relaxation of the above |
|
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):
The fitted closed-shell Fock matrix and its two-electron response are
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
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),
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,
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 withz.Same-class pairs fixed by a canonical condition. For two orbitals of the same class the two-electron part of
Xis 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 ofz, 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 tostationarity_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
Xthere is a measured property of the input (invariance_residual) and is refused abovestationarity_tol.Degenerate pairs on a torus. A torus has degenerate pairs by symmetry (characters
kand-k), where the quotient form above is0/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 abovelocalisation_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
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}\), |
|
|
|
integral derivatives |
|
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,
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 |
|
PNO eigenvector response through the pair density and the amplitude equation \(T = K/\Delta\) |
|
domain response: inside the span \(-\tfrac12 V (V^T G) V^T\) on |
|
dipole estimate of screened pairs |
|
Boys multipliers, core-active, Z-vector, |
|
dipole-integral derivative of the Boys term and of the estimate |
|
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 |
|
Lambda with the (T) source |
|
|
|
(T) energy and its derivatives in |
|
orbital conditions and integral derivatives |
|
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
Abecomes the weight \(\sum_{r,x} |x\rangle\langle x|W|r\rangle\langle r| / (a_r - a_x) + {\rm h.c.}\) onA(_projector_weight), applied first toMand 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 firstfrozen_corelocalised 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 |
|
fitted Coulomb |
|
fitted exchange, times |
|
exchange |
|
composition (RHF, UHF; the KS assemblies add the XC term) |
|
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)
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 |
|
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\) |
|
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)]\) |
|
non-separable correlated terms |
extra |
metric response of the truncated inverse |
|
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, |
|
Bloch control seeded from the direct state, context |
|
real supercell matrices to the mesh |
|
Bloch orbital components \(C_p(k)\) |
|
separable and non-separable derivatives |
|
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 |
|
UHF reference, spin-sector check |
|
Bloch control seeded from the direct state |
|
separable derivatives |
|
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 |
|
energy and selection |
|
explicit weights, PNO and domain response |
|
gauge multipliers, Z-vector, AO weights |
|
integral derivatives |
|
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 |
|
CCSD, Lambda, reverse sweep in the union space |
|
union-space rotations, retained-discarded response, localisation multipliers |
|
orbital Lagrangian with the torus Fock response |
|
two-particle density to the fit through all orbital pairs |
|
integral derivatives |
|
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
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 |
|
nuclear repulsion |
|
overlap, kinetic, Ewald nuclear attraction |
|
fitted Coulomb and exchange at fixed density: SR image tiles, reciprocal part, metric, fixed positive eigenprojector of each kept channel |
|
assembled forces, energy recomposition |
|
forces of a front-door run |
|
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):
Term |
Executed definition |
Derivative |
|---|---|---|
|
AO pairs within the one-electron cutoff, Bloch summed |
|
|
explicit Ewald sum: erfc images within the nuclear cutoff of each pair midpoint, executed reciprocal vectors, gauge constant times |
|
|
Ewald sum with the same controls |
|
|
\(\tfrac12 v^H H v\) at |
|
|
\(-\tfrac14 \sum_q {\rm Re\,Tr}[G(q)H(q)]\) |
|
|
\(-\tfrac14 \xi \sum_k w_k {\rm Re\,Tr}[DSDS]\) |
|
|
\(W = DFD/2\) with |
|
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\),
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 |
|---|---|---|
|
χ RI-RHF without explicit controls; forces only |
|
|
χ RI-RHF on the classic physical-pair source |
|
|
canonical χ RI-MP2 on that reference |
|
|
canonical CCSD, CCSD(T) |
|
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 |
|
|
molecular union-PNO |
PNO count per pair, union dimension, localiser solution followed (all pairs always) |
|
|
Γ DLPNO-MP2 |
gauge, frozen count, pairs, Mulliken domains, PAO and PNO counts |
|
|
every Γ and χ fit |
retained metric modes per |
cache |
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 |
|
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_torusrefuseslocalize="boys"inccm_dlpno_mp2,ccm_dlpno_ccsdandrun_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_spacekeep every eigenvector abovepno_lindepwith 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_ccsdand the molecular union default to Pipek-Mezey. With canonical orbitals and full domains the Γ DLPNO-MP2 energy is canonical RI-MP2 at anytcut_pno.Two DLPNO-CCSD(T) approximations. The Γ
ccm_dlpno_ccsdmerges 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 2eq: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_mp2uses 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), withfitted_per_cell_derivativesupplying the ERI symmetries of the fit, and the seam bookkeepingseam_energy_split,corrected_fock,code_sign_translationandtotal_half_fock(proof bridge). This is the variationality the SCF gradients rely on (no orbital response) and the identification of the Fock responseGused in every Z-vector operator.Stationarity:
bvk_quadratic_fock,bvk_orbital_stationary_iff,bvk_fock_stationary_iffandbvk_rhf_fock_iff(orbital stationarity is \(FDS - SDF = 0\) for the operator that belongs to the energy), behind the commutator gates.Representation transport:
bvk_stationaryandbvk_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_gramand 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 |
#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.