Resolve CI/CD failure

Author: AsTonyshment

docs/advanced/input_files/input-main.md

@@ -683,7 +683,7 @@
 - **Availability**: *([`basis_type`](#basis_type)==pw and [`esolver_type`](#esolver_type)==sdft) or ([`basis_type`](#basis_type)==pw and [`esolver_type`](#esolver_type)==ksdft and [`ks_solver`](#ks_solver)==bpcg)*
 - **Description**: Controls band-group parallelism for PW SDFT and PW KSDFT calculations using the BPCG eigensolver.
   - Within each k-point pool, divide the MPI processes into bndpar band groups. Each group contains NPROC / (kpar * bndpar) processes when bndpar is greater than 1.
-  - With BPCG, distribute contiguous ranges of global Kohn-Sham bands among the band groups. nbands does not need to be divisible by bndpar; groups with lower indices receive one additional band when necessary.
+  - With BPCG, distribute contiguous ranges of global Kohn-Sham bands among the band groups. nbands does not need to be divisible by bndpar, but bndpar cannot exceed a positive nbands. Groups with lower indices receive one additional band when necessary.
   - In SDFT, distribute stochastic orbitals among the band groups. When the deterministic Kohn-Sham eigensolver is not BPCG, band group 0 calculates the deterministic orbitals and broadcasts them to the other groups.
   - bndpar must be positive and no greater than the number of MPI processes. When bndpar is greater than 1, kpar * bndpar must divide the number of MPI processes exactly.
   > Note: For PW calculations on GPU, if the input kpar * bndpar differs from the number of MPI processes, ABACUS automatically sets the effective kpar to NPROC / bndpar.

docs/parameters.yaml

@@ -113,7 +113,7 @@ parameters:
     description: |
       Controls band-group parallelism for PW SDFT and PW KSDFT calculations using the BPCG eigensolver.
       * Within each k-point pool, divide the MPI processes into bndpar band groups. Each group contains NPROC / (kpar * bndpar) processes when bndpar is greater than 1.
-      * With BPCG, distribute contiguous ranges of global Kohn-Sham bands among the band groups. nbands does not need to be divisible by bndpar; groups with lower indices receive one additional band when necessary.
+      * With BPCG, distribute contiguous ranges of global Kohn-Sham bands among the band groups. nbands does not need to be divisible by bndpar, but bndpar cannot exceed a positive nbands. Groups with lower indices receive one additional band when necessary.
       * In SDFT, distribute stochastic orbitals among the band groups. When the deterministic Kohn-Sham eigensolver is not BPCG, band group 0 calculates the deterministic orbitals and broadcasts them to the other groups.
       * bndpar must be positive and no greater than the number of MPI processes. When bndpar is greater than 1, kpar * bndpar must divide the number of MPI processes exactly.
       [NOTE] For PW calculations on GPU, if the input kpar * bndpar differs from the number of MPI processes, ABACUS automatically sets the effective kpar to NPROC / bndpar.

source/source_cell/cal_atoms_info.h

@@ -143,6 +143,11 @@ class CalAtomsInfo
         result.nbands = nbands;
         unitcell::cal_nbands(static_cast<int>(result.nelec), result.nlocal, nelec_spin, result.nbands,
                               esolver_type, lspinorb, nspin, basis_type, smearing_method);
+        // Taoni add check for bndpar > nbands on 2026-08-21
+        if (ks_solver == "bpcg" && result.nbands > 0 && bndpar > result.nbands)
+        {
+            ModuleBase::WARNING_QUIT("CalAtomsInfo", "bndpar cannot exceed nbands when ks_solver is bpcg");
+        }
 
         // calculate the number of nbands_local
         result.nbands_l = result.nbands;

source/source_cell/parallel_kpoints.cpp

@@ -5,7 +5,6 @@
 #include "parallel_kpoints.h"
 
 #include "source_base/parallel_common.h"
-#include "source_base/parallel_comm.h"
 #include "source_base/parallel_global.h"
 
 /// @note the kpoints here are reduced after symmetry applied.
@@ -114,18 +113,20 @@ void Parallel_Kpoints::set_startpro_pool()
     return;
 }
 
-
 // gather kpoints from all processor pools, only need to be called by the first processor of each pool.
 void Parallel_Kpoints::gatherkvec(const std::vector<ModuleBase::Vector3<double>>& vec_local,
                                   std::vector<ModuleBase::Vector3<double>>& vec_global) const
 {
+    int world_rank = 0;
+    MPI_Comm_rank(MPI_COMM_WORLD, &world_rank);
     // Taoni fix bndpar on 2026-08-21
-    int band_rank = 0;
-    MPI_Comm_rank(BP_WORLD, &band_rank);
+    // rank_in_pool is repeated in every band group under BPCG. The first
+    // world rank of the k-point pool instead identifies one unique contributor.
+    const bool is_pool_root = (world_rank == this->startpro_pool[this->my_pool]);
     vec_global.resize(this->nkstot_np, ModuleBase::Vector3<double>(0.0, 0.0, 0.0));
     for (int i = 0; i < this->nks_np; ++i)
     {
-        if (this->rank_in_pool == 0 && band_rank == 0)
+        if (is_pool_root)
         {
             vec_global[i + startk_pool[this->my_pool]] = vec_local[i];
         }
@@ -157,7 +158,6 @@ void Parallel_Kpoints::pool_collection(double& value, const double* wk, const in
             {
                 MPI_Status ierror;
                 MPI_Recv(&value, 1, MPI_DOUBLE, this->startpro_pool[pool], ik, MPI_COMM_WORLD, &ierror);
-
             }
         }
         else
@@ -218,7 +218,7 @@ void Parallel_Kpoints::pool_collection_aux(T* value, const V& w, const int& dim,
     T* p = &w.ptr[begin];
     // temprary restrict kpar=1 for NSPIN=2 case for generating_orbitals
     int pool = 0;
-    if (this->nspin != 2) 
+    if (this->nspin != 2)
     {
         pool = this->whichpool[ik];
     }

source/source_io/module_energy/band_parallel_output.cpp

@@ -3,6 +3,7 @@
 #include "source_base/global_function.h"
 #include "source_base/parallel_comm.h"
 
+#include <algorithm>
 #include <numeric>
 #include <vector>
 
@@ -12,7 +13,10 @@
 
 ModuleBase::matrix ModuleIO::gather_band_matrix(const ModuleBase::matrix& local_matrix, const int global_nbands)
 {
-    assert(global_nbands > 0);
+    if (global_nbands < 0)
+    {
+        ModuleBase::WARNING_QUIT("ModuleIO::gather_band_matrix", "global band count cannot be negative");
+    }
 #ifndef __MPI
     if (local_matrix.nc != global_nbands)
     {
@@ -22,17 +26,29 @@ ModuleBase::matrix ModuleIO::gather_band_matrix(const ModuleBase::matrix& local_
 #else
     int band_groups = 0;
     MPI_Comm_size(BP_WORLD, &band_groups);
-    if (band_groups == 1)
+    std::vector<int> band_counts(band_groups);
+    std::vector<int> row_counts(band_groups);
+    MPI_Allgather(&local_matrix.nc, 1, MPI_INT, band_counts.data(), 1, MPI_INT, BP_WORLD);
+    MPI_Allgather(&local_matrix.nr, 1, MPI_INT, row_counts.data(), 1, MPI_INT, BP_WORLD);
+
+    // SDFT without BPCG replicates all deterministic bands across band groups,
+    // whereas BPCG stores complementary column ranges. All ranks inspect the
+    // same gathered shapes before choosing a path, preventing rank-divergent
+    // collectives for uneven band distributions.
+    const bool rows_match
+        = std::all_of(row_counts.begin(), row_counts.end(), [&local_matrix](const int rows) { return rows == local_matrix.nr; });
+    if (!rows_match)
+    {
+        ModuleBase::WARNING_QUIT("ModuleIO::gather_band_matrix", "band groups have inconsistent row counts");
+    }
+
+    const bool bands_are_replicated
+        = std::all_of(band_counts.begin(), band_counts.end(), [global_nbands](const int bands) { return bands == global_nbands; });
+    if (bands_are_replicated)
     {
-        if (local_matrix.nc != global_nbands)
-        {
-            ModuleBase::WARNING_QUIT("ModuleIO::gather_band_matrix", "local band count does not match global nbands");
-        }
         return local_matrix;
     }
 
-    std::vector<int> band_counts(band_groups);
-    MPI_Allgather(&local_matrix.nc, 1, MPI_INT, band_counts.data(), 1, MPI_INT, BP_WORLD);
     const int gathered_nbands = std::accumulate(band_counts.begin(), band_counts.end(), 0);
     if (gathered_nbands != global_nbands)
     {

source/source_io/module_energy/band_parallel_output.h

@@ -7,11 +7,15 @@ namespace ModuleIO
 {
 
 /**
- * @brief Reconstruct global band columns from a contiguous band distribution.
+ * @brief Obtain a complete band matrix from replicated or distributed input.
  *
- * @param local_matrix Matrix whose columns are locally owned bands.
+ * Band groups may either hold identical complete column ranges, as in SDFT
+ * without BPCG, or complementary contiguous ranges, as in BPCG. An empty
+ * matrix is valid when the calculation has no deterministic bands.
+ *
+ * @param local_matrix Complete or locally owned band columns.
  * @param global_nbands Expected global number of bands.
- * @return Matrix with all global band columns on every rank in BP_WORLD.
+ * @return Complete matrix on every rank in BP_WORLD.
  */
 ModuleBase::matrix gather_band_matrix(const ModuleBase::matrix& local_matrix, const int global_nbands);
 

source/source_io/module_parameter/read_inp_sys.cpp

@@ -339,7 +339,7 @@ void ReadInput::item_system()
         item.type = "Integer";
         item.description = R"(Controls band-group parallelism for PW SDFT and PW KSDFT calculations using the BPCG eigensolver.
 * Within each k-point pool, divide the MPI processes into bndpar band groups. Each group contains NPROC / (kpar * bndpar) processes when bndpar is greater than 1.
-* With BPCG, distribute contiguous ranges of global Kohn-Sham bands among the band groups. nbands does not need to be divisible by bndpar; groups with lower indices receive one additional band when necessary.
+* With BPCG, distribute contiguous ranges of global Kohn-Sham bands among the band groups. nbands does not need to be divisible by bndpar, but bndpar cannot exceed a positive nbands. Groups with lower indices receive one additional band when necessary.
 * In SDFT, distribute stochastic orbitals among the band groups. When the deterministic Kohn-Sham eigensolver is not BPCG, band group 0 calculates the deterministic orbitals and broadcasts them to the other groups.
 * bndpar must be positive and no greater than the number of MPI processes. When bndpar is greater than 1, kpar * bndpar must divide the number of MPI processes exactly.
 [NOTE] For PW calculations on GPU, if the input kpar * bndpar differs from the number of MPI processes, ABACUS automatically sets the effective kpar to NPROC / bndpar.)";