Relativistic 2e 3- and 4-center integrals

.github/workflows/cmake.yml

@@ -45,6 +45,15 @@ jobs:
             build_shared_libs: ON
             os: macos-15
             do_fortran: ON
+          # exercise a center-dependent AM table for the 3-center RKB ERIs and
+          # 2nd geometric derivatives of the 4-center ERIs in one lane only
+          - build_type: Release
+            os: macos-15
+            subproject: OFF
+            rkb_eri3_max_am: 3
+            eri_deriv_order: 2
+            max_am: '2;2;1'
+            eri_max_am: '2;2;1'
 
     name: "Repo • ${{ matrix.os }}: ${{ matrix.cxx }} ${{ matrix.build_type }} shared=${{ matrix.build_shared_libs }} fetch=${{ matrix.subproject }}"
     runs-on: ${{ matrix.os }}
@@ -61,11 +70,14 @@ jobs:
         -D BUILD_SHARED_LIBS=${{ matrix.build_shared_libs }}
         -D LIBINT2_BUILD_LIBRARY_AS_SUBPROJECT=${{ matrix.subproject }}
         -D CMAKE_INSTALL_PREFIX=${{github.workspace}}/build/library
-        -D LIBINT2_MAX_AM=2;2
-        -D LIBINT2_ERI_MAX_AM=2;2
+        -D LIBINT2_MAX_AM=${{ matrix.max_am || '2;2' }}
+        -D LIBINT2_ERI_MAX_AM=${{ matrix.eri_max_am || '2;2' }}
         -D LIBINT2_ERI3_MAX_AM=3;2
-        -D LIBINT2_ENABLE_ERI=1
+        -D LIBINT2_ENABLE_ERI=${{ matrix.eri_deriv_order || 1 }}
         -D LIBINT2_ENABLE_ERI3=1
+        -D LIBINT2_ENABLE_RKB_ERI=0
+        -D LIBINT2_ENABLE_RKB_ERI3=0
+        -D LIBINT2_RKB_ERI3_MAX_AM=${{ matrix.rkb_eri3_max_am || 2 }}
         -D LIBINT2_ENABLE_ONEBODY=1
         -D LIBINT2_DISABLE_ONEBODY_PROPERTY_DERIVS=${{ matrix.disable_onebody_property_derivs || 'ON' }}
         -D LIBINT2_MULTIPOLE_MAX_ORDER=2

CHANGES

@@ -4,6 +4,37 @@
 Following is a brief summary of changes made in each release of Libint.
 
 - unreleased:
+  - PR #399: relativistic restricted kinetic balance (RKB) integrals: 2-body Operator::coulomb_opop,
+    Operator::coulomb_op, Operator::opop_coulomb_opop, Operator::op_coulomb_op (enabled by
+    LIBINT2_ENABLE_RKB_ERI and LIBINT2_ENABLE_RKB_ERI3, off by default; no geometric derivatives yet)
+    and 1-body Operator::opemuop. N.B. Operator::opemuop is inserted after the other 1-body
+    operators, hence the numeric values of all 2-body Operator enumerators increase by 1.
+    Engine::compute() now throws Engine::missing_kernel if the library was not configured to
+    compute the requested operator/braket/derivative order (previously the result was undefined),
+    and std::invalid_argument if given a cartesian fitting shell with l > 1 when the library was
+    configured with LIBINT2_ERI3_PURE_SH (previously a Debug-only assert). The Libint compiler
+    now requires C++17; the generated library still requires C++11 only.
+    Other changes that affect all libraries, not just the RKB integrals:
+    - BraKet::xx_xs is now usable for 3-center energies (as the alias of BraKet::xs_xx with the
+      fitting function last); previously Engine::compute() aborted for it.
+    - the geometric-derivative kernels of all 2-body Coulomb integrals (ERI, ERI3, ERI2) are now
+      generated by DerivGaussV2 (comp_deriv_gauss_v2.h), which shares one function between all
+      shell sets with the same differentiated shell, instead of by CR_DerivGauss; the generated
+      code is validated against finite differences for every shell set in the unit tests. With
+      LIBINT2_ENABLE_GENERIC_CODE the generic kernel is used when the differentiated shell is
+      beyond LIBINT2_OPT_AM (previously: when the average AM of the shell set is).
+    - Engine::initialize() no longer asserts (in Debug builds only) that the library includes the
+      braket type; missing kernels are reported by Engine::missing_kernel from compute().
+    - the validation of LIBINT2_<class>_MAX_AM in cmake/modules/int_am.cmake now actually runs
+      (it referred to undefined variables); a value of 0 is accepted, negative values are rejected.
+    - Engine::compute() throws Engine::lmax_exceeded in all builds if a shell exceeds the angular
+      momentum limit of its center (e.g. an AO shell beyond LIBINT2_MAX_AM given to a 3-center Engine
+      whose max_l is within LIBINT2_ERI3_MAX_AM); previously a Debug-only assert, and Release builds
+      dispatched the kernel of another shell set.
+    - Engine::set(BraKet) and Engine::set_max_l() rebuild the core integral evaluator, whose order
+      depends on the rank of the braket and on the maximum angular momentum.
+    - the Fortran ERI test and example and the hartree-fock++ test honor a lower angular momentum
+      limit of the derivative kernels (e.g. LIBINT2_MAX_AM="2;2;1").
   - PR #447: TennoGmEval (Yukawa/Slater core integrals) fixed for U < 1e-7 at small T (#444) and no
              longer returns NaN for large U and T; the slow, thread-unsafe Gaussian-fit fallback
              is replaced by series expansions

CMakeLists.txt

@@ -140,6 +140,19 @@ option_with_default(LIBINT2_ENABLE_ERI3
   "Compile with support for up to N-th derivatives of 3-center electron repulsion integrals (-1 for OFF)" -1)
 option_with_default(LIBINT2_ENABLE_ERI2
   "Compile with support for up to N-th derivatives of 2-center electron repulsion integrals (-1 for OFF)" -1)
+option_with_default(LIBINT2_ENABLE_RKB_ERI
+        "Compile with support for up to N-th derivatives of relativistic restricted kinetic
+         balance (RKB) 4-center electron repulsion integrals (-1 for OFF). Only N=0 is currently supported." -1)
+option_with_default(LIBINT2_ENABLE_RKB_ERI3
+        "Compile with support for up to N-th derivatives of relativistic restricted kinetic
+         balance (RKB) 3-center electron repulsion integrals (-1 for OFF).
+         σ·p acts on the two paired (AO) centers; the unpaired/fitting center is a spectator.
+         Only N=0 is currently supported." -1)
+foreach(_cls RKB_ERI;RKB_ERI3)
+    if (LIBINT2_ENABLE_${_cls} GREATER 0)
+        message(FATAL_ERROR "LIBINT2_ENABLE_${_cls}=${LIBINT2_ENABLE_${_cls}}: geometric derivatives of RKB integrals are not yet implemented; use 0 (or -1 for OFF)")
+    endif()
+endforeach()
 option_with_default(LIBINT2_ENABLE_G12
   "Compile with support for N-th derivatives of MP2-F12 energies with Gaussian factors (-1 for OFF)" -1)
 option_with_default(LIBINT2_ENABLE_G12DKH
@@ -219,10 +232,25 @@ option_with_default(LIBINT2_ERI_OPT_AM
   "Optimize 4-center ERIs maximally for up to angular momentum N (N <= max-am).
    Can specify values for each derivative level as a semicolon-separated string (default: (max_am/2)+1)" -1)
 
+option_with_default(LIBINT2_RKB_ERI_MAX_AM
+        "Support relativistic restricted kinetic balance (RKB) 4-center ERIs for Gaussians of angular momentum up to N.
+   Can specify values for each derivative level as a semicolon-separated string. (default: max_am)" -1)
+option_with_default(LIBINT2_RKB_ERI_OPT_AM
+        "Optimize relativistic restricted kinetic balance (RKB) 4-center ERIs maximally for up to angular momentum N (N <= max-am).
+   Can specify values for each derivative level as a semicolon-separated string (default: (max_am/2)+1)" -1)
+
+option_with_default(LIBINT2_RKB_ERI3_MAX_AM
+        "Support relativistic restricted kinetic balance (RKB) 3-center ERIs for Gaussians of angular momentum up to N.
+   Can specify values for each derivative level as a semicolon-separated string. (default: max_am)
+   This sets the max AM of the density fitting (auxiliary/DF) basis on the single fitting center. The paired AO centers (on which σ·p acts) use LIBINT2_MAX_AM." -1)
+option_with_default(LIBINT2_RKB_ERI3_OPT_AM
+        "Optimize relativistic restricted kinetic balance (RKB) 3-center ERIs maximally for up to angular momentum N (N <= max-am).
+   Can specify values for each derivative level as a semicolon-separated string (default: (max_am/2)+1)" -1)
+
 option_with_default(LIBINT2_ERI3_MAX_AM
   "Support 3-center ERIs for Gaussians of angular momentum up to N.
    Can specify values for each derivative level as a semicolon-separated string. (default: max_am)
-   This option controls only the single fitting center. The paired centers use LIBINT2_MAX_AM." -1)
+   This sets the max AM of the density fitting (auxiliary/DF) basis on the single fitting center. The paired AO centers use LIBINT2_MAX_AM." -1)
 option_with_default(LIBINT2_ERI3_OPT_AM
   "Optimize 3-center ERIs maximally for up to angular momentum N (N <= max-am).
    Can specify values for each derivative level as a semicolon-separated string. (default: (max_am/2)+1)" -1)
@@ -307,7 +335,8 @@ include(int_am)
 # see #445). Map unset/empty values to the -1 sentinel.
 foreach(_v MAX_AM OPT_AM
         ONEBODY_MAX_AM ONEBODY_OPT_AM ERI_MAX_AM ERI_OPT_AM ERI3_MAX_AM ERI3_OPT_AM
-        ERI2_MAX_AM ERI2_OPT_AM G12_MAX_AM G12_OPT_AM G12DKH_MAX_AM G12DKH_OPT_AM)
+        ERI2_MAX_AM ERI2_OPT_AM RKB_ERI_MAX_AM RKB_ERI_OPT_AM RKB_ERI3_MAX_AM RKB_ERI3_OPT_AM
+        G12_MAX_AM G12_OPT_AM G12DKH_MAX_AM G12DKH_OPT_AM)
     if ("${LIBINT_${_v}}" STREQUAL "")
         set(LIBINT_${_v} -1)
     endif()

INSTALL.md

@@ -113,7 +113,7 @@ Use combined targets like `cmake --target check install` to avoid some unnecessa
 * `🔸` required or recommended, but there's a path forward without
 * `-` not involved
 
-[^1]: C++ compiler that supports C++11 standard. C++11 standard is the fourth most recent international standard for C++, hence most modern compilers support it fully. A common compiler flag is `-std=c++11`, which CMake will impose on the compilation.
+[^1]: C++ compiler that supports C++11 standard (the Libint compiler itself requires C++17). C++11 standard is the fourth most recent international standard for C++, hence most modern compilers support it fully. A common compiler flag is `-std=c++11`, which CMake will impose on the compilation.
 
 [^2]: Fortran 2003 compiler to enable Fortran bindings generation.
 
@@ -169,6 +169,8 @@ Use combined targets like `cmake --target check install` to avoid some unnecessa
 * `LIBINT2_ENABLE_ERI` - G - Compile with support for up to N-th derivatives of 4-center electron repulsion integrals. Use -1 for OFF. [Default=0]
 * `LIBINT2_ENABLE_ERI3` - G - Compile with support for up to N-th derivatives of 3-center electron repulsion integrals. Use -1 for OFF. [Default=-1]
 * `LIBINT2_ENABLE_ERI2` - G - Compile with support for up to N-th derivatives of 2-center electron repulsion integrals. Use -1 for OFF. [Default=-1]
+* `LIBINT2_ENABLE_RKB_ERI` - G - Compile with support for up to N-th derivatives of relativistic restricted kinetic balance (RKB) 4-center electron repulsion integrals. Use -1 for OFF. Derivatives are not yet implemented, i.e. only N=0 is supported. [Default=-1]
+* `LIBINT2_ENABLE_RKB_ERI3` - G - Compile with support for up to N-th derivatives of relativistic restricted kinetic balance (RKB) 3-center electron repulsion integrals. Use -1 for OFF. σ·p acts on the two paired (AO) centers; the unpaired/fitting (density-fitting/auxiliary) center is a spectator. Derivatives are not yet implemented, i.e. only N=0 is supported. [Default=-1]
 * `LIBINT2_ENABLE_G12` - G - Compile with support for N-th derivatives of MP2-F12 energies with Gaussian factors. Use -1 for OFF. [Default=-1]
 * `LIBINT2_ENABLE_G12DKH` - G - Compile with support for N-th derivatives of DKH-MP2-F12 energies with Gaussian factors. Use -1 for OFF. [Default=-1]
 
@@ -255,6 +257,12 @@ Note that options, docs, and CMake components are focused on the C++ interface,
 * `LIBINT2_ERI2_OPT_AM` - G - Optimize 2-center ERIs maximally for up to angular momentum N (N <= max-am). Can specify values for each derivative level as a semicolon-separated string. [Default=-1 -> `LIBINT2_OPT_AM`]
 * `LIBINT2_ERI2_PURE_SH` - G - Assume the 2-center ERIs will be transformed to pure solid harmonics. [Default=OFF]
 
+* `LIBINT2_RKB_ERI_MAX_AM` - G - Support RKB 4-center ERIs for Gaussians of angular momentum up to N. Can specify values for each derivative level as a semicolon-separated string. [Default=-1 -> `LIBINT2_MAX_AM`]
+* `LIBINT2_RKB_ERI_OPT_AM` - G - Optimize RKB 4-center ERIs maximally for up to angular momentum N (N <= max-am). Can specify values for each derivative level as a semicolon-separated string. [Default=-1 -> `LIBINT2_OPT_AM`]
+
+* `LIBINT2_RKB_ERI3_MAX_AM` - G - Support RKB 3-center ERIs for Gaussians of angular momentum up to N. Can specify values for each derivative level as a semicolon-separated string. This option sets the AM of the density-fitting (auxiliary) basis on the single fitting center; the paired (AO) centers, on which σ·p acts, use LIBINT2_MAX_AM. [Default=-1 -> `LIBINT2_MAX_AM`]
+* `LIBINT2_RKB_ERI3_OPT_AM` - G - Optimize RKB 3-center ERIs maximally for up to angular momentum N (N <= max-am). Can specify values for each derivative level as a semicolon-separated string. [Default=-1 -> `LIBINT2_OPT_AM`]
+
 * `LIBINT2_G12_MAX_AM` - G - Support integrals for G12 methods of angular momentum up to N. No specification with per-derivative list. [Default=-1 -> `LIBINT2_MAX_AM`]
 * `LIBINT2_G12_OPT_AM` - G - Optimize G12 integrals for up to angular momentum N (N <= max-am). No specification with per-derivative list. [Default=-1 `LIBINT2_OPT_AM`]