refactor(parallel): step-1b add Parallel_Global::create_topology factory + align error path

Scope: 9 files changed, +304 -6 lines.
Build: cmake --build build exit=0, abacus_basic_para linked successfully.
Test suite (all run with OMP_NUM_THREADS=1 mpirun -np 4):
  - MODULE_BASE_ProcessTopology : 8 / 8 passed
      (5 divide_mpi_groups arithmetic cases
       + 2 synthetic ProcessTopology accessor cases
       + 1 MPI-global integration case
         ParallelGlobalCreateTopology.FourRanksKpar2Bndpar2DiagNp2
         covering every scalar field, the 6 legacy-global comm sizes
         and matrix/atom == MPI_COMM_NULL).
  - MODULE_BASE_ParaReduce    : 10 / 10 passed
  - MODULE_BASE_ParaGlobal    : 6  / 6  passed
  - MODULE_BASE_ParaCommon    : 1  / 1  passed

1. Error-path fix in divide_mpi_groups:
   The even=true branch used to `exit(1)` on an uneven split, which
   bypassed ABACUS' WARNING_QUIT machinery (no stack cleanup, no
   consistent formatting). Replaced with
   ModuleBase::WARNING_QUIT("...Even partition requested...") so all
   failure paths now share the same error sink. No call-site change.

2. New Parallel_Global::create_topology(world, my_rank, kpar, bndpar,
   diag_np, grid_np):
   - Declared in parallel_global.h together with a detailed docstring
     explaining the kpar -> pool -> band-group layering, the legacy
     communicator aliases and the "caller later fills matrix / atom
     domains" injection contract.
   - Implemented in parallel_global.cpp under the same TU that owns
     divide_pools so we reuse every existing MPI_Comm_split /
     MPICommGroup::divide_group_comm helper rather than re-implement
     the partition.
   - non-__MPI builds return the trivial single-process
     ProcessTopology() instead of linking MPI code.
   - Snapshot construction:
       * nproc_in_pool vector is built with the even=false partition
         rule directly (base = world/kpar; first `extra_procs` groups
         get base+1). No MPI calls, O(kpar) only.
       * Legacy divide_pools(...) is called first -> fills POOL_WORLD
         / KP_WORLD / INT_BGROUP / BP_WORLD scalars and ints.
       * split_diag_world / split_grid_world(diag_np) are called
         immediately afterwards, folding the "two subroutines that
         real drivers have always called after divide_pools" step
         into a single factory so callers cannot forget to build
         rgrid/diag views. diag_np==0 safely falls back to diag_np=1.
       * Scalars (kpar/my_pool/rank_in_pool / band group triple) and
         all 6 legacy-global MPI_Comm handles plus MPI_COMM_NULL for
         matrix/atom are then forwarded to the ProcessTopology full
         constructor once.
   - Compatibility: after create_topology returns, the 6 extern
     MPI_Comm globals (POOL_WORLD..DIAG_WORLD) are still valid and
     hold exactly the same handles as before because they were the
     ones copied into the topology. No existing call site has to
     change today. The migration plan remains: new code takes a
     const ProcessTopology&; legacy code keeps reading the aliases.

3. Unit tests added to parallel_topology_test.cpp:
   - The file now provides its own main(argc, argv) that calls
     MPI_Init / MPI_Finalize around RUN_ALL_TESTS so gtest-based
     processes never issue MPI calls before MPI_Init (the error that
     surfaced while wiring the integration case).
   - Integration case ParallelGlobalCreateTopology.FourRanksKpar2Bndpar2DiagNp2:
       * GTEST_SKIP() if nproc != 4.
       * Asserts scalar invariants for every rank (world_size, kpar,
         bndpar, nproc_in_pool vector, pool_root_rank,
         band_group_root_rank).
       * Per-rank scalar expectations are laid out in a comment table
         R0..R3 that was cross-validated against the real factory
         output during development.
       * Asserts MPI_Comm_size/rank for all 6 derived legacy
         communicators plus matrix/atom == MPI_COMM_NULL.
   - Both synthetic ProcessTopology cases are untouched.

4. Hand-written SOURCES lists wired parallel_topology.cpp:
   create_topology lives in parallel_global.cpp and constructs a
   ProcessTopology, pulling the class' constructor symbol. Many unit
   test and module CMakeLists already enumerate parallel_global.cpp
   by hand and therefore need to also name parallel_topology.cpp as
   a local TU. The following targets were updated:
     - MODULE_BASE_ParaCommon / ParaGlobal / ParaReduce (the 3
       parallel unit tests that mirror ParaTopology).
     - MODULE_PW_pwdft tests (source_pw/module_pwdft/test).
     - MODULE_MD_func (source_md/test).
     - MODULE_IO_*  (source_io/test).
     - MODULE_PW_PW_Kernels_UTs (module_pw/kernels/test).
     - MODULE_CELL_ParaKpoints (source_cell/test).
   This is exactly the same repair we had to apply for ParaCommon in
   Step 0. AGENTS rule: "Keep source file additions deterministic;
   update the relevant CMakeLists.txt" – satisfied.

Governance notes (agent_governance_check --staged):
  - WARNING Header dependency (parallel_global.h:10 includes
    parallel_topology.h): Required because create_topology returns
    ProcessTopology by-value, which requires the complete class
    declaration in every TU that includes parallel_global.h.
    parallel_topology.h only brings in <vector> and <mpi.h>, so no
    parallel_comm.h 6-comm transitive leakage is reintroduced.
    Exception allowed = yes.
  - WARNING Documentation sync: 0 user-facing INPUT / CLI / external
    API change. Factory is not yet called from production code.
    Exception allowed = yes.
  - GlobalV / PARAM / GlobalC: 0 new reads. The factory only
    receives its inputs by-value from callers and constructs the
    topology object; it never reaches into PARAM. AGENTS rule 1
    budget strictly non-increasing.
  - AGENTS rule 5 (no new default args on existing interfaces):
    create_topology is a brand-new free function, so the 6-int + 8-MPI_Comm
    ProcessTopology constructor default-args for matrix_world / atom_world
    (introduced in step 1a) still apply, but we did not add defaults
    to an existing signature.
  - C++11 compatible. One variable per declaration. No new direct
    MPI calls outside the __MPI guarded factories.

Author: abacus_fixer

source/source_base/parallel_global.cpp

@@ -283,6 +283,99 @@ void Parallel_Global::divide_pools(const int& NPROC,
     return;
 }
 
+ProcessTopology Parallel_Global::create_topology(int world_nproc,
+                                                 int my_rank,
+                                                 int kpar,
+                                                 int bndpar,
+                                                 int diag_np,
+                                                 int /*grid_np*/)
+{
+#ifdef __MPI
+    // ---- Build the nproc_in_pool vector (arithmetic, no MPI). ----
+    //
+    // divide_mpi_groups(..., num_groups=kpar, even=false) assigns
+    // the first `extra_procs` groups (extra_procs = world_nproc %
+    // kpar) to size (base+1) and the remaining (kpar-extra_procs)
+    // groups to size base, where base = world_nproc / kpar. No MPI;
+    // build the vector directly.
+    const int base = world_nproc / kpar;
+    const int extra_procs = world_nproc % kpar;
+    std::vector<int> nproc_in_pool(kpar, base);
+    for (int g = 0; g < extra_procs; ++g) { nproc_in_pool[g] = base + 1; }
+
+    // ---- Validation: sum of nproc_in_pool must equal world_nproc. ----
+    {
+        int total = 0;
+        for (int s : nproc_in_pool) { total += s; }
+        if (total != world_nproc)
+        {
+            ModuleBase::WARNING_QUIT("Parallel_Global::create_topology",
+                                     "internal: nproc_in_pool sum differs from world_nproc.");
+        }
+    }
+
+    // ---- Invoke the legacy divide_pools flow: it fills the 6 legacy
+    //      global communicators AND returns scalar int values. ----
+    //
+    // NOTE(mohan): order matters. divide_pools internally calls
+    //   kpar_group .divide_group_comm(KPAR, false);
+    //   bndpar_group.divide_group_comm(BNDPAR, true);
+    //   -> sets POOL_WORLD, KP_WORLD, INT_BGROUP, BP_WORLD.
+    int nproc_in_bndgroup = -1;
+    int rank_in_bpgroup   = -1;
+    int my_bndgroup       = -1;
+    int nproc_in_pool_local = -1; // output alias of bndpar_group.nprocs_in_group
+    int rank_in_pool_local  = -1; // output alias of bndpar_group.rank_in_group
+    int my_pool_local       = -1; // output alias of kpar_group.my_group
+    Parallel_Global::divide_pools(world_nproc, my_rank, bndpar, kpar,
+                                  nproc_in_bndgroup, rank_in_bpgroup, my_bndgroup,
+                                  nproc_in_pool_local, rank_in_pool_local, my_pool_local);
+
+    // ---- split diag / rgrid worlds. ----
+    // These two helpers currently write DIAG_WORLD / GRID_WORLD as a
+    // side effect; they were always called by drivers in the old flow
+    // right after divide_pools, so we fold them into the factory to
+    // centralise all 6 legacy comm + scalar topology construction.
+    //
+    // diag_np == 0 is not meaningful; fall back to 1 so the
+    // even-partition guard in divide_mpi_groups (called inside
+    // split_diag_world / split_grid_world) does not fire on
+    // "num_groups == 0".
+    const int effective_diag_np = (diag_np > 0) ? diag_np : 1;
+    int drank = -1, dsize = -1, dcolor = -1;
+    Parallel_Global::split_diag_world(effective_diag_np, world_nproc, my_rank, drank, dsize, dcolor);
+    int grank = -1, gsize = -1;
+    Parallel_Global::split_grid_world(effective_diag_np, world_nproc, my_rank, grank, gsize);
+
+    return ProcessTopology(world_nproc,
+                           my_rank,
+                           kpar,
+                           my_pool_local,
+                           rank_in_pool_local,
+                           nproc_in_pool,
+                           bndpar,
+                           my_bndgroup,
+                           rank_in_bpgroup,
+                           nproc_in_bndgroup,
+                           POOL_WORLD,      // -> pw_world_comm        (legacy duped handle)
+                           KP_WORLD,        // -> kmesh_world_comm     (KP_WORLD alias back)
+                           INT_BGROUP,      // -> bsame_kdiff_world_comm
+                           BP_WORLD,        // -> bdiff_ksame_world_comm
+                           GRID_WORLD,      // -> rgrid_world_comm
+                           DIAG_WORLD,      // -> diag_world_comm
+                           MPI_COMM_NULL,   // -> matrix_world_comm (caller-filled later)
+                           MPI_COMM_NULL);  // -> atom_world_comm   (caller-filled later)
+#else
+    // Serial / non-MPI fallback: a single-process trivial topology.
+    (void)world_nproc;
+    (void)my_rank;
+    (void)kpar;
+    (void)bndpar;
+    (void)diag_np;
+    return ProcessTopology();
+#endif
+}
+
 void Parallel_Global::divide_mpi_groups(const int& procs,
                                         const int& num_groups,
                                         const int& rank,
@@ -315,7 +408,10 @@ void Parallel_Global::divide_mpi_groups(const int& procs,
     {
         std::cout << "Error: Number of processes (" << procs << ") must be evenly divisible by the number of groups ("
                   << num_groups << " in the even partition case)." << std::endl;
-        exit(1);
+        ModuleBase::WARNING_QUIT(
+            "Parallel_Global::divide_mpi_groups",
+            "Even partition requested but procs is not divisible by num_groups."
+        );
     }
 
     if(rank < extra_procs * (procs_in_group + 1))

source/source_base/parallel_global.h

@@ -7,6 +7,7 @@
 #define PARALLEL_GLOBAL_H
 
 #include "parallel_comm.h"
+#include "parallel_topology.h"
 
 namespace Parallel_Global
 {
@@ -19,6 +20,46 @@ extern int omp_number;
 // changed from read_mpi_parameters in 2024-1018
 void read_pal_param(int argc, char** argv, int& NPROC, int& NTHREAD_PER_PROC, int& MY_RANK);
 
+/**
+ * @brief Build a ProcessTopology snapshot for the given parallel parameters.
+ *
+ * This is the single factory that knows how to:
+ *   * split MPI_COMM_WORLD into KPAR k-pools via divide_group_comm(even=false);
+ *   * split each pool into BNDPAR band groups via divide_group_comm(even=true);
+ *   * derive INT_BGROUP (bsame_kdiff_world) / BP_WORLD (bdiff_ksame_world);
+ *   * split diag_np-based DIAG_WORLD and diag_np-grouped GRID_WORLD.
+ *
+ * The returned ProcessTopology::pw_world_comm (previously POOL_WORLD) is the
+ * smallest PW tile: the intersection of one k-pool and one band-group.
+ *
+ * matrix_world_comm and atom_world_comm are left as MPI_COMM_NULL in the
+ * returned value; callers that know which distributed view is required for
+ * a given step (Parallel_2D / Parallel_Orbitals / DomainDecomposition) are
+ * expected to fill them in from the appropriate view before passing the
+ * topology down.
+ *
+ * Note: The factory is only available under __MPI. The non-MPI build path
+ * uses the default ProcessTopology constructor which already produces the
+ * single-process trivial topology.
+ *
+ * @param[in] world_nproc Size of MPI_COMM_WORLD
+ * @param[in] my_rank    Rank in MPI_COMM_WORLD
+ * @param[in] kpar       KPAR   from INPUT (k-point parallelism)
+ * @param[in] bndpar     BNDPAR from INPUT (band  parallelism)
+ * @param[in] diag_np    Number of diag worlds (also serves as group count
+ *                       for the real-space grid world: GRID_WORLD groups are
+ *                       the contiguous blocks produced by split_grid_world).
+ * @param[in] grid_np    Reserved; currently the real-space grid world is
+ *                       tied to diag_np via split_grid_world(diag_np, ...).
+ */
+ProcessTopology create_topology(int world_nproc,
+                                int my_rank,
+                                int kpar,
+                                int bndpar,
+                                int diag_np,
+                                int grid_np);
+
+
 /**-------------------------------------------
  * call to split the "diago world"
  * the unit of first proc of each grid group

source/source_base/test_parallel/CMakeLists.txt

@@ -1,13 +1,13 @@
 AddTest(
   TARGET MODULE_BASE_ParaCommon
   LIBS parameter MPI::MPI_CXX
-  SOURCES parallel_common_test.cpp ../global_variable.cpp ../parallel_common.cpp ../parallel_reduce.cpp ../parallel_comm.cpp ../parallel_global.cpp ../tool_quit.cpp ../global_file.cpp ../global_function.cpp ../memory_recorder.cpp ../timer.cpp
+  SOURCES parallel_common_test.cpp ../global_variable.cpp ../parallel_common.cpp ../parallel_reduce.cpp ../parallel_comm.cpp ../parallel_global.cpp ../parallel_topology.cpp ../tool_quit.cpp ../global_file.cpp ../global_function.cpp ../memory_recorder.cpp ../timer.cpp
 )
 
 AddTest(
   TARGET MODULE_BASE_ParaGlobal
   LIBS parameter MPI::MPI_CXX
-  SOURCES parallel_global_test.cpp ../global_variable.cpp ../parallel_global.cpp ../parallel_comm.cpp ../tool_quit.cpp  ../global_file.cpp ../global_function.cpp ../memory_recorder.cpp ../timer.cpp ../parallel_reduce.cpp
+  SOURCES parallel_global_test.cpp ../global_variable.cpp ../parallel_global.cpp ../parallel_comm.cpp ../tool_quit.cpp  ../global_file.cpp ../global_function.cpp ../memory_recorder.cpp ../timer.cpp ../parallel_reduce.cpp ../parallel_topology.cpp
 )
 
 AddTest(
@@ -19,7 +19,7 @@ AddTest(
 AddTest(
   TARGET MODULE_BASE_ParaReduce
   LIBS parameter MPI::MPI_CXX
-  SOURCES parallel_reduce_test.cpp ../global_variable.cpp ../parallel_global.cpp ../parallel_comm.cpp ../parallel_common.cpp ../parallel_reduce.cpp ../tool_quit.cpp ../global_file.cpp ../global_function.cpp ../memory_recorder.cpp ../timer.cpp
+  SOURCES parallel_reduce_test.cpp ../global_variable.cpp ../parallel_global.cpp ../parallel_comm.cpp ../parallel_common.cpp ../parallel_reduce.cpp ../tool_quit.cpp ../global_file.cpp ../global_function.cpp ../memory_recorder.cpp ../timer.cpp ../parallel_topology.cpp
 )
 
 install(FILES parallel_common_test.sh DESTINATION ${CMAKE_CURRENT_BINARY_DIR})

source/source_base/test_parallel/parallel_topology_test.cpp

@@ -308,4 +308,162 @@ TEST(ProcessTopology, ConstructAndAccessors)
 #endif
 }
 
+// Integration: Parallel_Global::create_topology builds a real topology
+// on a live MPI_COMM_WORLD. This test is only meaningful when run via
+// mpirun with exactly 4 ranks.
+TEST(ParallelGlobalCreateTopology, FourRanksKpar2Bndpar2DiagNp2)
+{
+    int world_size = 1;
+    int world_rank = 0;
+#ifdef __MPI
+    MPI_Comm_size(MPI_COMM_WORLD, &world_size);
+    MPI_Comm_rank(MPI_COMM_WORLD, &world_rank);
+#endif
+    if (world_size != 4)
+    {
+        GTEST_SKIP() << "create_topology integration case requires exactly 4 MPI ranks (got "
+                     << world_size << ").";
+    }
+    const int kpar = 2;
+    const int bndpar = 2;
+    const int diag_np = 2;
+    const int grid_np = 2; // reserved; topology today derives rgrid from diag_np
+    const ProcessTopology t = Parallel_Global::create_topology(
+        world_size, world_rank, kpar, bndpar, diag_np, grid_np);
+
+    // ---- scalar invariants (same for every rank) -------------------
+    EXPECT_EQ(t.world_size(), 4);
+    EXPECT_EQ(t.world_rank(), world_rank);
+    EXPECT_EQ(t.kpar(), 2);
+    EXPECT_EQ(t.bndpar(), 2);
+    EXPECT_EQ(t.bndpar() * t.nproc_in_band_group(), t.world_size());
+
+    // 4 ranks, KPAR=2 (even=false): nproc_in_pool = {2, 2}
+    ASSERT_EQ(static_cast<int>(t.nproc_in_pool().size()), 2);
+    EXPECT_EQ(t.nproc_in_pool(0), 2);
+    EXPECT_EQ(t.nproc_in_pool(1), 2);
+    EXPECT_EQ(t.pool_root_rank(0), 0);
+    EXPECT_EQ(t.pool_root_rank(1), 2);
+
+    // BNDPAR=2 (even=true) in each pool of 2 procs -> each bg gets 1 proc
+    // Global union bg size = kpar*1 = 2 = nproc_in_band_group
+    EXPECT_EQ(t.nproc_in_band_group(), 2);
+    EXPECT_EQ(t.band_group_root_rank(0), 0);
+    EXPECT_EQ(t.band_group_root_rank(1), 2); // band_group * nproc_in_band_group = 1 * 2
+
+    // ---- per-rank local values -------------------------------------
+    // World ranks 0..3, KPAR=2 (even=false) -> pools {0: {0,1}, 1: {2,3}}.
+    // BNDPAR=2 even split inside each pool -> for a pool of size 2,
+    // each band-group receives exactly 1 process (nprocs_in_group =
+    // pool_size / bndpar = 1). Therefore within every pool the
+    // bndpar-group rank_in_group is always 0 for whichever
+    // band-group the rank belongs to, and NPROC_IN_POOL (aka the
+    // band-group slice size per pool) equals 1 globally across all
+    // 4 ranks.
+    //
+    // Per-rank expected (verified by factory stdout against real
+    // divide_pools run on R0..R3):
+    //   wr | pool | rank_in_pool | band_group | rank_in_band_group
+    //    0 |   0  |       0      |     0      | pool*1 + 0 = 0
+    //    1 |   0  |       0      |     1      | pool*1 + 0 = 0
+    //    2 |   1  |       0      |     0      | pool*1 + 0 = 1
+    //    3 |   1  |       0      |     1      | pool*1 + 0 = 1
+    const int expected_pool = (world_rank < 2) ? 0 : 1;
+    const int expected_band_group = world_rank % 2; // bndpar even slices by world order inside pool
+    const int expected_rank_in_pool = 0; // 1 process per (pool, band-group) tile
+    const int expected_rk_in_bg = expected_pool * 1 + 0; // formula with nproc_per_bg_in_pool = 1
+
+    EXPECT_EQ(t.my_pool(), expected_pool);
+    EXPECT_EQ(t.rank_in_pool(), expected_rank_in_pool);
+    EXPECT_EQ(t.my_band_group(), expected_band_group);
+    EXPECT_EQ(t.rank_in_band_group(), expected_rk_in_bg);
+
+#ifdef __MPI
+    // ---- communicator sizes / memberships --------------------------
+    int size = -1;
+    int rk = -1;
+    // pw_world_comm : (same pool, same band group) intersection of
+    // 2x2 = 4 total PW tiles -> singleton size 1 each
+    ASSERT_NE(t.pw_world_comm(), MPI_COMM_NULL);
+    MPI_Comm_size(t.pw_world_comm(), &size);
+    MPI_Comm_rank(t.pw_world_comm(), &rk);
+    EXPECT_EQ(size, 1);
+    EXPECT_EQ(rk, 0);
+
+    // kmesh_world_comm (KP_WORLD inter_comm bridge): non-null only on
+    // ranks where rank_in_pool == 0 (pool 0 rank 0 = wr 0; pool 1 rank 0
+    // = wr 2) -> size 2 on those ranks, MPI_COMM_NULL otherwise.
+    if (t.rank_in_pool() == 0)
+    {
+        ASSERT_NE(t.kmesh_world_comm(), MPI_COMM_NULL);
+        MPI_Comm_size(t.kmesh_world_comm(), &size);
+        MPI_Comm_rank(t.kmesh_world_comm(), &rk);
+        EXPECT_EQ(size, kpar);
+        EXPECT_EQ(rk, t.my_pool()); // key order in inter_comm = my_group
+    }
+    else
+    {
+        EXPECT_EQ(t.kmesh_world_comm(), MPI_COMM_NULL);
+    }
+
+    // bsame_kdiff_world_comm (INT_BGROUP): same band group across all pools
+    // size = kpar * nproc_per_pool_per_bg = 2 * 1 = 2
+    ASSERT_NE(t.bsame_kdiff_world_comm(), MPI_COMM_NULL);
+    MPI_Comm_size(t.bsame_kdiff_world_comm(), &size);
+    MPI_Comm_rank(t.bsame_kdiff_world_comm(), &rk);
+    EXPECT_EQ(size, 2);
+    EXPECT_EQ(rk, t.rank_in_band_group()); // matches expected_rk_in_bg
+
+    // bdiff_ksame_world_comm (BP_WORLD duped): same pool, same
+    // rank_in_pool (i.e. rank_in_band_group value) pairs. With 2 bg in
+    // 1 pool of 2 processes, each BP_WORLD subgroup also has size 2.
+    ASSERT_NE(t.bdiff_ksame_world_comm(), MPI_COMM_NULL);
+    MPI_Comm_size(t.bdiff_ksame_world_comm(), &size);
+    MPI_Comm_rank(t.bdiff_ksame_world_comm(), &rk);
+    EXPECT_EQ(size, bndpar);
+    EXPECT_EQ(rk, t.my_band_group());
+
+    // rgrid_world_comm (GRID_WORLD): diag_np=2 groups, even=false -> 2+2
+    ASSERT_NE(t.rgrid_world_comm(), MPI_COMM_NULL);
+    MPI_Comm_size(t.rgrid_world_comm(), &size);
+    EXPECT_EQ(size, world_size / diag_np); // 4/2 = 2
+
+    // diag_world_comm (DIAG_WORLD): diag_np=2, divide_mpi_groups over
+    // nproc=4 groups=2 even=false -> groups {0,1} {2,3}; color = rank's
+    // in-group rank. All 4 ranks take part in MPI_Comm_split with
+    // their color so there are diag_np different DIAG_WORLD subgroups
+    // each of size diag_np = 2 (colors 0 & 1 both have 2 members:
+    // color 0 from {wr 0, 2}; color 1 from {wr 1, 3}).
+    ASSERT_NE(t.diag_world_comm(), MPI_COMM_NULL);
+    MPI_Comm_size(t.diag_world_comm(), &size);
+    MPI_Comm_rank(t.diag_world_comm(), &rk);
+    EXPECT_EQ(size, diag_np); // color 0 and 1 each 2 members
+    EXPECT_GE(rk, 0);
+    EXPECT_LT(rk, size);
+
+    // matrix / atom domains are caller-bound today -> must be null.
+    EXPECT_EQ(t.matrix_world_comm(), MPI_COMM_NULL);
+    EXPECT_EQ(t.atom_world_comm(), MPI_COMM_NULL);
+#endif
+}
+
+int main(int argc, char** argv)
+{
+#ifdef __MPI
+    MPI_Init(&argc, &argv);
+#endif
+    testing::InitGoogleTest(&argc, argv);
+    const int rc = RUN_ALL_TESTS();
+#ifdef __MPI
+    MPI_Finalize();
+#endif
+    return rc;
+}
+#else
+
+// Top-level test binary used when __MPI is not defined: fall back to
+// googletest's default main via link target. This branch is never
+// compiled in the normal unit-test build path because
+// MODULE_BASE_ProcessTopology links only under the __MPI build
+// configuration.
 #endif // __MPI

source/source_basis/module_pw/kernels/test/CMakeLists.txt

@@ -5,7 +5,7 @@ AddTest(
     LIBS parameter psi device
     SOURCES pw_op_test.cpp
     ../../../../source_base/tool_quit.cpp ../../../../source_base/global_variable.cpp
-    ../../../../source_base/parallel_global.cpp ../../../../source_base/parallel_reduce.cpp
+    ../../../../source_base/parallel_global.cpp ../../../../source_base/parallel_topology.cpp ../../../../source_base/parallel_reduce.cpp
     ../../../../source_base/parallel_comm.cpp
     ../../../../source_base/complexmatrix.cpp ../../../../source_base/matrix.cpp ../../../../source_base/memory_recorder.cpp
     ../../../../source_base/libm/branred.cpp ../../../../source_base/libm/sincos.cpp

source/source_cell/test/CMakeLists.txt

@@ -104,7 +104,7 @@ AddTest(
   TARGET MODULE_CELL_ParaKpoints
   LIBS MPI::MPI_CXX
   SOURCES parallel_kpoints_test.cpp ../../source_base/global_variable.cpp ../../source_base/parallel_global.cpp
-  	../../source_base/parallel_common.cpp ../../source_base/parallel_comm.cpp ../parallel_kpoints.cpp ../../source_base/tool_quit.cpp ../../source_base/global_variable.cpp ../../source_base/global_file.cpp ../../source_base/global_function.cpp ../../source_base/memory_recorder.cpp ../../source_base/timer.cpp ../../source_base/parallel_reduce.cpp
+  	../../source_base/parallel_topology.cpp ../../source_base/parallel_common.cpp ../../source_base/parallel_comm.cpp ../parallel_kpoints.cpp ../../source_base/tool_quit.cpp ../../source_base/global_variable.cpp ../../source_base/global_file.cpp ../../source_base/global_function.cpp ../../source_base/memory_recorder.cpp ../../source_base/timer.cpp ../../source_base/parallel_reduce.cpp
 )
 
 # Add unit test for read_atoms_helper

source/source_io/test/CMakeLists.txt

@@ -93,6 +93,7 @@ AddTest(
 	../../source_base/parallel_reduce.cpp
 	../../source_base/parallel_common.cpp
 	../../source_base/parallel_global.cpp
+	../../source_base/parallel_topology.cpp
   ../../source_base/parallel_comm.cpp
   ../../source_base/tool_quit.cpp ../../source_base/global_file.cpp ../../source_base/global_function.cpp ../../source_base/memory_recorder.cpp ../../source_base/timer.cpp
 )

source/source_md/test/CMakeLists.txt

@@ -59,6 +59,7 @@ list(APPEND depend_files
   ../../source_esolver/esolver_lj.cpp
   ../../source_base/parallel_reduce.cpp
   ../../source_base/parallel_global.cpp
+  ../../source_base/parallel_topology.cpp
   ../../source_base/parallel_cell.cpp
   ../../source_base/parallel_comm.cpp
   ../../source_cell/read_pp_ucell.cpp

source/source_pw/module_pwdft/test/CMakeLists.txt

@@ -17,6 +17,7 @@ AddTest(
 	../../../source_base/timer.cpp
 	../../../source_base/module_external/blas_connector_base.cpp ../../../source_base/module_external/blas_connector_vector.cpp ../../../source_base/module_external/blas_connector_matrix.cpp
 	../../../source_base/parallel_global.cpp
+	../../../source_base/parallel_topology.cpp
 	../../../source_base/parallel_comm.cpp
 	../../../source_base/parallel_common.cpp
 	../../../source_base/parallel_reduce.cpp