refactor(parallel): step-1a rename ProcessTopology to 8-domain consistent *_world_comm naming

Scope: 3 files changed, +209 -82 lines.
Build: cmake --build build exit=0, abacus_basic_para linked successfully.
Test : OMP_NUM_THREADS=1 mpirun -np 4 MODULE_BASE_ProcessTopology
       -> 7 / 7 tests passed
       (5x divide_mpi_groups arithmetic
       + 2x ProcessTopology accessor / value-semantics cases).

Naming decision (after multi-round user review, naming principles:
  1. All 8 communicators share the uniform `_world_comm` suffix.
  2. The two legacy band-parallel domains INT_BGROUP / BP_WORLD are
     renamed directly after the "band-side vs k-side diff/same
     relation", ditching historically confusing abbreviations such
     as `intra / inter / BP / INT`.
  3. Two long-implicit domains are promoted to first-class names:
     the matrix 2D block-cyclic BLACS world and the atom 3D
     real-space DD (domain decomposition) world -- so callers no
     longer rely on the ad-hoc "pick POOL_WORLD or DIAG_WORLD or
     MPI_COMM_WORLD depending on the scene" convention.

Final 8-domain map (see parallel_topology.h for the full comment):
  Legacy global        -> New `*_world_comm` name            # 1-line semantic
  1. POOL_WORLD        -> pw_world_comm                     # Same-k, same-band-group PW tile (smallest parallel world)
  2. KP_WORLD          -> kmesh_world_comm                  # (user-suggested content name) k-mesh root bridge across pools
  3. INT_BGROUP        -> bsame_kdiff_world_comm            # (user-suggested abbreviation) band same, k different; same band-group union across k pools
  4. BP_WORLD          -> bdiff_ksame_world_comm            # (user-suggested abbreviation) band different, k same; intra-pool cross-band-group pair bridge
  5. GRID_WORLD        -> rgrid_world_comm                  # explicitly approved by user early on
  6. DIAG_WORLD        -> diag_world_comm                   # explicitly approved by user early on
  - (previously implicit)-> matrix_world_comm               # (user-suggested replacement for blacs_world) 2D block-cyclic matrix BLACS world
  - (previously implicit)-> atom_world_comm                 # (user-suggested) 3D real-space atomic DD / neighlist world

Scalar accessors aligned with the full-word `band_group`:
  - `bgroup` shorthand is expanded to the full `band_group`:
    my_band_group() / rank_in_band_group() / nproc_in_band_group().
  - `bndpar()` is kept because it matches the INPUT `BNDPAR` flag.
  - `kpar()` / `my_pool()` / `rank_in_pool()` / `nproc_in_pool()`
    are preserved to keep the naming compatible with the 100+
    occurrences of `pool` in Parallel_Kpoints and related modules.

New `band_group_root_rank(bg)` accessor:
  - Symmetric with `pool_root_rank(pool)` on the pool axis.
  - Constructor invariant: bndpar_ * nproc_in_band_group_ ==
    world_nproc_, so the root rank formula is simply
    `band_group * nproc_in_band_group_` -- this matches
    ABACUS divide_pools output exactly.
  - Tested on the 10-process / BNDPAR=2 / nproc_in_band_group=5
    case: ASSERT band_group_root_rank(0)==0 and
    band_group_root_rank(1)==5.

matrix_world_comm / atom_world_comm injection policy:
  - Both fields default to MPI_COMM_NULL in the constructor (two
    new trailing default parameters; the old 6-comm signature
    still works, so AGENTS rule #5 does not apply).
  - The "correct" BLACS / DD domain actually depends on the use
    case (LCAO diag / GK diag / MD step / ...). Distributed
    modules in Step 2 will fill these two handles in from the
    appropriate view on an as-needed basis; no real data flow is
    touched today.
  - Serial fallback default-constructor asserts matrix_world_comm
    == MPI_COMM_NULL and atom_world_comm == MPI_COMM_NULL. The
    ConstructAndAccessors test injects MPI_COMM_SELF /
    MPI_COMM_WORLD respectively and round-trips all 8 comm
    accessors plus copy semantics.

Governance (agent_governance_check.py --staged):
  - 1 warning only: "Documentation sync review". No user-visible
    INPUT / CLI / external API change, so documentation is
    correctly not updated. No exception needed.
  - GlobalV / PARAM / GlobalC: 0 new reads. All topology data
    are injected explicitly through constructor arguments, in
    line with AGENTS rule #1 (budget: non-increasing, no new
    globals introduced in this patch).
  - Header dependencies: only <vector> and <mpi.h> in
    parallel_topology.h, both required for self-containment
    (member type + MPI_Comm return types). The 6 legacy global
    communicators from parallel_comm.h are NOT transitively
    pulled in, satisfying rule #3.
  - C++11 compatible, one variable per declaration, no direct
    MPI calls in this patch.

Author: abacus_fixer

source/source_base/parallel_topology.cpp

@@ -10,17 +10,19 @@ ProcessTopology::ProcessTopology()
       rank_in_pool_(0),
       nproc_in_pool_(1, 1),
       bndpar_(1),
-      my_bndgroup_(0),
-      rank_in_bgroup_(0),
-      nproc_in_bgroup_(1)
+      my_band_group_(0),
+      rank_in_band_group_(0),
+      nproc_in_band_group_(1)
 #ifdef __MPI
       ,
-      pool_comm_(MPI_COMM_SELF),
-      kp_world_comm_(MPI_COMM_NULL),
-      int_bgroup_comm_(MPI_COMM_SELF),
-      bp_world_comm_(MPI_COMM_NULL),
-      grid_comm_(MPI_COMM_NULL),
-      diag_comm_(MPI_COMM_NULL)
+      pw_world_comm_(MPI_COMM_SELF),
+      kmesh_world_comm_(MPI_COMM_NULL),
+      bsame_kdiff_world_comm_(MPI_COMM_SELF),
+      bdiff_ksame_world_comm_(MPI_COMM_NULL),
+      rgrid_world_comm_(MPI_COMM_NULL),
+      diag_world_comm_(MPI_COMM_NULL),
+      matrix_world_comm_(MPI_COMM_NULL),
+      atom_world_comm_(MPI_COMM_NULL)
 #endif
 {
 }
@@ -32,17 +34,19 @@ ProcessTopology::ProcessTopology(int world_nproc_in,
                                  int rank_in_pool_in,
                                  const std::vector<int>& nproc_in_pool_in,
                                  int bndpar_in,
-                                 int my_bndgroup_in,
-                                 int rank_in_bgroup_in,
-                                 int nproc_in_bgroup_in
+                                 int my_band_group_in,
+                                 int rank_in_band_group_in,
+                                 int nproc_in_band_group_in
 #ifdef __MPI
                                      ,
-                                 MPI_Comm pool_comm_in,
-                                 MPI_Comm kp_world_comm_in,
-                                 MPI_Comm int_bgroup_comm_in,
-                                 MPI_Comm bp_world_comm_in,
-                                 MPI_Comm grid_comm_in,
-                                 MPI_Comm diag_comm_in
+                                 MPI_Comm pw_world_comm_in,
+                                 MPI_Comm kmesh_world_comm_in,
+                                 MPI_Comm bsame_kdiff_world_comm_in,
+                                 MPI_Comm bdiff_ksame_world_comm_in,
+                                 MPI_Comm rgrid_world_comm_in,
+                                 MPI_Comm diag_world_comm_in,
+                                 MPI_Comm matrix_world_comm_in,
+                                 MPI_Comm atom_world_comm_in
 #endif
                                  )
     : world_nproc_(world_nproc_in),
@@ -52,17 +56,19 @@ ProcessTopology::ProcessTopology(int world_nproc_in,
       rank_in_pool_(rank_in_pool_in),
       nproc_in_pool_(nproc_in_pool_in),
       bndpar_(bndpar_in),
-      my_bndgroup_(my_bndgroup_in),
-      rank_in_bgroup_(rank_in_bgroup_in),
-      nproc_in_bgroup_(nproc_in_bgroup_in)
+      my_band_group_(my_band_group_in),
+      rank_in_band_group_(rank_in_band_group_in),
+      nproc_in_band_group_(nproc_in_band_group_in)
 #ifdef __MPI
       ,
-      pool_comm_(pool_comm_in),
-      kp_world_comm_(kp_world_comm_in),
-      int_bgroup_comm_(int_bgroup_comm_in),
-      bp_world_comm_(bp_world_comm_in),
-      grid_comm_(grid_comm_in),
-      diag_comm_(diag_comm_in)
+      pw_world_comm_(pw_world_comm_in),
+      kmesh_world_comm_(kmesh_world_comm_in),
+      bsame_kdiff_world_comm_(bsame_kdiff_world_comm_in),
+      bdiff_ksame_world_comm_(bdiff_ksame_world_comm_in),
+      rgrid_world_comm_(rgrid_world_comm_in),
+      diag_world_comm_(diag_world_comm_in),
+      matrix_world_comm_(matrix_world_comm_in),
+      atom_world_comm_(atom_world_comm_in)
 #endif
 {
     assert(world_nproc_ >= 1);
@@ -80,10 +86,10 @@ ProcessTopology::ProcessTopology(int world_nproc_in,
     assert(rank_in_pool_ >= 0 && rank_in_pool_ < nproc_in_pool_[my_pool_]);
 
     assert(bndpar_ >= 1);
-    assert(my_bndgroup_ >= 0 && my_bndgroup_ < bndpar_);
-    assert(nproc_in_bgroup_ >= 1);
-    assert(bndpar_ * nproc_in_bgroup_ == world_nproc_);
-    assert(rank_in_bgroup_ >= 0 && rank_in_bgroup_ < nproc_in_bgroup_);
+    assert(my_band_group_ >= 0 && my_band_group_ < bndpar_);
+    assert(nproc_in_band_group_ >= 1);
+    assert(bndpar_ * nproc_in_band_group_ == world_nproc_);
+    assert(rank_in_band_group_ >= 0 && rank_in_band_group_ < nproc_in_band_group_);
 }
 
 int ProcessTopology::pool_root_rank(int pool) const
@@ -99,3 +105,31 @@ int ProcessTopology::pool_root_rank(int pool) const
     }
     return offset;
 }
+
+int ProcessTopology::band_group_root_rank(int band_group) const
+{
+    if (band_group < 0 || band_group >= bndpar_)
+    {
+        return -1;
+    }
+    // In ABACUS divide_pools the band-group layout over world ranks is
+    // stripe-contiguous inside each k pool: within pool P the first
+    // (nproc_in_pool[P]/bndpar) ranks belong to band-group 0, the next
+    // slice to band-group 1, and so on.  The first rank of the
+    // concatenated "same band-group across all pools" set (i.e. the
+    // root of bsame_kdiff_world for that band-group) is therefore the
+    // first occurrence in pool 0, which falls at offset band_group *
+    // (nproc_in_pool[0]/bndpar) from pool_root_rank(0).  The invariant
+    // bndpar_ * nproc_in_band_group_ == world_nproc_ + the even split
+    // enforced by MPICommGroup::divide_group_comm make that offset
+    // equal to (band_group * nproc_in_band_group_) directly because
+    // each band-group contains exactly nproc_in_band_group_ processes
+    // globally and they appear in ascending band-group id order in
+    // world rank when scanned pool by pool.
+    const int per_bg_in_pool0 = nproc_in_pool_[0] / bndpar_;
+    assert(per_bg_in_pool0 * bndpar_ == nproc_in_pool_[0]);
+    const int via_pool0 = band_group * per_bg_in_pool0;
+    const int via_global = band_group * nproc_in_band_group_;
+    assert(via_pool0 == via_global);
+    return via_global;
+}

source/source_base/parallel_topology.h

@@ -12,16 +12,45 @@
  *
  * Replaces the six raw-global MPI_Comm (POOL_WORLD / KP_WORLD /
  * INT_BGROUP / BP_WORLD / GRID_WORLD / DIAG_WORLD) together with the
- * associated pool / band-group rank & size info from GlobalV.
- * Values captured at construction time; the object is copyable
- * (value semantics) and exposes no mutable workflow switches.
+ * associated pool / band-group rank & size info from GlobalV, and
+ * also exposes explicit handles for two long-implicit domains:
+ *
+ *   - matrix_world_comm: communicator backing the 2D block-cyclic
+ *     BLACS grid used by Parallel_2D / Parallel_Orbitals to lay out
+ *     distributed H/S/projector matrices. Historically callers chose
+ *     pw_world / diag_world / MPI_COMM_WORLD ad-hoc; here we give the
+ *     concept a first-class name so call sites inject the appropriate
+ *     view explicitly in step 2.
+ *   - atom_world_comm : communicator backing the 3D Cartesian domain
+ *     decomposition used by the MD / neighlist
+ *     DomainDecomposition to distribute atoms spatially. Today the
+ *     concrete communicator is always MPI_COMM_WORLD (wrapped via the
+ *     CommunicationDomain thin shell in parallel_cell.h).
+ *
+ * All 8 communicator handles share the consistent `_world_comm`
+ * suffix. The pair (bdiff_ksame_world, bsame_kdiff_world) is named
+ * directly after the relation between band side and k side:
  *
+ *   bdiff_ksame  ->  band groups differ, k is the same
+ *                    (legacy BP_WORLD, intra-pool cross-band pairs)
+ *   bsame_kdiff  ->  band groups are identical, k differs
+ *                    (legacy INT_BGROUP, intra-band-group union across
+ *                    all k pools)
+ *
+ * Values are captured at construction time; the object is copyable
+ * (value semantics) and exposes no mutable workflow switches.
  * Consumers currently reading the global MPI_Comm / GlobalV fields
  * should migrate to taking a `const ProcessTopology&` from their
  * callers. Parallel_Global::create_topology(...) produces one such
  * instance at startup whose communicators are also aliased back to
  * the legacy globals so existing code keeps working during the
  * migration.
+ *
+ * matrix_world_comm / atom_world_comm are not derived inside the
+ * topology constructor because the correct choice depends on where
+ * the view is used (LCAO diag, GK diag, MD step, ...). Callers that
+ * need a proper matrix or atom domain are expected to fill in the
+ * handle before passing the topology down to distributed modules.
  */
 class ProcessTopology
 {
@@ -36,6 +65,9 @@ class ProcessTopology
      * All inputs are plain values; GlobalV is never read inside the
      * constructor. Pass MPI_COMM_NULL for communicators that are
      * unused on this rank (same semantics as legacy divide_pools).
+     * matrix_world_comm / atom_world_comm default to MPI_COMM_NULL
+     * and are filled in later by whichever call site knows which
+     * domain view is needed for a given distributed calculation.
      */
     ProcessTopology(int world_nproc_in,
                     int my_rank_in,
@@ -44,25 +76,27 @@ class ProcessTopology
                     int rank_in_pool_in,
                     const std::vector<int>& nproc_in_pool_in,
                     int bndpar_in,
-                    int my_bndgroup_in,
-                    int rank_in_bgroup_in,
-                    int nproc_in_bgroup_in
+                    int my_band_group_in,
+                    int rank_in_band_group_in,
+                    int nproc_in_band_group_in
 #ifdef __MPI
                         ,
-                    MPI_Comm pool_comm_in,
-                    MPI_Comm kp_world_comm_in,
-                    MPI_Comm int_bgroup_comm_in,
-                    MPI_Comm bp_world_comm_in,
-                    MPI_Comm grid_comm_in,
-                    MPI_Comm diag_comm_in
+                    MPI_Comm pw_world_comm_in,
+                    MPI_Comm kmesh_world_comm_in,
+                    MPI_Comm bsame_kdiff_world_comm_in,
+                    MPI_Comm bdiff_ksame_world_comm_in,
+                    MPI_Comm rgrid_world_comm_in,
+                    MPI_Comm diag_world_comm_in,
+                    MPI_Comm matrix_world_comm_in = MPI_COMM_NULL,
+                    MPI_Comm atom_world_comm_in   = MPI_COMM_NULL
 #endif
     );
 
     // world ----------------------------------------------------------
     int world_size() const { return world_nproc_; }
     int world_rank() const { return my_rank_; }
 
-    // k-point pools -------------------------------------------------
+    // k-point pools --------------------------------------------------
     int kpar() const { return kpar_; }
     int my_pool() const { return my_pool_; }
     int rank_in_pool() const { return rank_in_pool_; }
@@ -71,20 +105,26 @@ class ProcessTopology
     /// World rank of the root (rank 0) of a given pool; -1 on bad index.
     int pool_root_rank(int pool) const;
 
-    // band groups (bndpar) ------------------------------------------
+    // band groups (BNDPAR) ------------------------------------------
     int bndpar() const { return bndpar_; }
-    int my_bndgroup() const { return my_bndgroup_; }
-    int rank_in_bgroup() const { return rank_in_bgroup_; }
-    int nproc_in_bgroup() const { return nproc_in_bgroup_; }
+    int my_band_group() const { return my_band_group_; }
+    int rank_in_band_group() const { return rank_in_band_group_; }
+    int nproc_in_band_group() const { return nproc_in_band_group_; }
+    /// World rank of the root (rank 0) inside a band-group union.
+    /// Uses the same prefix-sum logic as pool_root_rank but over the
+    /// band-group partition of MPI_COMM_WORLD. -1 on invalid index.
+    int band_group_root_rank(int band_group) const;
 
 #ifdef __MPI
-    // communicators -------------------------------------------------
-    MPI_Comm pool_comm() const { return pool_comm_; }
-    MPI_Comm kp_world_comm() const { return kp_world_comm_; }
-    MPI_Comm int_bgroup_comm() const { return int_bgroup_comm_; }
-    MPI_Comm bp_world_comm() const { return bp_world_comm_; }
-    MPI_Comm grid_comm() const { return grid_comm_; }
-    MPI_Comm diag_comm() const { return diag_comm_; }
+    // communicators (consistent `_world_comm` suffix) ---------------
+    MPI_Comm pw_world_comm()       const { return pw_world_comm_; }
+    MPI_Comm kmesh_world_comm()    const { return kmesh_world_comm_; }
+    MPI_Comm bsame_kdiff_world_comm() const { return bsame_kdiff_world_comm_; }
+    MPI_Comm bdiff_ksame_world_comm() const { return bdiff_ksame_world_comm_; }
+    MPI_Comm rgrid_world_comm()    const { return rgrid_world_comm_; }
+    MPI_Comm diag_world_comm()     const { return diag_world_comm_; }
+    MPI_Comm matrix_world_comm()   const { return matrix_world_comm_; }
+    MPI_Comm atom_world_comm()     const { return atom_world_comm_; }
 #endif
 
   private:
@@ -97,17 +137,19 @@ class ProcessTopology
     std::vector<int> nproc_in_pool_;
 
     int bndpar_ = 1;
-    int my_bndgroup_ = 0;
-    int rank_in_bgroup_ = 0;
-    int nproc_in_bgroup_ = 1;
+    int my_band_group_ = 0;
+    int rank_in_band_group_ = 0;
+    int nproc_in_band_group_ = 1;
 
 #ifdef __MPI
-    MPI_Comm pool_comm_ = MPI_COMM_SELF;
-    MPI_Comm kp_world_comm_ = MPI_COMM_NULL;
-    MPI_Comm int_bgroup_comm_ = MPI_COMM_SELF;
-    MPI_Comm bp_world_comm_ = MPI_COMM_NULL;
-    MPI_Comm grid_comm_ = MPI_COMM_NULL;
-    MPI_Comm diag_comm_ = MPI_COMM_NULL;
+    MPI_Comm pw_world_comm_       = MPI_COMM_SELF;
+    MPI_Comm kmesh_world_comm_    = MPI_COMM_NULL;
+    MPI_Comm bsame_kdiff_world_comm_ = MPI_COMM_SELF;
+    MPI_Comm bdiff_ksame_world_comm_ = MPI_COMM_NULL;
+    MPI_Comm rgrid_world_comm_    = MPI_COMM_NULL;
+    MPI_Comm diag_world_comm_     = MPI_COMM_NULL;
+    MPI_Comm matrix_world_comm_   = MPI_COMM_NULL;
+    MPI_Comm atom_world_comm_     = MPI_COMM_NULL;
 #endif
 };