[kshitij-05]

• Implement 2-electron 4-center relativistic integrals with restricted kinetic balance condition (RKB).

  • (LL|SS)
  • (SS|SS)
  • (LS|LS) [gaunt]

• Implement 2e 3-center relativistic integrals with RKB.

  • (X|SS)
  • (X|LS) [gaunt]

  Also adds σpeμσp operator for small component dipole moment integrals

[loriab]

I just noticed this and saw some tweaks to propose. You might want to add the new class to INSTALL.md, too.

[kshitij-05]

Audit of the branch before pushing: two review passes (branch vs master, then the four commits that landed today), each finding verified against the code. What was fixed, and what the new commits had already covered.

Fixed in this push

• edf8161 engine.h / engine.impl.h
  • The new std::invalid_argument for Cartesian fitting shells with LIBINT2_ERI3_PURE_SH (a287bd7) now applies to derivative order 0 only. The generator marks the fitting shell pure_sh only for deriv_level == 0 (build_libint.cc 1671/1716), so derivative kernels are Cartesian-complete and were being rejected. Same condition on the Debug-only ERI2 asserts (plus "in bra" → "in ket" in the ket message).
  • BraKet::xx_xs with deriv_order > 0 is rejected at initialize(); before, it got as far as a std::logic_error from DerivMapGenerator::instance inside compute2.
  • _initialize() clears buildfnptrs_ before throwing lmax_exceeded, so an Engine that survives the exception throws missing_kernel instead of dispatching a table that does not match primdata_. hard_lmax_ / hard_default_lmax_ are initialized; they were indeterminate for a kernel-less or default-constructed Engine (and copied as such).
• 00042b6 cmake/modules/int_am.cmake
  • The scalar LIBINT2_<class>_MAX_AM branch of both process_integrals_class* macros still read the bare ${class}_MAX_AM after e22dfdd renamed it to LIBINT_${class}_MAX_AM. Effects: _candidate_<class>_d<d> empty, so Libint2_ERI_COMPONENTS under-reported (find_package(Libint2 COMPONENTS ...)); the "Enabling integrals class X to max AM" line printed a blank; the AM-range validation was dead. Pre-existing on master, hit by every lane that passes a scalar max AM.
  • RKB classes take part in _glob_classes_derivs; _rkb_eri3_impure_sh renamed after the PURE_SH removal.
• 2a5178c build_libint.cc: LIBINT2_SUPPORT_RKB_ERI3 / LIBINT2_DERIV_RKB_ERI3_ORDER feature macros, mirroring RKB_ERI.
• af3d628 comp_deriv_gauss_v2.h: the generated-function label includes the differentiation direction. directional() is always true, so a shell with derivative quanta in two directions (2nd derivatives) is a valid target for two instances whose children and a[dir] coefficients differ, yet the RRStack deduplicated them by label and kept the first one; correctness relied on the tactic tie-break selecting the same instance. Inherited from CR_DerivGauss. Also removed a dead if (np == 1) return true;.
• 54afe4d / 9c02f59 (earlier today): fold CRs select the sign pattern from the component index and check the child count; CR_σpCoulombσp_ → CR_opCoulombop_, since the Unicode label had leaked into generated symbols and filenames.

Already covered by f3d21c1 / 884e8d7: per-operator swap branches (now traits), progress double count and the stderr spinner, print_config, the stale canonical-form comment, and both RKB_ERI3_PURE_SH findings.

Verified: light build, all max AM 2, ONEBODY/RKB_ERI/RKB_ERI3 at derivative 0 and ERI/ERI3 at derivative 1: compiler tests pass, export passes, the configure log now prints the max AM values; the library build and check-libint2 on this exact tree were still running when this was posted and CI runs the full set. Earlier today, before the engine/cmake fixes, the same pipeline at derivative 0 passed 12/13 ctest entries (the known hf++ validate.py SyntaxError) with the unit suite at 3,084,450 assertions in 41 cases, including the new solid-harmonics case.

Update (build finished): on the pushed tree (af3d628f), same configuration, check-libint2 passes 13/13; unit suite 21,019,631 assertions in 41 cases; "eri geometric derivatives vs finite differences" passes on the new DerivGaussV2 labels. libint2/hf++/run passes as well: its long-standing SyntaxError in validate.py came from the empty LIBINT_ERI_MAX_AM that the int_am.cmake fix (00042b6) restores.

[kshitij-05]

Windows CI, two separate failures, both bisected by job history to commits of today (neither from the audit fixes):

1. Export • windows-mingw-CLANG64, "RKB Coulomb integrals", since f3d21c1. Root cause found and fixed in 7d8b6ad: the component remap after a bra-ket swap copied targets_ (const auto tmp = targets_;), a std::vector on ext_stack_allocator whose elements live in primdata_[0].targets. The copy inherits the allocator state; on libc++ the copy's storage overlapped the original's, so the remap read entries it had already overwritten and every opop_coulomb_opop quartet that needs a bra-ket swap came out scrambled. Evidence from a diagnostic branch run: on mingw the canonical kernel (p s|d s) is bit-identical to Linux, while the engine-permuted (s d|s p) disagrees with its transpose by 0.042. The fix copies the pointers into a local std::array (as before f3d21c1) and makes ext_stack_allocator::select_on_container_copy_construction() return a heap-only allocator so a container copy can never alias again.

2. Export • windows-clang-cl, five 1-body absolute-reference tests (electrostatic potential, erf, W, σpeμσp, python correctness), since a287bd7. The wrong values are exactly "correct pure value + 1.0 × the Cartesian xx element", i.e. the d-shell solid-harmonics m=0 row behaves as if its xx coefficient were +0.5 instead of −0.5. The tarball consumed by that lane is byte-identical in generated code to the last passing run; ASan/UBSan are clean on the path; and on the diagnostic branch, which only appends a TEST_CASE to test-1body.cc, all 42 cases pass on clang-cl with every printed value correct (parity(-1) = -1, m=0 row {−0.5, −0.5, 1}). So this one is layout-dependent (heap or code layout), not a logic error visible in the source; the first test of the run is the one failing, so test-order contamination is excluded. I could not identify the mechanism from macOS. If it comes back after 7d8b6ad (which changes the library layout), it needs a Windows debugger or a MSan-like build.

[kshitij-05]

clang-cl root cause found and fixed in 307d3dd. SolidHarmonicsCoefficients::coeff() called an anonymous-namespace parity unqualified. clang-cl defaults to MSVC-style delayed template parsing, which binds unqualified names in template bodies at instantiation. test-2body.cc includes test_eri/eri.h, which declares libint2::parity with if (a % 2 == 1) return -1; (so parity(-1) == +1), and since a287bd7 that TU instantiates the solid-harmonics transforms; its copy of coeff<double> wins the COMDAT for the whole test executable. The only l ≤ 2 coefficient that depends on parity(-1) is the xx entry of the d-shell m=0 row, hence exactly "+0.5 instead of −0.5" and exactly the pure-shell 1-body tests. Reproduced locally with clang++ -fdelayed-template-parsing (gives +0.5; without the flag −0.5; with the fix −0.5 in both modes). Fix: parity moved to libint2::solidharmonics::detail, called qualified, correct for negative arguments; libint2::parity in test_eri/eri.h fixed for negative odd arguments; a one-line guard in test-2body.cc. The diagnostic branch is deleted.

[evaleev]

@kshitij-05 I merged master twice (#445/#446, then #449) and ran another adversarial review of the branch. Nothing blocks the merge. Three bugs are fixed in the commits I just pushed. Three warnings are left for you, because they depend on conventions you chose.

The two items from the previous round are fixed:

• the sign patterns in the composite RRs now switch on the component index;
• the comment about canonicalization is gone.

Merges (b0802c7, cfbf6e7)

• The four RKB scalar max/opt AM macros (LIBINT_RKB_ERI{,3}_{MAX,OPT}_AM) now follow master's #define/#undef pattern from LIBINT2_OPT_AM=0 breaks the build: #cmakedefine drops zero-valued LIBINT_*_AM macros #445/config.h: preserve a value of 0 for the scalar LIBINT_*_MAX_AM/OPT_AM macros #446, and CMakeLists.txt maps them to -1 when unset, like the other classes. Before this, a value of 0 was silently dropped (e.g. LIBINT2_RKB_ERI_OPT_AM=0).
• With Declare RR target pointers LIBINT2_RESTRICT #449 merged, the generator's target/child overlap check passes for the RKB and DerivGaussV2 kernels.
• Verified locally with MAX_AM=2, OPT_AM=0, RKB_ERI_MAX_AM=1, RKB_ERI3_MAX_AM=2 and ERI deriv 1:
  • the compiler, the library and check-libint2compiler build;
  • all 27 cases in test-1body and test-2body pass.

Fixed

• 5a3755c: set() changes oper_/braket_ and then calls initialize(). When initialize() rejected the change (RKB with deriv > 0, or xx_xs with deriv > 0), the Engine kept the previous kernel table, and compute() dispatched it.
  • Example: Engine(coulomb, n, L, 1), then set(coulomb_opop) throws, and a later compute() runs the eri1 kernels as coulomb_opop, which also overruns the Boys table.
  • buildfnptrs_ is now cleared before the throw, as for lmax_exceeded, so compute() throws missing_kernel instead.
  • There is a new test, and it fails without the fix.
• 5a3755c: the "Coulombσpσp 3-center xx_xs alias" test built its Engines with the default 4-center braket. That throws lmax_exceeded whenever LIBINT2_RKB_ERI_MAX_AM is less than the 3-center AM. The test now passes the braket to the constructor.
• d20e092: libint-compiler-eri-test-generate failed to link with an undefined g_progress. It is now defined once, as an inline variable in buildtest.h.

Warnings: please take a look

1. Sign convention of coulomb_op.
   • CR_11_Coulombσp_11 takes the derivative with respect to the center of d (d_k.deriv().inc(k)), i.e. ∂/∂D = −∂/∂r.
   • Its comment says "the -i factor ... applied by the caller". But σ·p ν = −i σ·∇_r ν = +i σ·∂_D ν, so a caller who follows the comment gets every coulomb_op integral with the wrong sign.
   • This is the only RKB operator with an odd number of derivatives; for the other three the sign cancels.
   • The unit test uses the same center-derivative convention, so it cannot catch this.
   • Suggested fixes:
     • add a prefactor column to the \page rkb_operators table in engine.h (the other operators also carry an implicit −1 and/or i);
     • fix the comment;
     • change "d/dr" to "d/dA" in the comment of comp_deriv_gauss_v2.h.
2. Each expansion is written twice. In comp_11_Coulombσpσp_11.h, comp_11_σpσpCoulombσpσp_11.h and comp_11_σpCoulombσp_11.h, the order of the make_child calls and the sign strings in generate_code() are maintained separately.
   • The child-count guard catches deduplication, but not a reordering. Swapping two mc(...) lines leaves the count, and expr_, unchanged, while generate_code() emits the wrong sign for every shell set that shares the function.
   • Driving both from one (coefficient, derivative tuple) table per component would make that impossible.
3. AM limits per center are checked only by assert (the xs_xx buildfnidx block in engine.impl.h).
   • _initialize checks lmax_ only against max(hard_lmax_, hard_default_lmax_).
   • Example: build with MAX_AM=2 and RKB_ERI3_MAX_AM=3. In Release, an f AO shell indexes into the wrong kernel (e.g. it returns the (p|ss) kernel's result).
   • The asserts also use <= where < is needed.
   • This is the same on master, but the new RKB_ERI3_MAX_AM knob makes a mismatched configuration much more likely. Suggest throwing lmax_exceeded per center in all builds.

Notes

• set(BraKet) and set_max_l do not rebuild core_eval_pack_. So Engine(..., BraKet::xs_xx) followed by set(BraKet::xx_xx) can need a higher Boys order than the evaluator was built for. This is pre-existing, but the intrinsic derivatives of the RKB operators make it more likely.
• The choice between explicit DerivGaussV2 code and generic code (comp_deriv_gauss_v2.h, max_am_opt()) uses the default task's OPT_AM, not the per-class value. This affects performance only.
• The "lmax_exceeded leaves no kernels" test compiles to nothing unless MAX_AM_3eri > MAX_AM_eri. Using 3coulomb_opop vs coulomb_opop would exercise it in more configurations.
• The xx_xs alias test and the coulomb_op test pick AO shells using the fitting-center limit (LIBINT2_MAX_AM_3coulomb_opop). check_3center correctly uses min(LIBINT2_MAX_AM_default, ...).
• The RKB descriptors use Multiplicative*_Props, so hermitian() returns +1 and HRR would consider them movable. This is harmless today because only the composite RR is in their strategies, but it is a trap if HRR is ever enabled for them.
• Stale or misleading text:
  • "CR_DerivGauss" label prefix and comments in the DerivGaussV2 translational-invariance path;
  • "quaternion_index" for the 16- and 9-component indices;
  • "(a b | op c op d)" in comp_11_σpCoulombσp_11.h;
  • "the operator acts on b and/or d" in engine.h, which contradicts the table;
  • the \page block now separates the /// doc of rank() from the function.
• opemuop renumbers every 2-body Operator. CHANGES says so, and the next release should also bump the SONAME.

This review was agent-generated and human-reviewed.

[kshitij-05]

Follow-up to the review of 2026-10-25, in 40e9389 (tests), 9fba2b0 (engine) and 046a313 (compiler).

CI of 5a3755c: two failures, both in tests

• Debug lanes: "lmax_exceeded leaves no kernels" aborted on the argument-count assert of compute(). set(BraKet::xx_xx) changes the braket before initialize() throws, so the Engine is left as a kernel-less 4-center Engine, and the 3-shell compute(fit, s, s) that followed is an argument-count error (Release reached missing_kernel by accident). The test now checks the braket instead, and has a coulomb_opop/3coulomb_opop section (live when LIBINT2_RKB_ERI3_MAX_AM > LIBINT2_RKB_ERI_MAX_AM), as suggested.
• macOS Release shared=ON, the lane that aceb113 reconfigured to LIBINT2_MAX_AM="2;2;1" with ERI derivatives up to 2: the Fortran ERI test and example and hf++ evaluated 2nd-derivative integrals over a d shell while the deriv-2 kernels stop at p (segfault through the C/Fortran kernel table; lmax_exceeded from hf++'s Hessian engine). The Fortran test and example clamp each derivative order to LIBINT2_MAX_AM_eri<d>; hf++ computes the 2-body forces/Hessian (and the derivative 2-center checks) only when the kernels support the basis and prints a "skipped" line otherwise, which the validator accepts.

Warnings

1. Sign convention of coulomb_op: the comment was wrong, the kernels are unchanged. The \page rkb_operators now states the derivative convention (all kernels differentiate with respect to the centers, so σ·p contributes +i on b, d and −i on the conjugated a, c) and has a prefactor column: coulomb_opop and opop_coulomb_opop need nothing beyond the folded spin block q₀ + i σ·q, coulomb_op needs +i, op_coulomb_op needs −1. The "acts on b and/or d" sentence became a column; comp_deriv_gauss_v2.h says d/dA.
2. Each expansion written twice: every fold relation now has one fold_terms(component) table, (coefficient, derivative direction on a, b, c, d) per term; rkb_fold_make_children() creates the children and the symbolic expression from it and rkb_fold_generate_code_from_terms() emits the element-wise expression from it. The Pauli components of (σ·∇)(σ·∇') live in one table (rkb_fold_pair_terms), the 16-component relation is its product with the −1 of i² on the cross × cross block, the 9 irreps of op_coulomb_op are listed. Diff of the 32 generated fold kernels before/after: 17 byte-identical (all of coulomb_op, coulomb_opop, op_coulomb_op, and SS of opop_coulomb_opop); the other 15 differ only in the spacing of a leading minus and, for the dot × cross components, in the order of the six terms (bra pair outer, ket pair inner).
3. Per-center AM limits: compute2() now throws lmax_exceeded (with the task label) in all builds when a shell exceeds the limit of its center, comparing with <.

Notes

• set(BraKet) and set_max_l() rebuild core_eval_pack_.
• DerivGaussV2's explicit-vs-generic choice uses the OPT_AM of the current task.
• The 16-component descriptor's quaternion_index() is now component_index(); the RKB descriptors carry a note on the hermitian()/HRR trap; the translational-invariance instances of DerivGaussV2 are labeled DerivGaussV2TI... instead of CR_DerivGauss... (CR_DerivGauss labels its own instances that way, and the RRStack deduplicates by label); (a σ·p b | c σ·p d) fixed; the page no longer splits the doc of rank().
• The xx_xs alias and coulomb_op tests limit the AO shells by LIBINT2_MAX_AM.
• SONAME bump for opemuop: noted, yours at release time.

Verification (M2, Apple clang 17, gfortran 14)

• The configuration of the failing lane (MAX_AM=2;2;1, ERI_MAX_AM=2;2;1, ENABLE_ERI=2, ERI3_MAX_AM=3;2, RKB_ERI3_MAX_AM=3, Release compiler, Release shared library with Fortran): check-libint2 17/17, unit 43 cases / 21,128,306 assertions, hf++ validates with the Hessian skipped, Fortran example and test pass.
• The default CI configuration (MAX_AM=2;2, ERI/ERI3 derivative 1, RKB on, Debug, static): check-libint2compiler 2/2, check-libint2 13/13, unit 43 cases / 21,040,446 assertions; "RKB Coulomb integrals" 295,673 and "RKB integrals with solid harmonics shells" 694,742 assertions, unchanged.