refactor(dftu): rename flat/state funcs + fix initialed_locale spelling (Step 3/5)

Rename Plus_U_Base flat-conversion and state-management APIs:
  get_locale_flat        -> get_occ_mat_flat
  set_locale_flat        -> set_occ_mat_flat
  is_locale_initialized  -> is_occ_mat_initialized
  mark_locale_initialized-> mark_occ_mat_initialized
  mark_locale_dirty      -> mark_occ_mat_dirty

Also fix a long-standing spelling bug: the member variable
  bool initialed_locale
was renamed to
  bool occ_mat_initialized
(initialed -> initialized + naming aligned with occ_mat_* convention).

Header declarations updated in dftu_base.h, plus definitions and all
call sites updated across:
  * dftu_base.cpp    (defs + mark_locale_initialized calls in init_base)
  * dftu_lcao.cpp    (~16 call sites + doc comments)
  * dftu_fs.cpp      (1 get_occ_mat_flat call)
  * dftu_hamilt.cpp  (2 is_occ_mat_initialized calls)
  * setup_dftu_lcao.cpp (1 mark_occ_mat_initialized call)
  * dftu_occup.cpp   (is/mark calls in cal_occup_m_*)
  * dftu.cpp         (1 is_occ_mat_initialized call in cal_energy_correction)

8 files changed, 36 insertions(+), 36 deletions(-).

Author: abacus_fixer

source/source_lcao/module_dftu/dftu.cpp

@@ -105,7 +105,7 @@ void Plus_U::cal_energy_correction(const UnitCell& ucell,
 {
     ModuleBase::TITLE("Plus_U", "cal_energy_correction");
     ModuleBase::timer::start("Plus_U", "cal_energy_correction");
-    if (!is_locale_initialized())
+    if (!is_occ_mat_initialized())
     {
         ModuleBase::timer::end("Plus_U", "cal_energy_correction");
         return;

source/source_lcao/module_dftu/dftu_hamilt.cpp

@@ -12,7 +12,7 @@ void Plus_U::cal_eff_pot_mat_complex(const int ik,
 		const int npol)
 {
     ModuleBase::TITLE("Plus_U", "cal_eff_pot_c");
-    if (!is_locale_initialized())
+    if (!is_occ_mat_initialized())
     {
         return;
     }
@@ -65,7 +65,7 @@ void Plus_U::cal_eff_pot_mat_complex(const int ik,
 void Plus_U::cal_eff_pot_mat_real(const int ik, double* eff_pot, const std::vector<int>& isk, const double* sk, const int npol)
 {
     ModuleBase::TITLE("Plus_U", "cal_eff_pot_r");
-    if (!is_locale_initialized())
+    if (!is_occ_mat_initialized())
     {
         return;
     }

source/source_lcao/module_dftu/dftu_occup.cpp

@@ -236,12 +236,12 @@ void Plus_U::cal_occup_m_k(const int iter,
         } // end ia
     } // end it
 
-    if(is_mixing_enabled() && is_locale_initialized())
+    if(is_mixing_enabled() && is_occ_mat_initialized())
     {
         this->mix_locale(ucell,mixing_beta);
     }
 
-    mark_locale_initialized();
+    mark_occ_mat_initialized();
     ModuleBase::timer::end("Plus_U", "cal_occup_m_k");
     return;
 }
@@ -393,12 +393,12 @@ void Plus_U::cal_occup_m_gamma(const int iter,
         } // it
     } // is
 
-    if(is_mixing_enabled() && is_locale_initialized())
+    if(is_mixing_enabled() && is_occ_mat_initialized())
     {
         this->mix_locale(ucell,mixing_beta);
     }
 
-    mark_locale_initialized();
+    mark_occ_mat_initialized();
     ModuleBase::timer::end("Plus_U", "cal_occup_m_gamma");
     return;
 }

source/source_lcao/module_operator_lcao/dftu_fs.cpp

@@ -138,7 +138,7 @@ void DFTU<OperatorLCAO<TK, TR>>::cal_force_stress(const bool cal_force,
         }
         // first iteration to calculate occupation matrix
         std::vector<double> occ(tlp1 * tlp1 * this->nspin, 0);
-        this->dftu->get_locale_flat(iat0, target_L, occ);
+        this->dftu->get_occ_mat_flat(iat0, target_L, occ);
 
         // calculate VU
         const double u_value = this->dftu->U[T0];

source/source_lcao/module_operator_lcao/dftu_lcao.cpp

@@ -177,25 +177,25 @@ 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_locale_initialized)
+ * 1. Whether locale (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_locale_initialized)
+ * Case 1: Locale 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_locale_flat() for use in VU calculation
+ *     * 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
  * 
- * Case 2: Locale IS initialized (is_locale_initialized, i.e., read from dm_onsite.txt file)
+ * 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
  *     * Skips DMR-based occ calculation entirely
  *     * Reads locale from stored data via get_locale()
  *     * Different indexing for nspin=4 vs nspin=1/2 (see below)
- *   - After first iteration: mark_locale_dirty() is called to force recomputation
+ *   - After first iteration: mark_occ_mat_dirty() is called to force recomputation
  * 
  * Spin configurations:
  *   nspin=1 (non-spin-polarized):
@@ -206,14 +206,14 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::cal_nlm_all(const Parallel_Orbi
  *   nspin=2 (collinear spin-polarized):
  *     - Two separate spin channels (spin-up: 0, spin-down: 1)
  *     - current_spin toggles between 0 and 1 across iterations
- *     - mark_locale_dirty() called when current_spin == 1 (last spin)
+ *     - mark_occ_mat_dirty() called when current_spin == 1 (last spin)
  *     - HR accumulated separately for each spin
  *   
  *   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
- *     - mark_locale_dirty() always called (current_spin check always true)
+ *     - mark_occ_mat_dirty() always called (current_spin check always true)
  *     - No current_spin toggling (all spins handled simultaneously)
  * 
  * @warning THREAD SAFETY: cal_HR_IJR() updates shared HR matrix entries.
@@ -228,10 +228,10 @@ 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_locale_initialized(): locale not read from file AND not yet computed from DMR
+    // - !is_occ_mat_initialized(): locale 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_locale_initialized();
+    const bool locale_not_init = !this->dftu->is_occ_mat_initialized();
 
     if (dmr_null && locale_not_init)
     {
@@ -280,10 +280,10 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::contributeHR()
         // BRANCH 1: Locale NOT initialized (compute from DMR)
         // ============================================================
         // This branch is taken when:
-        // - is_locale_initialized() == false (no file read or omc != 0)
+        // - is_occ_mat_initialized() == false (no file read or omc != 0)
         // - DMR is available (get_dmr() != nullptr)
         // Typical scenario: normal SCF iterations after first step
-        if (!this->dftu->is_locale_initialized())
+        if (!this->dftu->is_occ_mat_initialized())
         {
             // TODO: UNSAFE - get_dmr(current_spin) assumes DMR has correct spin indexing.
             // For nspin=2, current_spin must be correctly toggled (0 then 1).
@@ -328,13 +328,13 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::contributeHR()
             {
                 for (auto& v : occ) { v *= 0.5; }
             }
-            this->dftu->set_locale_flat(iat0, target_L, this->current_spin, occ);
+            this->dftu->set_occ_mat_flat(iat0, target_L, this->current_spin, occ);
         }
         // ============================================================
         // BRANCH 2: Locale IS initialized (use pre-read data)
         // ============================================================
         // This branch is taken when:
-        // - is_locale_initialized() == true (locale read from dm_onsite.txt file)
+        // - is_occ_mat_initialized() == true (locale 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
@@ -346,8 +346,8 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::contributeHR()
             {
                 // For nspin=4, locale 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_locale_flat to read the stacked blocks directly
-                this->dftu->get_locale_flat(iat0, target_L, occ);
+                // 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
@@ -447,7 +447,7 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::contributeHR()
     // TODO: This logic is confusing. Consider explicit variable like `is_last_spin_channel`.
 	if (this->current_spin == this->nspin - 1 || this->nspin == 4) 
 	{
-		this->dftu->mark_locale_dirty();
+		this->dftu->mark_occ_mat_dirty();
 	}
 
     // 8. Spin channel toggling for nspin=2

source/source_lcao/setup_dftu_lcao.cpp

@@ -73,7 +73,7 @@ void finish_dftu_lcao(const int iter,
     /// use the converged occupation matrix for next MD/Relax SCF calculation
     if (conv_esolver)
     {
-        dftu_ptr->mark_locale_initialized();
+        dftu_ptr->mark_occ_mat_initialized();
     }
 }
 

source/source_pw/module_pwdft/dftu_base.cpp

@@ -238,7 +238,7 @@ void Plus_U_Base::init_base(UnitCell& cell,
         this->local_occup_bcast(cell, nspin, npol);
 #endif
 
-        mark_locale_initialized();
+        mark_occ_mat_initialized();
         this->copy_locale(cell);
     }
     else
@@ -251,7 +251,7 @@ void Plus_U_Base::init_base(UnitCell& cell,
 #ifdef __MPI
             this->local_occup_bcast(cell, nspin, npol);
 #endif
-            mark_locale_initialized();
+            mark_occ_mat_initialized();
         }
         else
         {
@@ -487,7 +487,7 @@ void Plus_U_Base::set_locale(const UnitCell& ucell)
 }
 
 
-void Plus_U_Base::get_locale_flat(const int iat, const int l, std::vector<double>& occ) const
+void Plus_U_Base::get_occ_mat_flat(const int iat, const int l, std::vector<double>& occ) const
 {
     const int tlp1 = 2 * l + 1;
     const int size = tlp1 * tlp1;
@@ -511,7 +511,7 @@ void Plus_U_Base::get_locale_flat(const int iat, const int l, std::vector<double
 }
 
 
-void Plus_U_Base::set_locale_flat(const int iat, const int l, const int spin,
+void Plus_U_Base::set_occ_mat_flat(const int iat, const int l, const int spin,
                                    const std::vector<double>& occ)
 {
     for (int i = 0; i < static_cast<int>(occ.size()); i++)

source/source_pw/module_pwdft/dftu_base.h

@@ -134,12 +134,12 @@ class Plus_U_Base
         return eff_pot_pw.size();
     }
 
-    // dftu can be calculated only after locale has been initialed
-    bool initialed_locale = false;
+    // dftu can be calculated only after occ_mat has been initialized
+    bool occ_mat_initialized = false;
 
-    bool is_locale_initialized() const { return initialed_locale; }
-    void mark_locale_initialized() { initialed_locale = true; }
-    void mark_locale_dirty() { initialed_locale = false; }
+    bool is_occ_mat_initialized() const { return occ_mat_initialized; }
+    void mark_occ_mat_initialized() { occ_mat_initialized = true; }
+    void mark_occ_mat_dirty() { occ_mat_initialized = false; }
 
     static bool is_mixing_enabled() { return mixing_dftu != 0; }
     static void enable_mixing() { mixing_dftu = 1; }
@@ -180,10 +180,10 @@ class Plus_U_Base
     /// nspin=1: fills occ with occ_mat[iat][l][0][0] data
     /// nspin=2: fills occ with interleaved occ_mat[iat][l][0][0] and [1] data
     /// nspin=4: fills occ with occ_mat[iat][l][0][0] data (all 4 Pauli blocks)
-    void get_locale_flat(const int iat, const int l, std::vector<double>& occ) const;
+    void get_occ_mat_flat(const int iat, const int l, std::vector<double>& occ) const;
 
     /// set flat occupation matrix for an atom's correlated orbital (write-back)
-    void set_locale_flat(const int iat, const int l, const int spin,
+    void set_occ_mat_flat(const int iat, const int l, const int spin,
                         const std::vector<double>& occ);
 
     // local occupancy matrix of the correlated subspace