refactor(klist): extract time-reversal op doubling into KListIO

Move the inversion check and the time-reversal operation expansion
(Theta*g antiunitary coset for magnetic nspin=4, -g doubling
otherwise) out of K_Vectors::reduce_by_symmetry into the this-free
KListIO::append_time_reversal_ops. The physics comment moves with the
logic. reduce_by_symmetry cyclomatic complexity drops 13 -> 7 and the
file loses the Matrix3 'inv' local (brace-initialized in the helper),
removing a 9-parameter false positive; klist.cpp 793 -> 763 lines.

Author: abacus_fixer

source/source_cell/klist.cpp

@@ -564,9 +564,7 @@ void K_Vectors::reduce_by_symmetry(const UnitCell& ucell,
     // if the operations does not already included
     // inverse operation, double it.
     //===============================================
-    bool include_inv = false;
     std::vector<ModuleBase::Matrix3> kgmatrix(48 * 2);
-    ModuleBase::Matrix3 inv(-1, 0, 0, 0, -1, 0, 0, 0, -1);
 
     ModuleBase::Matrix3 k_vec;
     int nrotkm = 0;
@@ -580,39 +578,9 @@ void K_Vectors::reduce_by_symmetry(const UnitCell& ucell,
         return;
     }
 
-    // check whether the inverse operation is already included
-    for (int i = 0; i < nrotkm; ++i)
-    {
-        if (kgmatrix[i] == inv)
-        {
-            include_inv = true;
-        }
-    }
-
-    if (symm.magnetic_nspin4)
-    {
-        // (nspin=4, magnetic) Time reversal Theta reverses the magnetization, so Theta alone is
-        // NOT a symmetry and the blanket "-k is always equivalent" doubling below is invalid.
-        // Only the antiunitary elements Theta*g with g in the moment-reversing coset belong to
-        // the Shubnikov group; append exactly those, keeping the index convention
-        // j + nrotk  <->  Theta * gmatrix_anti[j]  (decoded the same way in restore_dm).
-        // (nspin=2 is unaffected: there the antiunitary operation is plain conjugation K, which
-        //  does not touch the spin, so D_s(-k)=D_s^*(k) holds even for a ferromagnet and the
-        //  generic branch below stays correct.)
-        for (int j = 0; j < symm.nrotk_anti; ++j)
-        {
-            kgmatrix[j + symm.nrotk] = inv * symm.kgmatrix_anti[j];
-        }
-        nrotkm = symm.nrotk + symm.nrotk_anti;
-    }
-    else if (!include_inv)
-    {
-        for (int i = 0; i < symm.nrotk; ++i)
-        {
-            kgmatrix[i + symm.nrotk] = inv * symm.kgmatrix[i];
-        }
-        nrotkm = 2 * symm.nrotk;
-    }
+    // append time-reversal-related operations (Theta*g for magnetic
+    // nspin=4; -g otherwise unless inversion is already present)
+    nrotkm = KListIO::append_time_reversal_ops(symm, kgmatrix, nrotkm);
 
     // convert kgmatrix to k-lattice
     std::vector<ModuleBase::Matrix3> kkmatrix(nrotkm);

source/source_cell/klist_io.cpp

@@ -9,6 +9,7 @@
 #include "source_base/formatter.h"
 #include "source_base/global_function.h"
 #include "source_base/parallel_common.h"
+#include "source_cell/module_symmetry/symmetry.h"
 #include "source_cell/reciprocal_grid.h"
 
 #include <sstream>
@@ -207,6 +208,46 @@ void build_kstars(const std::vector<ModuleBase::Vector3<double>>& kvec_d,
     }
 }
 
+int append_time_reversal_ops(const ModuleSymmetry::Symmetry& symm,
+                             std::vector<ModuleBase::Matrix3>& kgmatrix,
+                             const int nrotkm)
+{
+    const ModuleBase::Matrix3 inv{-1.0, 0.0, 0.0, 0.0, -1.0, 0.0, 0.0, 0.0, -1.0};
+
+    bool include_inv = false;
+    for (int i = 0; i < nrotkm; ++i)
+    {
+        if (kgmatrix[i] == inv)
+        {
+            include_inv = true;
+        }
+    }
+
+    if (symm.magnetic_nspin4)
+    {
+        // (nspin=4, magnetic) Time reversal Theta reverses the magnetization,
+        // so Theta alone is NOT a symmetry; only the antiunitary Theta*g
+        // elements with g in the moment-reversing coset belong to the
+        // Shubnikov group. The same index convention j + nrotk is decoded
+        // in restore_dm. (nspin=2 is unaffected: there the antiunitary
+        // operation is plain conjugation K, which leaves D_s(-k)=D_s*(k).)
+        for (int j = 0; j < symm.nrotk_anti; ++j)
+        {
+            kgmatrix[j + symm.nrotk] = inv * symm.kgmatrix_anti[j];
+        }
+        return symm.nrotk + symm.nrotk_anti;
+    }
+    if (!include_inv)
+    {
+        for (int i = 0; i < symm.nrotk; ++i)
+        {
+            kgmatrix[i + symm.nrotk] = inv * symm.kgmatrix[i];
+        }
+        return 2 * symm.nrotk;
+    }
+    return nrotkm;
+}
+
 void pack_kpts(const std::vector<int>& isk,
                const std::vector<double>& wk,
                const std::vector<ModuleBase::Vector3<double>>& kvec_c,

source/source_cell/klist_io.h

@@ -10,6 +10,11 @@
 #include <string>
 #include <vector>
 
+namespace ModuleSymmetry
+{
+class Symmetry; // full definition only needed in klist_io.cpp
+}
+
 /// this-free helpers extracted from K_Vectors, kept in a separate TU so they
 /// can be unit-tested and reused without dragging in the K_Vectors class.
 namespace KListIO
@@ -65,6 +70,16 @@ void build_kstars(const std::vector<ModuleBase::Vector3<double>>& kvec_d,
                   const std::function<bool(double, double)>& equal,
                   std::vector<std::map<int, ModuleBase::Vector3<double>>>& kstars);
 
+/// Append the time-reversal-related k-point symmetry operations into
+/// `kgmatrix` (the slots right after the first `nrotkm` operations must be
+/// available). For magnetic nspin=4 systems the antiunitary Theta*g coset
+/// is appended from `symm.kgmatrix_anti`; otherwise the inverted -g ops are
+/// appended unless inversion is already present. Returns the updated total
+/// operation count.
+int append_time_reversal_ops(const ModuleSymmetry::Symmetry& symm,
+                             std::vector<ModuleBase::Matrix3>& kgmatrix,
+                             int nrotkm);
+
 /// Flatten k-point arrays into contiguous MPI buffers (x,y,z interleaved).
 /// this-free; used on rank 0 before broadcasting in K_Vectors::mpi_k.
 void pack_kpts(const std::vector<int>& isk,