Refactor DFT+U step 2 (deepmodeling#7858)

* refactor(dftu): rename member locale/locale_save -> occ_mat/occ_mat_save (Step 1/5)

- Rename Plus_U_Base data members: locale -> occ_mat, locale_save -> occ_mat_save
- Update all direct member access sites in:
  * dftu_base.h inline get_locale/set_locale bodies and doc examples
  * dftu_base.cpp (init allocation, copy/zero/mix/set internal, flat conv,
    read_occup_m, local_occup_bcast MPI, Memory::record tag)
  * dftu_pw.cpp (cal_occ_pw: becp accumulation, k-pool reduce, VU & energy)
  * dftu.cpp (cal_energy_correction trace & double-counting terms)
  * dftu_occup.cpp (LCAO cal_occup_m_k/_gamma S*DM accumulation, MPI
    Allreduce, symmetrization via transpose)
  * dftu_tools.cpp (get_onebody_eff_pot new/saved branches)
  * test_dftu.cpp (setup resize/create, EXPECT assertions on values)
- Public API names (get_locale, set_locale, copy_locale, zero_locale,
  mix_locale, set_locale_flat, is_locale_initialized, etc.) are kept
  unchanged in this step to keep the change surface minimal.

7 files changed, 133 insertions(+), 133 deletions(-).

* refactor(dftu): rename get_locale/set_locale -> get_occ_mat/set_occ_mat (Step 2/5)

Rename the public single-element accessors of Plus_U_Base:
  get_locale(iat,l,n,spin,m1,m2) -> get_occ_mat(...)
  set_locale(iat,l,n,spin,m1,m2,val) -> set_occ_mat(...)

Update all 5 direct call sites:
  * dftu_output.cpp  (4 calls in dftu_io::write_occup_m for output)
  * dftu_lcao.cpp    (1 call in DFTU cal_occ fallback branch)

The protected batch overload set_locale(const UnitCell&) and the other
state/flat helpers (copy_locale, zero_locale, mix_locale, get_locale_flat,
set_locale_flat, is_locale_initialized, mark_*) are intentionally kept
unchanged and will be renamed in the following steps.

3 files changed, 7 insertions(+), 7 deletions(-).

* 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(-).

* refactor(dftu): rename protected copy/zero/mix/set_locale -> *_occ_mat (Step 4/5)

Rename the four protected internal helpers of Plus_U_Base and their
ModuleBase::TITLE / timer tag strings for consistency:
  copy_locale(ucell)             -> copy_occ_mat(ucell)
  zero_locale(ucell)             -> zero_occ_mat(ucell)
  mix_locale(ucell, mixing_beta) -> mix_occ_mat(ucell, mixing_beta)
  set_locale(ucell)              -> set_occ_mat(ucell)

The single-argument batch setter set_occ_mat(const UnitCell&) now
overloads the public element-wise setter set_occ_mat(iat,l,n,spin,m1,m2,val)
with a different signature — no ambiguity, no change to callers.

Declarations (dftu_base.h), definitions + internal call sites in
dftu_base.cpp (init_base flow, also all TITLE/timer labels), and
call sites in cal_occ_pw (dftu_pw.cpp) and cal_occup_m_{k,gamma}
(dftu_occup.cpp) are all updated together.

4 files changed, 32 insertions(+), 32 deletions(-).

* 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(-).

* refactor(dftu): move DFT+U operator from module_operator_lcao to module_dftu

Move DFTU/OperatorDFTU<OperatorLCAO> operator implementation files
(dftu.hpp, dftu_lcao.h/cpp, dftu_fs.cpp, op_dftu_lcao.h/cpp) and the
related unit test (test_dftu.cpp -> dftu_lcao_test.cpp) from
module_operator_lcao to module_dftu. This is a step toward removing
module_operator_lcao and grouping DFT+U code by physical domain.

CMake changes:
- module_dftu CMakeLists adds the 3 cpp files guarded by ENABLE_LCAO,
  since module_dftu is unconditionally added by source_lcao while
  these files depend on operator_lcao.h
- module_operator_lcao CMakeLists drops the 3 cpp files
- source_lcao CMakeLists drops the 3 cpp entries from the hamilt_lcao
  OBJECT library (now provided by the dftu OBJECT library)
- New dftu_lcao_test target guarded by ENABLE_LCAO AND ENABLE_MPI
  matches the original MODULE_LCAO_operator_dftu_test build condition

Include path updates in 5 external call sites plus op_dftu_lcao.h
internal operator_lcao.h path (changed from same-directory relative
to full path since the file is no longer co-located).

Verified: cmake configure, make abacus_max_para + dftu_lcao_test,
and ctest dftu_pw_test/dftu_core_test/dftu_operator_test/dftu_lcao_test
all pass; agent_governance_check reports only include-path change
warnings with no errors.

---------

Co-authored-by: abacus_fixer <mohanchen@pku.eud.cn>

Author: mohanchen

source/source_io/module_hs/write_vxc.hpp

@@ -4,7 +4,7 @@
 #include "source_base/parallel_reduce.h"
 #include "source_base/module_container/base/third_party/blas.h"
 #include "source_base/module_external/scalapack_connector.h"
-#include "source_lcao/module_operator_lcao/op_dftu_lcao.h"
+#include "source_lcao/module_dftu/op_dftu_lcao.h"
 #include "source_lcao/module_operator_lcao/veff_lcao.h"
 #include "source_hamilt/module_xc/exx_info.h"
 #ifdef __EXX

source/source_io/module_hs/write_vxc_r.hpp

@@ -2,7 +2,7 @@
 #define __WRITE_VXC_R_H_
 #include "source_io/module_parameter/parameter.h"
 #include "source_io/module_hs/write_hs_sparse.h"
-#include "source_lcao/module_operator_lcao/op_dftu_lcao.h"
+#include "source_lcao/module_dftu/op_dftu_lcao.h"
 #include "source_lcao/module_operator_lcao/veff_lcao.h"
 #include "source_lcao/spar_hsr.h"
 #ifdef __EXX

source/source_lcao/CMakeLists.txt

@@ -15,7 +15,6 @@ if(ENABLE_LCAO)
         module_operator_lcao/veff_lcao.cpp
         module_operator_lcao/veff_dh.cpp
         module_operator_lcao/meta_lcao.cpp
-        module_operator_lcao/op_dftu_lcao.cpp
         module_operator_lcao/deepks_lcao.cpp
         module_operator_lcao/op_exx_lcao.cpp
         module_operator_lcao/overlap.cpp
@@ -32,8 +31,6 @@ if(ENABLE_LCAO)
         module_operator_lcao/td_pot_hybrid_fs.cpp
         module_operator_lcao/dspin_lcao.cpp
         module_operator_lcao/dspin_fs.cpp
-        module_operator_lcao/dftu_lcao.cpp
-        module_operator_lcao/dftu_fs.cpp
         module_operator_lcao/operator_fs_utils.cpp
         setup_dftu_lcao.cpp
         pulay_fs_center2.cpp

source/source_lcao/force_stress_lcao.cpp

@@ -20,7 +20,7 @@
 #include "source_lcao/module_deepks/lcao_deepks_io.h" // mohan add 2024-07-22
 #include "source_lcao/module_deepks/deepks_force.h"
 #endif
-#include "source_lcao/module_operator_lcao/dftu_lcao.h"
+#include "source_lcao/module_dftu/dftu_lcao.h"
 #include "source_lcao/module_operator_lcao/dspin_lcao.h"
 #include "source_lcao/module_operator_lcao/nonlocal.h"
 #include "source_lcao/module_operator_lcao/ekinetic.h"

source/source_lcao/hamilt_lcao.cpp

@@ -31,12 +31,12 @@
 #include "source_lcao/module_deltaspin/spin_constrain.h"
 #include "source_hamilt/module_hcontainer/hcontainer_funcs.h"
 #include "source_hsolver/hsolver_lcao.h"
-#include "module_operator_lcao/dftu_lcao.h"
+#include "module_dftu/dftu_lcao.h"
 #include "module_operator_lcao/dspin_lcao.h"
 #include "module_operator_lcao/ekinetic.h"
 #include "module_operator_lcao/meta_lcao.h"
 #include "module_operator_lcao/nonlocal.h"
-#include "module_operator_lcao/op_dftu_lcao.h"
+#include "module_dftu/op_dftu_lcao.h"
 #include "module_operator_lcao/op_exx_lcao.h"
 #include "module_operator_lcao/overlap.h"
 #include "module_operator_lcao/td_ekinetic_lcao.h"

source/source_lcao/module_dftu/CMakeLists.txt

@@ -8,6 +8,14 @@ list(APPEND objects
       dftu_hamilt.cpp
 )
 
+if(ENABLE_LCAO)
+  list(APPEND objects
+        dftu_lcao.cpp
+        dftu_fs.cpp
+        op_dftu_lcao.cpp
+  )
+endif()
+
 add_library(
     dftu
     OBJECT

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;
@@ -158,11 +158,11 @@ void Plus_U::cal_energy_correction(const UnitCell& ucell,
 
                             for (int m0 = 0; m0 < 2 * l + 1; m0++)
                             {
-                                nm_trace += this->locale[iat][l][n][spin](m0, m0);
+                                nm_trace += this->occ_mat[iat][l][n][spin](m0, m0);
                                 for (int m1 = 0; m1 < 2 * l + 1; m1++)
                                 {
-                                    nm2_trace += this->locale[iat][l][n][spin](m0, m1)
-                                                 * this->locale[iat][l][n][spin](m1, m0);
+                                    nm2_trace += this->occ_mat[iat][l][n][spin](m0, m1)
+                                                 * this->occ_mat[iat][l][n][spin](m1, m0);
                                 }
                             }
                             if (Yukawa)
@@ -186,16 +186,16 @@ void Plus_U::cal_energy_correction(const UnitCell& ucell,
                             for (int ipol0 = 0; ipol0 < this->npol; ipol0++)
                             {
                                 const int m0_all = m0 + (2 * l + 1) * ipol0;
-                                nm_trace += this->locale[iat][l][n][0](m0_all, m0_all);
+                                nm_trace += this->occ_mat[iat][l][n][0](m0_all, m0_all);
 
                                 for (int m1 = 0; m1 < 2 * l + 1; m1++)
                                 {
                                     for (int ipol1 = 0; ipol1 < this->npol; ipol1++)
                                     {
                                         int m1_all = m1 + (2 * l + 1) * ipol1;
 
-                                        nm2_trace += this->locale[iat][l][n][0](m0_all, m1_all)
-                                                     * this->locale[iat][l][n][0](m1_all, m0_all);
+                                        nm2_trace += this->occ_mat[iat][l][n][0](m0_all, m1_all)
+                                                     * this->occ_mat[iat][l][n][0](m1_all, m0_all);
                                     }
                                 }
                             }
@@ -228,14 +228,14 @@ void Plus_U::cal_energy_correction(const UnitCell& ucell,
                                         {
                                             double VU = 0.0;
                                             VU = get_onebody_eff_pot(T, iat, l, n, is, m1_all, m2_all, false);
-                                            energy_dc += VU * this->locale[iat][l][n][is](m1_all, m2_all);
+                                            energy_dc += VU * this->occ_mat[iat][l][n][is](m1_all, m2_all);
                                         }
                                     }
                                     else if (Plus_U::nspin == 4)
                                     {
                                         double VU = 0.0;
                                         VU = get_onebody_eff_pot(T, iat, l, n, 0, m1_all, m2_all, false);
-                                        energy_dc += VU * this->locale[iat][l][n][0](m1_all, m2_all);
+                                        energy_dc += VU * this->occ_mat[iat][l][n][0](m1_all, m2_all);
                                     }
                                 }
                             }

…ource_lcao/module_operator_lcao/dftu.hpp source/source_lcao/module_dftu/dftu.hppsource/source_lcao/module_operator_lcao/dftu.hpp renamed to source/source_lcao/module_dftu/dftu.hpp source/source_lcao/module_operator_lcao/dftu.hpp renamed to source/source_lcao/module_dftu/dftu.hpp

@@ -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];

…ce_lcao/module_operator_lcao/dftu_fs.cpp …urce/source_lcao/module_dftu/dftu_fs.cppsource/source_lcao/module_operator_lcao/dftu_fs.cpp renamed to source/source_lcao/module_dftu/dftu_fs.cpp source/source_lcao/module_operator_lcao/dftu_fs.cpp renamed to source/source_lcao/module_dftu/dftu_fs.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;
     }