feat(rpa): modularize RPA and extend LibRPA exports

.github/workflows/build_test_cmake.yml

@@ -70,8 +70,18 @@ jobs:
 
       - name: Build
         run: |
+          set -o pipefail
           git config --global --add safe.directory `pwd`
           source toolchain/install/setup
           rm -rf build
           cmake -B build -G Ninja ${{ matrix.build_args }}
-          cmake --build build -j $(nproc)
+          cmake --build build -j $(nproc) 2>&1 | tee build.log
+
+      - name: Report build diagnostics
+        if: failure()
+        run: |
+          if [[ -f build.log ]]; then
+            message=$(grep -Ein -B 8 -A 8 'error:|fatal error:|undefined reference|FAILED|No rule to make' build.log || true)
+            message=$(printf '%s\n' "$message" | tail -n 120 | tr '\n' ' ' | cut -c1-5000)
+            echo "::error file=build.log,line=1,title=ABACUS build diagnostics::$message"
+          fi

.github/workflows/test.yml

@@ -86,6 +86,7 @@ jobs:
       - name: Configure
         run: |
           source toolchain/install/setup
+          set -o pipefail
           cmake -B build -G Ninja \
             -DBUILD_TESTING=ON \
             -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
@@ -97,7 +98,14 @@ jobs:
             -DENABLE_FLOAT_FFTW=ON \
             -DENABLE_DFTD4=ON \
             -DENABLE_PEXSI=ON \
-            -Werror=dev
+            -Werror=dev 2>&1 | tee configure.log
+
+      - name: Report configuration diagnostics
+        if: failure()
+        run: |
+          message=$(grep -Ein -B 8 -A 8 'CMake Error|CMake Warning.*error|fatal error|FAILED' configure.log || true)
+          message=$(printf '%s\n' "$message" | tail -n 120 | tr '\n' ' ' | cut -c1-5000)
+          echo "::error file=configure.log,line=1,title=ABACUS configuration diagnostics::$message"
 
 # Temporarily removed because no one maintains this now.
 # And it will break the CI test workflow.
@@ -112,8 +120,16 @@ jobs:
 
       - name: Build
         run: |
-          cmake --build build -j8
-          cmake --install build
+          set -o pipefail
+          cmake --build build -j8 2>&1 | tee build.log
+          cmake --install build 2>&1 | tee -a build.log
+
+      - name: Report build diagnostics
+        if: failure()
+        run: |
+          message=$(grep -Ein -B 8 -A 8 'error:|fatal error:|undefined reference|FAILED|No rule to make' build.log || true)
+          message=$(printf '%s\n' "$message" | tail -n 120 | tr '\n' ' ' | cut -c1-5000)
+          echo "::error file=build.log,line=1,title=ABACUS build diagnostics::$message"
 
       - name: Report compiler cache
         if: always()

CMakeLists.txt

@@ -68,6 +68,10 @@ option(ENABLE_CNPY "Enable cnpy usage" OFF)
 cmake_dependent_option(ENABLE_ELPA "Enable ELPA eigensolver" ON "ENABLE_MPI" OFF)
 cmake_dependent_option(ENABLE_LIBRI "Enable LibRI for hybrid functional"
                        OFF "ENABLE_LCAO;ENABLE_MPI" OFF)
+cmake_dependent_option(ENABLE_GREENX_MINIMAX
+                       "Enable the external GreenX minimax API for Delta-Sternheimer"
+                       OFF "ENABLE_LCAO;ENABLE_MPI;ENABLE_LIBRI" OFF)
+set(GREENX_DIR "" CACHE PATH "GreenX installation prefix or CMake package directory")
 cmake_dependent_option(ENABLE_PEXSI "Enable PEXSI for LCAO" OFF "ENABLE_LCAO;ENABLE_MPI" OFF)
 cmake_dependent_option(ENABLE_MLALGO "Enable the machine learning algorithms"
                        OFF "ENABLE_LCAO;ENABLE_MPI" OFF)
@@ -607,6 +611,11 @@ if(ENABLE_LIBRI)
   find_package(cereal REQUIRED CONFIG)
 endif()
 
+if(ENABLE_GREENX_MINIMAX)
+  enable_language(Fortran)
+  find_package(GreenX REQUIRED)
+endif()
+
 if(ENABLE_LIBXC)
   find_package(Libxc CONFIG REQUIRED)
   if(Libxc_VERSION VERSION_LESS "5.1.7")

cmake/modules/FindGreenX.cmake

@@ -0,0 +1,92 @@
+# Find an external GreenX minimax installation or source tree.
+#
+# Supported inputs:
+#   GREENX_DIR=<prefix>  install prefix containing GreenXConfig.cmake or
+#                        Fortran modules and libgx_minimax
+#   GREENX_DIR=<package> GreenX install prefix or package directory
+#
+# The module exposes GreenX::MiniMax when the minimax API is available.
+
+set(GreenX_FOUND FALSE)
+
+if(TARGET GreenX::MiniMax)
+  set(GreenX_FOUND TRUE)
+elseif(TARGET greenX::LibGXMiniMax)
+  add_library(GreenX::MiniMax ALIAS greenX::LibGXMiniMax)
+  set(GreenX_FOUND TRUE)
+elseif(TARGET LibGXMiniMax)
+  add_library(GreenX::MiniMax ALIAS LibGXMiniMax)
+  set(GreenX_FOUND TRUE)
+endif()
+
+# GreenX is an external dependency.  Prefer its installed CMake package so
+# that ABACUS does not compile or vendor GreenX sources.  GREENX_DIR may point
+# either to the install prefix or directly to the package directory.
+if(NOT GreenX_FOUND)
+  set(_greenx_config_paths)
+  if(GREENX_DIR)
+    list(APPEND _greenx_config_paths
+      "${GREENX_DIR}"
+      "${GREENX_DIR}/lib/cmake/greenX"
+      "${GREENX_DIR}/lib64/cmake/greenX"
+      "${GREENX_DIR}/share/greenX/cmake")
+  endif()
+  if(GREENX_DIR)
+    find_package(greenX CONFIG QUIET
+      PATHS ${_greenx_config_paths}
+      NO_DEFAULT_PATH)
+  else()
+    find_package(greenX CONFIG QUIET)
+  endif()
+  if(TARGET greenX::LibGXMiniMax)
+    add_library(GreenX::MiniMax ALIAS greenX::LibGXMiniMax)
+    set(GreenX_FOUND TRUE)
+  endif()
+endif()
+
+if(NOT GreenX_FOUND AND GREENX_DIR)
+  find_path(GreenX_Fortran_MODULE_DIR
+    NAMES gx_minimax.mod
+    PATHS
+      "${GREENX_DIR}/include"
+      "${GREENX_DIR}/modules"
+      "${GREENX_DIR}/lib"
+    NO_DEFAULT_PATH)
+  find_library(GreenX_MINIMAX_LIBRARY
+    NAMES gx_minimax LibGXMiniMax
+    PATHS
+      "${GREENX_DIR}/lib"
+      "${GREENX_DIR}/lib64"
+    NO_DEFAULT_PATH)
+  find_library(GreenX_COMMON_LIBRARY
+    NAMES GXCommon gx_common
+    PATHS
+      "${GREENX_DIR}/lib"
+      "${GREENX_DIR}/lib64"
+    NO_DEFAULT_PATH)
+
+  if(GreenX_Fortran_MODULE_DIR AND GreenX_MINIMAX_LIBRARY)
+    add_library(GreenX::MiniMax UNKNOWN IMPORTED)
+    set_target_properties(GreenX::MiniMax PROPERTIES
+      IMPORTED_LOCATION "${GreenX_MINIMAX_LIBRARY}"
+      INTERFACE_INCLUDE_DIRECTORIES "${GreenX_Fortran_MODULE_DIR}")
+    if(math_libs)
+      set_property(TARGET GreenX::MiniMax APPEND PROPERTY
+        INTERFACE_LINK_LIBRARIES "${math_libs}")
+    endif()
+    if(GreenX_COMMON_LIBRARY)
+      set_property(TARGET GreenX::MiniMax APPEND PROPERTY
+        INTERFACE_LINK_LIBRARIES "${GreenX_COMMON_LIBRARY}")
+    endif()
+    set(GreenX_FOUND TRUE)
+  endif()
+endif()
+
+if(NOT GreenX_FOUND AND GreenX_FIND_REQUIRED)
+  message(FATAL_ERROR
+    "GreenX minimax was requested but no usable installation was found. "
+    "Set GREENX_DIR to a GreenX installation prefix or CMake package directory "
+    "containing gx_minimax.mod and libgx_minimax.")
+endif()
+
+mark_as_advanced(GreenX_Fortran_MODULE_DIR GreenX_MINIMAX_LIBRARY GreenX_COMMON_LIBRARY)

docs/advanced/input_files/input-main.md

@@ -204,8 +204,8 @@
     - [out\_element\_info](#out_element_info)
     - [restart\_save](#restart_save)
     - [rpa](#rpa)
-    - [rpa\_out\_vel](#rpa_out_vel)
-    - [rpa\_outdir](#rpa_outdir)
+    - [out\_librpa\_reader\_version](#out_librpa_reader_version)
+    - [out\_librpa\_abf\_overlap](#out_librpa_abf_overlap)
     - [out\_pchg](#out_pchg)
     - [out\_wfc\_norm](#out_wfc_norm)
     - [out\_wfc\_re\_im](#out_wfc_re_im)
@@ -339,6 +339,8 @@
     - [exx\_real\_number](#exx_real_number)
     - [exx\_singularity\_correction](#exx_singularity_correction)
     - [rpa\_ccp\_rmesh\_times](#rpa_ccp_rmesh_times)
+    - [rpa\_abfs\_preorth](#rpa_abfs_preorth)
+    - [rpa\_abfs\_preorth\_threshold](#rpa_abfs_preorth_threshold)
     - [exx\_symmetry\_realspace](#exx_symmetry_realspace)
     - [out\_ri\_cv](#out_ri_cv)
   - [Exact Exchange (PW)](#exact-exchange-pw)
@@ -2429,20 +2431,19 @@
   > Note: If symmetry is set to 1, additional files containing the necessary information for exploiting symmetry in the subsequent rpa calculation will be output: irreducible_sector.txt, symrot_k.txt and symrot_R.txt.
 - **Default**: False
 
-### rpa_out_vel
+### out_librpa_reader_version
 
-- **Type**: Boolean
-- **Availability**: *[`basis_type`](#basis_type)==lcao*
-- **Description**: Velocity matrix in KS basis (in unit of eV *Angstrom). Loop layer: spin -> k -> direction -> KS_basis1 -> KS_basis2.
-- **Default**: False
-- **Unit**: eV * A
+- **Type**: Integer
+- **Availability**: *Numerical atomic orbital basis with rpa=True.*
+- **Description**: Select the ABACUS output format for files consumed by LibRPA. 0 writes the legacy text files, and 1 writes LibRPA reader-v1 binary files directly.
+- **Default**: 0
 
-### rpa_outdir
+### out_librpa_abf_overlap
 
-- **Type**: String
-- **Availability**: *[`basis_type`](#basis_type)==lcao*
-- **Description**: The directory to save files for LibRPA.
-- **Default**: "OUT.librpa"
+- **Type**: Boolean
+- **Availability**: *Numerical atomic orbital basis with rpa=True, reader version 1, and shrink ABFs.*
+- **Description**: Writes dense raw active-ABF q-space overlap matrices as `v1_abf_overlap_active_iq_<iq>.dat` for offline PSD diagnostics; this can be high-cost in memory and output size. The writer fails closed if an actually present post-communication `(I,J,R)` key has duplicate MPI contributors, and reports the offending integer key. This check proves uniqueness only for keys present in the post-communication map; it does not assert complete R coverage or pre-communication ownership. The analyzer uses `basis_aux_shrink_out` only to validate per-type shell layout and its declared total; that file does not provide atom-to-type mapping. Full-unshrunk overlap output is not provided because that basis lifecycle is not available safely here.
+- **Default**: False
 
 ### out_pchg
 
@@ -3424,6 +3425,22 @@
 - **Description**: How many times larger the radial mesh required is to that of atomic orbitals in the postprocess calculation of the bare Coulomb matrix for RPA, GW, etc.
 - **Default**: 10
 
+### rpa_abfs_preorth
+
+- **Type**: String
+- **Description**: Controls on-site Coulomb-metric preorthogonalization of the auxiliary basis used by RPA producer and Sternheimer response output.
+  - `none`: preserve the legacy auxiliary basis exactly.
+  - `onsite_coulomb`: process every atom type and angular-momentum radial channel independently, reject near-dependent radial functions, and retain complete `(2l+1)` multiplets in an on-site Coulomb-orthonormal basis.
+
+  This option does not change ordinary EXX, GW, SCF, force, or stress auxiliary-basis construction. The producer and Sternheimer response must use the same value. Molecular production workflows validated with this option use a separate LibRPA global Coulomb hard threshold of `1e-4`; ABACUS does not set that LibRPA threshold automatically.
+- **Default**: none
+
+### rpa_abfs_preorth_threshold
+
+- **Type**: Real
+- **Description**: Squared residual on-site Coulomb norm at or below which a radial auxiliary function is rejected when `rpa_abfs_preorth=onsite_coulomb`. The value must be finite and strictly inside `(0,1)`. The validated molecular starting value is `1e-2`.
+- **Default**: 1e-2
+
 ### exx_symmetry_realspace
 
 - **Type**: Boolean

docs/advanced/interface/LibRPA.md

@@ -0,0 +1,95 @@
+# LibRPA exports with SOC and magnetic symmetry
+
+The LCAO RI exporter writes the ABACUS states and auxiliary-basis data needed
+by a compatible LibRPA reader. The reader constructs orbital and k-space
+rotation matrices from the spatial operations, lattice, atomic coordinates,
+and basis-shell conventions; no `symrot_*` sidecar files are part of this
+interface.
+Enabling an export does not certify symmetry equivalence of a downstream
+RPA/GW calculation.
+
+## Producer settings
+
+For an otherwise complete, converged LCAO SOC input, the relevant settings are:
+
+```text
+basis_type                  lcao
+nspin                       4
+lspinorb                    1
+symmetry                    1
+rpa                         1
+out_ri_cv                   1
+out_wfc_lcao                1
+out_mat_xc                  1
+out_librpa_reader_version   1
+```
+
+Set the intended magnetic moments in `STRU`. With `symmetry=1`, an all-zero
+initial magnetic configuration stays zero; it is not automatically replaced
+by nonzero starting moments. A nonmagnetic SOC system uses a grey group,
+whereas an ordered magnetic system uses the operations preserving that
+configuration, possibly combined with time reversal. For an on/off comparison,
+use a common converged density and keep the structure, basis, k mesh and
+numerical thresholds fixed.
+
+## Common symmetry operation block in `stru_out`
+
+The existing physical lattice/position units and spatial `row` convention
+are retained. After the atom records, symmetry-enabled output contains:
+
+```text
+N row
+<9 integer rotation entries and 3 fractional translations, repeated N times>
+```
+
+The same spatial-operation format is used for scalar space groups and for the
+spatial part of a magnetic group. Magnetic operations are written after the
+unitary operations in the same 12-field rows. For `nspin=4`, the producer then
+appends an explicit `spin_symmetry <grey_group> <spin_source>` block. Each row
+contains an antiunitary flag and, when `spin_source=1`, the eight real and
+imaginary components of the corresponding SU(2) spin rotation. This keeps the
+spatial block compatible with scalar and magnetic groups while giving a SOC-
+aware LibRPA reader the complete operation table. Readers that do not consume
+the optional spin block can stop after the spatial rows.
+
+## Optional auxiliary-overlap diagnostic
+
+To inspect the active, shrunk auxiliary basis, also set:
+
+```text
+shrink_abfs_pca_thr          1e-6
+out_librpa_abf_overlap       1
+```
+
+The threshold is an example, not a convergence recommendation. The option
+requires `rpa=1`, reader version `1`, and a nonnegative shrink threshold.
+It writes `v1_abf_overlap_active_iq_<iq>.dat` in the same active auxiliary
+basis as the associated Coulomb matrices. It does not export the full
+unshrunk overlap. Dense matrices can require substantial memory and disk.
+
+From the ABACUS source tree, inspect a completed export with:
+
+```bash
+python3 tools/analyze_librpa_abf_overlap.py /path/to/export
+python3 tools/test_analyze_librpa_abf_overlap.py
+```
+
+The analyzer checks metadata and matrix properties. The writer rejects
+duplicate MPI contributors for present `(I,J,R)` blocks. Neither check
+establishes complete real-space coverage or physical convergence.
+
+## Occupation precision and validation
+
+`band_out` writes the Fermi energy in Hartree and each occupation as the
+native k-weighted occupation multiplied by the number of exported k points.
+The stream precision is initialized before these values, including the first
+occupation. Previously the first occupation and Fermi energy retained the
+stream's default six significant digits; removing an irreducible k weight
+could turn an occupied state into `0.999999` or `1.000002`.
+
+An export check can divide the printed occupation by the exported k-point
+count and compare it with `OUT.<suffix>/eig_occ.txt`. Validate the first row
+as well as later rows. A successful LibRPA reader/EXX run establishes that the
+files can be consumed; full/reduced-grid RPA or GW equivalence requires a
+separate numerical comparison. This producer check does not change LibRPA's
+archived-input regression workflow.

docs/advanced/interface/index.rst

@@ -20,3 +20,4 @@ Interfaces to Other Softwares
    candela
    TB2J
    migration-guide-csr-format
+   LibRPA