refactor(dftu): cleanup comments, tests, parameter names (Step 5/5)

Final cleanup pass to align naming after the locale -> occ_mat rename:

* dftu_lcao.cpp (~40 lines):
  - Replace identifier-style 'locale' / 'Locale' references in the
    contributeHR() doc block and inline comments with 'occ_mat' /
    'Occ_mat', including stale 'via get_locale()' / 'get_locale uses'
    mentions that no longer match the API.
  - Rename local bool flag locale_not_init -> occ_mat_not_init.

* dftu_pw.cpp (4 lines): Fix the 4 remaining comments that still
  referred to 'locale matrix' / 'reduce locale' / 'locale reduced'
  in the cal_occ_pw implementation notes.

* dftu_occup.cpp (2 lines): Update the top-of-file function inventory
  comment: set_locale(ucell) -> set_occ_mat(ucell); get/set_locale_flat
  -> get/set_occ_mat_flat.

* dftu_tools.cpp (12 lines): Rename bool parameter 'newlocale' ->
  'new_occ_mat' and its 3 internal uses in cal_VU_pot_mat_{complex,real}
  and get_onebody_eff_pot signatures/bodies, so the parameter name
  matches the occ_mat naming convention.

* dftu_core_test.cpp (28 lines):
  - copy_locale_to_flat -> copy_occ_mat_to_flat (def + 3 call sites)
  - set_locale_from_flat -> set_occ_mat_from_flat (def + 3 call sites)
  - LocaleRoundtripTest -> OccMatRoundtripTest (test fixture + 2 TEST_F)
  - Related header comments: 'copy_locale <-> set_locale roundtrip',
    'nested locale matrix' updated accordingly.

* dftu_pw_test.cpp (6 lines):
  - 'Locale accumulation from becp' -> 'Occupation matrix accumulation
    from becp' in the test description;
  - 'set_locale is tested via integration tests.' -> 'set_occ_mat is
    tested via integration tests.'

Not touched: pure semantic/mathematical local variable names inside
the test helpers (locale_up, locale_dn, locale_c, compute_vu(locale_val),
compute_energy(locale_flat), etc.) - these are local symbolic
placeholders independent of the Plus_U_Base member naming.

6 files changed, 49 insertions(+), 49 deletions(-).

Author: abacus_fixer

source/source_lcao/module_dftu/dftu_occup.cpp

@@ -6,8 +6,8 @@
 #endif
 #include "source_base/module_external/scalapack_connector.h"
 
-// copy_occ_mat(), zero_occ_mat(), mix_occ_mat(), set_locale(ucell),
-// get_locale_flat(), set_locale_flat()
+// copy_occ_mat(), zero_occ_mat(), mix_occ_mat(), set_occ_mat(ucell),
+// get_occ_mat_flat(), set_occ_mat_flat()
 // are now implemented in dftu_base.cpp as Plus_U_Base methods (inherited by Plus_U).
 
 #ifdef __LCAO

source/source_lcao/module_dftu/dftu_tools.cpp

@@ -3,7 +3,7 @@
 #include "source_io/module_parameter/parameter.h"
 
 #ifdef __LCAO
-void Plus_U::cal_VU_pot_mat_complex(const int spin, const bool newlocale, std::complex<double>* VU, const int npol)
+void Plus_U::cal_VU_pot_mat_complex(const int spin, const bool new_occ_mat, std::complex<double>* VU, const int npol)
 {
     ModuleBase::TITLE("Plus_U", "cal_VU_pot_mat_complex");
     ModuleBase::GlobalFunc::ZEROS(VU, this->paraV->nloc);
@@ -53,7 +53,7 @@ void Plus_U::cal_VU_pot_mat_complex(const int spin, const bool newlocale, std::c
                                     }
                                     int m1_all = m1 + (2 * L + 1) * ipol1;
                                     int m2_all = m2 + (2 * L + 1) * ipol2;
-                                    double val = get_onebody_eff_pot(it, iat, L, n, spin, m1_all, m2_all, newlocale);
+                                    double val = get_onebody_eff_pot(it, iat, L, n, spin, m1_all, m2_all, new_occ_mat);
                                     VU[nu * this->paraV->nrow + mu] = std::complex<double>(val, 0.0);
                                 } // ipol2
                             } // m2
@@ -67,7 +67,7 @@ void Plus_U::cal_VU_pot_mat_complex(const int spin, const bool newlocale, std::c
     return;
 }
 
-void Plus_U::cal_VU_pot_mat_real(const int spin, const bool newlocale, double* VU, const int npol)
+void Plus_U::cal_VU_pot_mat_real(const int spin, const bool new_occ_mat, double* VU, const int npol)
 {
     ModuleBase::TITLE("Plus_U", "cal_VU_pot_mat_real");
     ModuleBase::GlobalFunc::ZEROS(VU, this->paraV->nloc);
@@ -118,7 +118,7 @@ void Plus_U::cal_VU_pot_mat_real(const int spin, const bool newlocale, double* V
                                     int m2_all = m2 + (2 * L + 1) * ipol2;
 
                                     VU[nu * this->paraV->nrow + mu]
-                                        = this->get_onebody_eff_pot(it, iat, L, n, spin, m1_all, m2_all, newlocale);
+                                        = this->get_onebody_eff_pot(it, iat, L, n, spin, m1_all, m2_all, new_occ_mat);
 
                                 } // ipol2
                             } // m2
@@ -139,7 +139,7 @@ double Plus_U::get_onebody_eff_pot(const int T,
                                  const int spin,
                                  const int m0,
                                  const int m1,
-                                 const bool newlocale)
+                                 const bool new_occ_mat)
 {
     ModuleBase::TITLE("Plus_U", "get_onebody_eff_pot");
 
@@ -156,7 +156,7 @@ double Plus_U::get_onebody_eff_pot(const int T,
         break;
 
     case 3: // simplified formalism and FLL double counting
-        if (newlocale)
+        if (new_occ_mat)
         {
             if (Yukawa)
             {

source/source_lcao/module_dftu/test/dftu_core_test.cpp

@@ -10,7 +10,7 @@
  *
  * These tests target the most complex and bug-prone logic:
  * 1. eff_pot_pw_index calculation for mixed atom types and nspin modes
- * 2. copy_locale <-> set_locale roundtrip (3 data layouts)
+ * 2. copy_occ_mat <-> set_occ_mat roundtrip (3 data layouts)
  * 3. VU effective potential formula (cal_type=3, FLL)
  * 4. Energy correction and double-counting terms
  ***********************************************************************/
@@ -88,9 +88,9 @@ TEST_F(EffPotIndexTest, Nspin2and4_SplitAndPauli)
 }
 
 // =====================================================================
-// 2. copy_locale <-> set_locale roundtrip
+// 2. copy_occ_mat <-> set_occ_mat roundtrip
 //
-// Tests the bidirectional conversion between nested locale matrix
+// Tests the bidirectional conversion between nested occ_mat matrix
 // and flat uom_array/uom_save arrays for all 3 nspin modes.
 // =====================================================================
 
@@ -103,7 +103,7 @@ struct Matrix2D {
     const double& operator()(int i, int j) const { return data[i * nc + j]; }
 };
 
-static void copy_locale_to_flat(
+static void copy_occ_mat_to_flat(
     const std::vector<Matrix2D>& locale_up,
     const std::vector<Matrix2D>& locale_dn,
     std::vector<double>& uom_save,
@@ -143,7 +143,7 @@ static void copy_locale_to_flat(
     }
 }
 
-static void set_locale_from_flat(
+static void set_occ_mat_from_flat(
     const std::vector<double>& uom_array,
     std::vector<Matrix2D>& locale_up,
     std::vector<Matrix2D>& locale_dn,
@@ -183,13 +183,13 @@ static void set_locale_from_flat(
     }
 }
 
-class LocaleRoundtripTest : public ::testing::Test
+class OccMatRoundtripTest : public ::testing::Test
 {
   protected:
     void SetUp() override {}
 };
 
-TEST_F(LocaleRoundtripTest, Nspin1and2_SingleAndSplitLayout)
+TEST_F(OccMatRoundtripTest, Nspin1and2_SingleAndSplitLayout)
 {
     // nspin=1: single atom d-orbital roundtrip
     const int l = 2;
@@ -202,8 +202,8 @@ TEST_F(LocaleRoundtripTest, Nspin1and2_SingleAndSplitLayout)
 
     std::vector<int> eff_pot_pw_index = {0};
     std::vector<double> uom_save(size, 0.0);
-    copy_locale_to_flat(locale_up, locale_dn, uom_save, eff_pot_pw_index, 1);
-    set_locale_from_flat(uom_save, locale_up, locale_dn, eff_pot_pw_index, 1);
+    copy_occ_mat_to_flat(locale_up, locale_dn, uom_save, eff_pot_pw_index, 1);
+    set_occ_mat_from_flat(uom_save, locale_up, locale_dn, eff_pot_pw_index, 1);
     for (int i = 0; i < size; i++)
         EXPECT_DOUBLE_EQ(locale_up[0].data[i], static_cast<double>(i + 1));
 
@@ -215,22 +215,22 @@ TEST_F(LocaleRoundtripTest, Nspin1and2_SingleAndSplitLayout)
         locale_dn[0].data[i] = static_cast<double>(i + 100);
     }
     uom_save.assign(total, 0.0);
-    copy_locale_to_flat(locale_up, locale_dn, uom_save, eff_pot_pw_index, 2);
+    copy_occ_mat_to_flat(locale_up, locale_dn, uom_save, eff_pot_pw_index, 2);
     // Verify split layout
     for (int i = 0; i < size; i++)
     {
         EXPECT_DOUBLE_EQ(uom_save[i], static_cast<double>(i + 1));
         EXPECT_DOUBLE_EQ(uom_save[size + i], static_cast<double>(i + 100));
     }
-    set_locale_from_flat(uom_save, locale_up, locale_dn, eff_pot_pw_index, 2);
+    set_occ_mat_from_flat(uom_save, locale_up, locale_dn, eff_pot_pw_index, 2);
     for (int i = 0; i < size; i++)
     {
         EXPECT_DOUBLE_EQ(locale_up[0].data[i], static_cast<double>(i + 1));
         EXPECT_DOUBLE_EQ(locale_dn[0].data[i], static_cast<double>(i + 100));
     }
 }
 
-TEST_F(LocaleRoundtripTest, Nspin4_PauliBlocks)
+TEST_F(OccMatRoundtripTest, Nspin4_PauliBlocks)
 {
     // 2 atoms: d(l=2), p(l=1)
     struct AtomSpec { int l; };
@@ -265,8 +265,8 @@ TEST_F(LocaleRoundtripTest, Nspin4_PauliBlocks)
     std::vector<double> uom_array(total, 0.0);
     std::vector<Matrix2D> locale_dn(specs.size()); // unused for nspin=4
 
-    copy_locale_to_flat(locale, locale_dn, uom_array, eff_pot_pw_index, 4);
-    set_locale_from_flat(uom_array, locale, locale_dn, eff_pot_pw_index, 4);
+    copy_occ_mat_to_flat(locale, locale_dn, uom_array, eff_pot_pw_index, 4);
+    set_occ_mat_from_flat(uom_array, locale, locale_dn, eff_pot_pw_index, 4);
 
     for (size_t i = 0; i < specs.size(); i++)
         for (int j = 0; j < sizes[i]; j++)

source/source_lcao/module_dftu/test/dftu_pw_test.cpp

@@ -12,13 +12,13 @@
  *   2. Becp index logic: different index formulas for nspin=1/2 vs nspin=4
  *   3. VU effective potential: cal_occ_pw VU calculation for all nspin modes
  *   4. Energy calculation: E_U accumulation with correct weights
- *   5. Locale accumulation from becp: the core loop of cal_occ_pw
+ *   5. Occupation matrix accumulation from becp: the core loop of cal_occ_pw
  *   6. Multi-atom split layout: [all_up | all_dn] layout for nspin=2
  *   7. OnsitePsOp kernel: vu application to ps for npol=1
  *
  * Strategy: test energy weights and becp index logic as pure
  * arithmetic — no need to link against full ABACUS libraries.
- * set_locale is tested via integration tests.
+ * set_occ_mat is tested via integration tests.
  ***********************************************************************/
 
 class DftuPwTest : public ::testing::Test
@@ -215,7 +215,7 @@ TEST_F(DftuPwTest, EnergyNspin4_WithOffDiagonal)
 }
 
 // =====================================================================
-// Locale accumulation from becp (cal_occ_pw core loop)
+// Occupation matrix accumulation from becp (cal_occ_pw core loop)
 // =====================================================================
 
 TEST_F(DftuPwTest, LocaleAccumNspin12)

source/source_lcao/module_operator_lcao/dftu_lcao.cpp

@@ -177,23 +177,23 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::cal_nlm_all(const Parallel_Orbi
  * @brief Contribute DFT+U Hamiltonian to real-space HR matrix
  * 
  * @details This function handles different scenarios based on:
- * 1. Whether locale (occupation matrix) is read from file (is_occ_mat_initialized)
+ * 1. Whether occ_mat (occupation matrix) is read from file (is_occ_mat_initialized)
  * 2. Spin configuration (nspin=1, 2, or 4)
  * 3. SCF iteration stage (first vs subsequent iterations)
  * 
- * Case 1: Locale NOT initialized (!is_occ_mat_initialized)
+ * Case 1: Occ_mat NOT initialized (!is_occ_mat_initialized)
  *   - First electronic iteration: calculates occupation matrix from density matrix (DMR)
  *     * Uses get_dmr(current_spin) to get real-space density matrix
  *     * Accumulates contributions from all atom pairs via cal_occ()
  *     * Performs MPI reduction to sum occ across processes
  *     * Stores result via set_occ_mat_flat() for use in VU calculation
  *     * For nspin=1: occ is scaled by 0.5 (since only one spin channel computed)
- *   - Subsequent iterations: locale is computed fresh each iteration from updated DMR
+ *   - Subsequent iterations: occ_mat is computed fresh each iteration from updated DMR
  * 
- * Case 2: Locale IS initialized (is_occ_mat_initialized, i.e., read from dm_onsite.txt file)
- *   - First electronic iteration: uses pre-read locale directly without DMR calculation
+ * Case 2: Occ_mat IS initialized (is_occ_mat_initialized, i.e., read from dm_onsite.txt file)
+ *   - First electronic iteration: uses pre-read occ_mat directly without DMR calculation
  *     * Skips DMR-based occ calculation entirely
- *     * Reads locale from stored data via get_locale()
+ *     * Reads locale from stored data via get_occ_mat()
  *     * Different indexing for nspin=4 vs nspin=1/2 (see below)
  *   - After first iteration: mark_occ_mat_dirty() is called to force recomputation
  * 
@@ -212,7 +212,7 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::cal_nlm_all(const Parallel_Orbi
  *   nspin=4 (non-collinear/SOC):
  *     - Single 4x4 Pauli matrix representation per atom
  *     - occ has 4*(2l+1)^2 elements (spin_fold=4)
- *     - get_locale uses spin=0, ipol indices for Pauli blocks
+ *     - get_occ_mat uses spin=0, ipol indices for Pauli blocks
  *     - mark_occ_mat_dirty() always called (current_spin check always true)
  *     - No current_spin toggling (all spins handled simultaneously)
  * 
@@ -228,12 +228,12 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::contributeHR()
     ModuleBase::TITLE("DFTU", "contributeHR");
     // Early exit conditions:
     // - get_dmr(0) == nullptr: DMR not available (typical in first iteration without file input)
-    // - !is_occ_mat_initialized(): locale not read from file AND not yet computed from DMR
+    // - !is_occ_mat_initialized(): occ_mat not read from file AND not yet computed from DMR
     // When both true, skip DFT+U contribution entirely (first iteration, no file input)
     const bool dmr_null = (this->dftu->get_dmr(0) == nullptr);
-    const bool locale_not_init = !this->dftu->is_occ_mat_initialized();
+    const bool occ_mat_not_init = !this->dftu->is_occ_mat_initialized();
 
-    if (dmr_null && locale_not_init)
+    if (dmr_null && occ_mat_not_init)
     {
         return;
     }
@@ -277,7 +277,7 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::contributeHR()
         std::vector<double> occ(tlp1 * tlp1 * spin_fold, 0.0);
 
         // ============================================================
-        // BRANCH 1: Locale NOT initialized (compute from DMR)
+        // BRANCH 1: Occ_mat NOT initialized (compute from DMR)
         // ============================================================
         // This branch is taken when:
         // - is_occ_mat_initialized() == false (no file read or omc != 0)
@@ -331,32 +331,32 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::contributeHR()
             this->dftu->set_occ_mat_flat(iat0, target_L, this->current_spin, occ);
         }
         // ============================================================
-        // BRANCH 2: Locale IS initialized (use pre-read data)
+        // BRANCH 2: Occ_mat IS initialized (use pre-read data)
         // ============================================================
         // This branch is taken when:
-        // - is_occ_mat_initialized() == true (locale read from dm_onsite.txt file)
+        // - is_occ_mat_initialized() == true (occ_mat read from dm_onsite.txt file)
         // - OR omc != 0 (occupation matrix control with dm_onsite_ini.txt)
         // Typical scenario: first SCF iteration with file input, or restart calculation
         else
         {
             // nspin=4: Non-collinear case with Pauli matrix representation
-            // Locale stored as single 4x4 block per atom, with spin indices embedded
+            // Occ_mat stored as single 4x4 block per atom, with spin indices embedded
             // in the matrix indices (ipol0, ipol1 for Pauli block indices)
             if (this->nspin == 4)
             {
-                // For nspin=4, locale is stored as 4 stacked tlp1^2 blocks
+                // For nspin=4, occ_mat is stored as 4 stacked tlp1^2 blocks
                 // at offsets 0, tlp1^2, 2*tlp1^2, 3*tlp1^2 for the 4 Pauli channels.
                 // Use get_occ_mat_flat to read the stacked blocks directly
                 this->dftu->get_occ_mat_flat(iat0, target_L, occ);
             }
             // nspin=1 or nspin=2: Collinear spin case
-            // Locale stored separately for each spin channel
+            // Occ_mat stored separately for each spin channel
             else
             {
                 for (int i = 0; i < static_cast<int>(occ.size()); i++)
                 {
                     // TODO: UNSAFE - current_spin must be correct for nspin=2.
-                    // If current_spin is not toggled properly, wrong spin channel's locale is read.
+                    // If current_spin is not toggled properly, wrong spin channel's occ_mat is read.
                     // This can happen if contributeHR() is called out of expected order.
                     occ[i] = this->dftu->get_occ_mat(iat0, target_L, 0, this->current_spin,
                                                       i / (2 * target_L + 1), i % (2 * target_L + 1));
@@ -428,21 +428,21 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::contributeHR()
         ModuleBase::timer::end("DFTU", "cal_vu");
     }
 
-    // 6. Post-processing: Energy correction and locale state management
+    // 6. Post-processing: Energy correction and occ_mat state management
     // For nspin=1: DFT+U energy computed for single spin channel, but should count both spins
     // set_double_energy() doubles the energy to account for degenerate spin-up/down
 	if (this->nspin == 1) 
 	{
         this->dftu->set_double_energy();
 	}
 
-    // 7. Mark locale as dirty to force recomputation in next iteration
+    // 7. Mark occ_mat as dirty to force recomputation in next iteration
     // This is called when:
     // - nspin=4: Always (all spins handled simultaneously, current_spin==0==nspin-1)
     // - nspin=2: When current_spin==1 (after spin-down calculation, last spin channel)
     // - nspin=1: When current_spin==0==nspin-1 (always called)
     // 
-    // Purpose: Ensure locale is recomputed from updated DMR in next SCF iteration,
+    // Purpose: Ensure occ_mat is recomputed from updated DMR in next SCF iteration,
     // rather than using stale pre-read data from file.
     // TODO: This logic is confusing. Consider explicit variable like `is_last_spin_channel`.
 	if (this->current_spin == this->nspin - 1 || this->nspin == 4) 

source/source_pw/module_pwdft/dftu_pw.cpp

@@ -16,7 +16,7 @@
 ///   spin channel selected by `isk[ik]` (not ik >= nk/2, which fails for kpar>1);
 ///
 /// nspin=4 (npol=2): spinor calculation;
-///   locale has a single matrix of size (2*tlp1) x (2*tlp1) per atom
+///   occ_mat has a single matrix of size (2*tlp1) x (2*tlp1) per atom
 ///   storing all 4 Pauli blocks contiguously.
 void Plus_U_Base::cal_occ_pw(const int iter,
             const void* psi_in,
@@ -188,7 +188,7 @@ void Plus_U_Base::cal_occ_pw(const int iter,
     }
 #endif
 
-    // reduce locale from all k-pools
+    // reduce occ_mat from all k-pools
     for(int iat = 0; iat < cell.nat; iat++)
     {
         const int it = cell.iat2it[iat];
@@ -221,7 +221,7 @@ void Plus_U_Base::cal_occ_pw(const int iter,
                     size * 4);
         }
 
-        // save locale matrix for this iat to uom_array
+        // save occ_mat matrix for this iat to uom_array
         if(this->uom_array.size() != 0)
         {
             for(int mm=0;mm<size;mm++)
@@ -249,7 +249,7 @@ void Plus_U_Base::cal_occ_pw(const int iter,
     Plus_U_Base::energy_u = 0.0;
     const double weight_eu = (Plus_U_Base::nspin == 1) ? 1.0 : (Plus_U_Base::nspin == 2) ? 0.5 : 0.25;
     const double diag_coeff = (Plus_U_Base::nspin == 4) ? 1.0 : 0.5;
-    // calculate VU and energy (locale already reduced above)
+    // calculate VU and energy (occ_mat already reduced above)
     for(int iat = 0; iat < cell.nat; iat++)
     {
         const int it = cell.iat2it[iat];