DFT+U refactor, step 6 (deepmodeling#7879)

* Slim down Plus_U_Base interface in dftu_base.h

- Remove dead members with no callers: get_u_target,
  get_orbital_corr_data, deprecated get_pot_uterm_pw(iat),
  element-wise set_occ_mat, and mix_occ_mat (occupation mixing now
  goes through Charge_Mixing::mix_uom + sync_occ_to_uom)
- Merge duplicate occ_mat_initialized accessors: keep the is_*/mark_*
  pair and update dftu_lcao_occ.cpp call sites accordingly
- Replace unitcell.h/charge_mixing.h includes with forward
  declarations in dftu_base.h; add explicit includes to units that
  relied on them transitively (dftu_base.cpp, dftu_cal_occ_pw.cpp,
  dftu_output.cpp) and parallel_comm.h to stodft/hsolver units that
  used BP_WORLD/POOL_WORLD/INT_BGROUP indirectly

Verified: full incremental build of all targets passes with no
errors; repo-wide grep confirms no remaining references to the
removed symbols.

* Fix: include parallel_comm.h for BP_WORLD in hsolver tests

test_hsolver_sdft.cpp and diago_bpcg_test.cpp use BP_WORLD without
including source_base/parallel_comm.h, which broke the MPI build.

* Refactor DFT+U base: unify DFTU_BASE namespace and slim Plus_U_Base

- Rename dftu_output.{h,cpp} -> dftu_base_io.{h,cpp},
  dftu_tools_pw.{h,cpp} -> dftu_base_tools.{h,cpp},
  dftu_cal_occ_pw.cpp -> dftu_base_occ.cpp (git mv)
- Unify all DFTU-related free functions in module_pwdft under a single
  namespace DFTU_BASE (formerly dftu_io, dftu_pw, and pw::iter_init_dftu_pw)
- Extract read_occup_m and local_occup_bcast from Plus_U_Base as
  DFTU_BASE:: free functions declared in dftu_base_io.h; dependencies
  (occ_mat, orbital_corr, occ_mat_ctrl) are now passed explicitly
- Replace element-wise MPI_Bcast in local_occup_bcast with whole-matrix
  Parallel_Common::bcast_double calls (rule: no direct MPI usage)
- dftu_lcao_test links one extra light source (dftu_base_io.cpp) so that
  the heavy PW implementation dftu_base_occ.cpp stays out of the test
  closure
- Move JacobiRotate/CalculateEigenvalues helpers into an anonymous
  namespace and drop an unused local variable during migration

Verification: full incremental build passes in build/ (abacus_basic_para,
100%); in build_max_para_test/ the targets dftu_lcao_test and
dftu_pw_test build and link successfully (100%); grep confirms no
references remain to dftu_io, dftu_pw::, dftu_output, dftu_tools_pw,
dftu_cal_occ_pw, or the removed Plus_U_Base members.

* refactor(dftu): add YukawaScreening class skeleton (no behavior change)

Introduce YukawaScreening to own the Yukawa screening length, Slater
integrals Fk and derived U_Yukawa/J_Yukawa values. The implementation is
moved verbatim from DFTU_LCAO free functions; no call sites are changed
yet, so dftu_yukawa.* stays in place and behavior is unchanged.

Verification: make -j 30 dftu (build_max_para_test) passed.

* refactor(dftu): hold YukawaScreening in Plus_U_Base

Move yukawa_screening.* from module_dftu to module_pwdft so the base
layer can own it without depending on LCAO. Plus_U_Base now constructs a
YukawaScreening when use_yukawa_ is set and exposes it via yukawa(); the
legacy lambda/Fk/U_Yukawa/J_Yukawa members are kept in place until call
sites migrate. The cal_slater_Fk orb dependency stays guarded by __LCAO.

Verification: make -j 30 module_pwdft (build_max_para_test) passed.

* refactor(dftu): switch call sites to YukawaScreening, drop dftu_yukawa.*

Replace the DFTU_LCAO free Yukawa functions with the YukawaScreening
member owned by Plus_U_Base. setup_dftu_lcao now drives
yukawa().cal_slater_UJ and writes U-J back to u_current; the pots,
energy and IO paths read U/J through yukawa(). The yukawa_lambda config
is threaded through init_base into YukawaScreening::init, and
dftu_yukawa.h/.cpp are removed.

Verification: make -j 30 (build_max_para_test) passed;
ctest -R dftu: 4/4 passed (dftu_pw_test, dftu_core_test,
dftu_operator_test, dftu_lcao_test).

* refactor(dftu): drop legacy Yukawa members from Plus_U_Base

All Yukawa state (lambda, Slater Fk integrals, derived U/J) now lives
exclusively in YukawaScreening, owned by Plus_U_Base via yukawa_.
use_yukawa() is derived from the pointer instead of a separate flag,
and the redundant yukawa_lambda member/accessor on Plus_U is removed.

Verified: make -j 30 in build_max_para_test passes;
OMP_NUM_THREADS=1 ctest -R dftu passes (4/4).

* refactor(dftu): add OccupationMatrix skeleton (unused for now)

New class owning the nested occ[iat][l][n][spin] matrices, their saved
copy for mixing, and the iat->(l,n,m,ipol)->iwt lookup table. Provides
element/matrix access, flat (de)serialization and bulk zero/copy/flat
operations covering everything the legacy Plus_U_Base code paths need.
Not yet referenced by existing code; call sites switch in later steps.

Verified: make -j 30 in build_max_para_test passes.

* refactor(dftu): Plus_U_Base holds an OccupationMatrix instance

occmat_ is allocated alongside the legacy occ_mat/occ_mat_save/
iatlnmipol2iwt arrays in init_base, and exposed via occmat(). Existing
read/write paths are unchanged; writers switch to occmat_ next.

Verified: make -j 30 in build_max_para_test passes;
OMP_NUM_THREADS=1 ctest -R dftu passes (4/4).

* Refactor: route DFT+U occupation-matrix writes through OccupationMatrix

Switch all internal writers and public read accessors of Plus_U_Base from
the legacy occ_mat/occ_mat_save/iatlnmipol2iwt members to the new
occmat_ (OccupationMatrix) object:

- init_base: read_occup_m/local_occup_bcast now fill occmat_.data()
- copy_occ_mat -> occmat_.copy_to_save + write_save_to_flat
- zero_occ_mat  -> occmat_.zero
- set_occ_mat   -> occmat_.read_from_flat
- get/set_occ_mat_flat -> occmat_.get_flat/set_flat
- dftu_base_occ.cpp: reduce_occ_mat, sync_occ_to_uom,
  compute_eff_pot_and_energy, accumulate_occ_one_k use occmat_.mat()
- header accessors get_occ_mat/get_occ_mat_save/get_occ_mat_data/
  get_occ_mat_save_data/get_iatlnmipol2iwt forward to occmat_
- dftu_lcao_test builds and reads the matrices through occmat()

The legacy members are still allocated but now dead; they are removed in
the follow-up commit. Behavior is unchanged: make -j 30 and
OMP_NUM_THREADS=1 ctest -R dftu (4/4) pass.

* Refactor: remove legacy DFT+U occupation-matrix members

All readers and writers now go through occmat_ (OccupationMatrix), so the
legacy Plus_U_Base members occ_mat, occ_mat_save and iatlnmipol2iwt are
deleted together with their allocation block in init_base (the
pot_uterm_pw_index / num_locale bookkeeping is kept).

The IO free functions read_occup_m / local_occup_bcast now take an
OccupationMatrix& instead of the raw nested vector, and write into it
through the set()/mat() interface. write_occup_m / output already used
the public get_occ_mat() accessors and are unchanged.

Behavior is unchanged: make -j 30 and OMP_NUM_THREADS=1 ctest -R dftu
(4/4) pass.

* docs: record nested-vector member extraction pattern in AGENTS.md

Lesson from the DFT+U OccupationMatrix refactor (B2-B4): migrate a
base-class nested-vector member in three steps so no commit mixes
old-storage writes with new-storage reads.

* refactor: move OccupationMatrix from module_pwdft to source_estate

OccupationMatrix depends only on UnitCell and ModuleBase::matrix, not on
any PW- or LCAO-specific layer. It is an electronic-state data container,
so source_estate is a more natural home than source_pw/module_pwdft.

Verified with make -j 30 in build_max_para_test and
OMP_NUM_THREADS=1 ctest -R dftu (4/4 passed).

* refactor: drop Plus_U_Base pure-forwarding occupation accessors

Remove 8 accessors on Plus_U_Base that only forwarded to the
OccupationMatrix member; call sites now use dftu.occmat() directly:
  get_iatlnmipol2iwt, get_occ_mat, get_occ_mat_save, get_occ_mat_data,
  get_occ_mat_save_data, get_occ_mat_flat, set_occ_mat_flat
(get_occ_mat_flat/set_occ_mat_flat definitions in dftu_base.cpp removed too).

Kept occmat(), get_occ_mat_ctrl(), and the copy_occ_mat/zero_occ_mat/
set_occ_mat/sync_occ_to_uom wrappers, which still touch the uom_array /
uom_save / pot_uterm_pw_index base-class members.

Verified with make -j 30 in build_max_para_test and
OMP_NUM_THREADS=1 ctest -R dftu (4/4 passed).

* fix: guard YukawaScreening::cal_slater_Fk body with __LCAO

cal_slater_Fk dereferences const LCAO_Orbitals*, but the complete type
(orb_read.h) is only included under #ifdef __LCAO while the function body
was not guarded. PW-only CI builds (without __LCAO) failed with
"invalid use of incomplete type 'const class LCAO_Orbitals'".

Guard the body with #ifdef __LCAO and WARNING_QUIT in the non-LCAO stub,
matching the existing codebase pattern (vnl_pw_alpha.cpp, esolver_factory).

Verified: make -j 30 (LCAO build) passed;
c++ -fsyntax-only -std=gnu++11 (no __LCAO) passed;
OMP_NUM_THREADS=1 ctest -R dftu 4/4 passed.

* refactor(dftu): slim dftu_lcao.h and turn pot_uterm_HR into free functions

Header slimming (forward declarations):
- dftu_lcao.h: drop 7 transitive includes (klist/unitcell/parallel_orbitals/
  orb_read/hamilt/hcontainer/density_matrix), replace with forward
  declarations for UnitCell, Parallel_Orbitals, LCAO_Orbitals,
  hamilt::HContainer<T> and elecstate::DensityMatrix<TK,TR>.
- Add direct includes where the removed transitives were actually used:
  dftu_lcao.cpp, dftu_lcao_pots.cpp, dftu_lcao_energy.cpp,
  force_stress_lcao.h, write_hs_r.h, spar_u.cpp.

Free-function refactor:
- Move Plus_U::cal_eff_pot_mat_R_double / cal_eff_pot_mat_R_complex_double
  out of the class into namespace DFTU_LCAO, renamed to pot_uterm_HR_real /
  pot_uterm_HR_complex to match the existing pot_uterm_real/complex family.
- spar_u.cpp now calls DFTU_LCAO::pot_uterm_HR_real/complex(dftu, ...).

Verified: cmake --build build -j4 (exit 0). This build has no test targets.

* refactor(dftu): sink occupation mixing to source_estate and drop forwarding methods

- Add free function elecstate::mix_occ_with_save() in occ_matrix.{h,cpp}:
  occ = beta*occ + (1-beta)*occ_save over each atom's correlated orbital,
  nspin-aware (nspin=4 single Pauli block, nspin=1/2 both spin channels).
- LCAO cal_occ_mat_k/gamma: replace the two duplicated hand-written mixing
  loops with a single mix_occ_with_save() call (~60 lines removed).
- Plus_U_Base: delete the pure-forwarding methods copy_occ_mat /
  zero_occ_mat / set_occ_mat and inline their call sites
  (init_base in dftu_base.cpp, cal_occ_pw in dftu_base_occ.cpp) to call
  occmat_.copy_to_save / write_save_to_flat / zero / read_from_flat directly.

Verified: cmake --build build -j4 (exit 0). This build has no test targets.

* refactor(dftu): turn Plus_U_Base PW occ path into DFTU_BASE free functions

Move the remaining PW occupation-matrix members out of Plus_U_Base into
namespace DFTU_BASE (declared in dftu_base_tools.h, defined in
dftu_base_occ.cpp):
- reduce_occ_mat(cell, nspin, kpar, orbital_corr, occmat): k-pool reduce
  still goes through Parallel_Reduce::reduce_double_allpool (unchanged MPI
  wrapper).
- compute_eff_pot_and_energy -> compute_pot_uterm_and_energy(...), renamed to
  match the pot_uterm_* family; takes u_current/orbital_corr/
  pot_uterm_pw_index/occmat/pot_uterm_pw and writes energy_u by reference.
- accumulate_occ_one_k<Device>: templated free function, explicit
  instantiations for DEVICE_CPU (and DEVICE_GPU) moved to the .cpp.
- sync_occ_to_uom removed; cal_occ_pw now calls occmat_.write_to_flat
  directly.

Plus_U_Base::cal_occ_pw remains as the thin orchestration wrapper.

Verified: cmake --build build -j4 (exit 0). This build has no test targets.

* refactor(dftu): collapse cal_occ_mat_k/gamma signatures onto Plus_U&

cal_occ_mat_k: 13 params -> 9 (add Plus_U& dftu, drop nspin/npol/nlocal/
ks_solver/iatlnmipol2iwt/orbital_corr/occ_mat/occ_mat_save/occ_mat_initialized).
cal_occ_mat_gamma: 13 params -> 7 (add Plus_U& dftu).

Both now read all occupation-matrix state from dftu.occmat()
(mat/mat_save/data/data_save/iatlnmipol2iwt/nspin/npol) and the Plus_U_Base
accessors (get_orbital_corr_vec / is_occ_mat_initialized /
mark_occ_mat_initialized), and use occmat().copy_to_save()/zero() instead of
the duplicated hand-written copy/zero loops. The intermediate cal_occ_mat
template forwarders shrink to a single direct call.

MPI_Allreduce(MPI_COMM_WORLD) inside the accumulation is intentionally left
unchanged: it has no exact Parallel_Reduce counterpart and was kept per the
"only replace what maps cleanly" rule.

Verified: cmake --build build -j4 (exit 0). This build has no test targets.

* refactor(dftu): split DFT+U force/stress into r-space NAO files and rename for clarity

Rename and reorganize DFT+U force/stress implementation:

New files (r-space, NAO basis):
- dftu_nao_fs_r.h/cpp    : unified force+stress entry with full formula docs
- dftu_nao_for_r.h/cpp   : single-pair force core (cal_for_IJR_nao_r)
- dftu_nao_str_r.h/cpp   : single-pair stress core (cal_str_IJR_nao_r)

Renamed files:
- dftu_lcao_op.h/cpp          -> dftu_nao_op.h/cpp
- dftu_lcao_op_legacy.cpp     -> dftu_nao_op_legacy.cpp
- dftu_force.h/cpp (legacy k) -> dftu_nao_fs_k.h/cpp
- dftu_folding.h/cpp          -> dftu_nao_folding.h/cpp

Deleted:
- dftu_fs.cpp (split into dftu_nao_fs_r.cpp + dftu_nao_for_r.cpp + dftu_nao_str_r.cpp)

Updated:
- dftu_nao_op.h: expose getters and cal_pot_onsite/transfer_pot_onsite for free functions
- force_stress_lcao.cpp, hamilt_lcao.cpp, dftu_lcao_occ.cpp: update includes
- test/CMakeLists.txt, test/dftu_lcao_test.cpp: update source list and include

Naming convention:
- nao : NAO/LCAO basis set
- _r  : real-space implementation (uses DMR, k-point independent)
- _k  : k-space legacy implementation (deprecated, broken)
- for : force
- str : stress
- fs  : force+stress combined

Co-Authored-By: TRAE <noreply@trae.ai>

* increase the thr of stress from 11 to 12 in example 15_KP_HSE_SOC_symm

* refactor(dftu): rename all dftu_lcao* files to dftu_nao* for NAO basis clarity

Rename all LCAO-specific DFT+U files in module_dftu to use 'nao' instead
of 'lcao', making the basis-set dependency explicit in the filename:

- dftu_lcao.h/cpp          -> dftu_nao.h/cpp
- dftu_lcao_occ.h/cpp      -> dftu_nao_occ.h/cpp
- dftu_lcao_pots.h/cpp     -> dftu_nao_pots.h/cpp
- dftu_lcao_energy.h/cpp   -> dftu_nao_energy.h/cpp
- dftu_lcao_op_legacy.h    -> dftu_nao_op_legacy.h

Update all #include references across 29 files in:
  source_lcao, source_esolver, source_estate, source_io, module_dftu

Update CMakeLists.txt source lists accordingly.

Note: setup_dftu_lcao.cpp/h keep their names (they are not in module_dftu
and represent the DFT+U setup workflow, not a basis-specific implementation).

Co-Authored-By: TRAE <noreply@trae.ai>

* fix: prevent out-of-bounds write in write_save_to_flat for nspin=1

For nspin==1, uom_save is allocated as a single block (pot_index is
doubled only when nspin==2). However, write_save_to_flat previously
wrote both spin channels unconditionally, causing part of the first
block to be overwritten and indices past the vector end to be accessed
(undefined behavior via operator[]).

Fix by guarding the channel-[1] write with `if (nspin_ == 2)`,
consistent with write_to_flat() and read_from_flat() which already
handle the two channels correctly.

* fix: adapt onsite_proj_force_stress.cpp to renamed Plus_U_Base interface

Upstream PR deepmodeling#7873 split onsite_proj.cpp and introduced
onsite_proj_force_stress.cpp, which still called the removed
get_orbital_corr_data() (returning const int*). Our refactor PR had
renamed it to get_orbital_corr_vec() (returning const std::vector<int>&).

Fix by appending .data() at both call sites, matching the new interface.

* fix(Makefile): update stale DFTU object names after module_dftu rename

The DFT+U LCAO files in module_dftu/ were renamed from dftu_lcao_*
to dftu_nao_* (step 6, commit 4fd1529), but source/Makefile.Objects
still referenced the old names. Additionally, dftu_fs.cpp was split
into four focused files (dftu_nao_fs_k/for_r/fs_r/str_r), so the old
single dftu_fs.o entry is no longer valid.

Fix both OBJS_LCAO and OBJS_DFTU sections to use the current source
filenames so the legacy Makefile build (used by the Intel CI) works.

* fix: eliminate variadic macro warnings in REQUIRES_OK

Two related warnings were triggered:
- -Wvariadic-macro-arguments-omitted: memory.h called REQUIRES_OK
  with only one argument (no variadic arg)
- -Wgnu-zero-variadic-macro-arguments: macros.h used GNU extension
  '##__VA_ARGS__' to swallow the comma when __VA_ARGS__ was empty

Fix:
1. Add a message argument to the single-arg REQUIRES_OK call site
2. Drop the '##' GNU extension since all call sites now pass at
   least one variadic argument

* fix: remove trailing semicolons in xc_kernel.h macros and destructor

The CREF and CREF3 macro definitions each had a trailing semicolon,
and the call sites also added one, resulting in double semicolons
(;;) inside the class that triggered -Wextra-semi warnings.

Remove the semicolons from the macro definitions and from the
destructor definition (~KernelXC() {};) to eliminate the warnings.

Verified: cmake --build . completes with no warnings from xc_kernel.h.

* fix: suppress -Wundefined-var-template warning for OperatorEXXPW::fock_div

Replace redundant explicit instantiation definitions (template class)
with explicit instantiation declarations (extern template class) in
op_pw_exx_pot.cpp. The static data member fock_div is defined and
instantiated in op_pw_exx.cpp; the duplicates in op_pw_exx_pot.cpp
could not instantiate it (out-of-class definition not visible) and
triggered -Wundefined-var-template when get_exx_potential accessed it.

* fix: add override to ElecStatePW::psiToRho and cal_tau

ElecStatePW<T, Device> is a template derived class. Its psiToRho/cal_tau
signatures only match the base-class virtual for some (T, Device) combos,
which prevented simply adding 'override' to the template declaration.

Fix: enumerate all (T, Device) combos (CPU and GPU for complex<float>,
complex<double>, and double) as empty virtuals in the base class ElecState,
then mark the two derived-class template members as 'override'.

This resolves the -Winconsistent-missing-override warning from icpx/clang
without changing any runtime behavior.

* fix(Makefile): drop stale dftu_yukawa.o from OBJS_DFTU

Commit 8310580 removed dftu_yukawa.cpp/.h and dropped it from the module_dftu CMakeLists, but source/Makefile.Objects still listed dftu_yukawa.o in OBJS_DFTU. The subsequent rename fix (5f3af73) updated the other DFTU object names but left this orphan entry behind, so the Intel CI Makefile build failed with 'No rule to make target build/obj/dftu_yukawa.o, needed by build/bin/ABACUS.mpi'.

Verified: make -n -f ../Makefile abacus from source/build now exits 0 with no missing-target error; the link line lists the 11 valid DFTU objects and no dftu_yukawa.o. dftu_nao_op.o is already registered in OBJS_HAMILT_LCAO, so no replacement is needed.

* fix(cal_plpr): resolve -Wreturn-type warnings under NDEBUG

In release builds with -DNDEBUG, assert(false) is compiled out, leaving
cal_LxijR and cal_LyijR with control paths that fall off the end without
returning a value. Convert the trailing `if (jm < -1)` to `else` and move
assert(jm < -1) inside as a defensive check, so the compiler can statically
prove all paths return. Also add explicit #include <cassert>.

* fix(ions_move_lbfgs): replace VLA with std::vector to fix -Wvla-cxx-extension

Replace the variable-length array 'double a[3*size]' in update_pos with a
std::vector<double>. The VLA relied on a runtime member 'size' and was a
non-standard Clang extension. The vector's .data() is passed to
unitcell::update_pos_tau, whose 'pos' parameter is 'const double*', so
the conversion is semantically equivalent.

* fix: resolve -Wdtor-name warning in EKinetic destructor definition

Use the fully-qualified template name after '::~' to satisfy Intel
compiler's -Wdtor-name, matching the pattern already used in
Mix_DMk_2D<Tdata>::~Mix_DMk_2D<Tdata>(). C++11 compatible.

* Fix -Wdtor-name warning in OnsiteProjector destructor

Move the out-of-line destructor definition and its explicit
instantiations into a 'namespace projectors {}' block so the name
after '~' is looked up in the same scope as the class name, satisfying
ISO C++ requirements.

* fix: replace C99 _Complex with std::complex<double> in cblacs.h

C99 `_Complex` is not valid in C++, causing -Wc99-extensions warnings
when cblacs.h is included from C++ translation units (wrapped in
extern "C" blocks). Replace with `std::complex<double>`, which has
identical memory layout and is compatible with the BLACS C library.

* fix(dftu): replace VLAs with std::vector in dftu_nao_fs_r

Replace two variable-length arrays (dmR_tmp and tmp) sized by
dftu_op->get_nspin() with std::vector, eliminating the
-Wvla-cxx-extension warnings. Both arrays are now explicitly
zero-initialized with nullptr. Pass tmp.data() to cal_for_IJR_nao_r
and cal_str_IJR_nao_r to match their const BaseMatrix<double>**
parameter signature.

* fix: wrap member function definitions in namespace hamilt for -Wdtor-name

Move Nonlocal and Overlap member function definitions inside `namespace hamilt`
blocks and drop redundant `hamilt::` qualifiers. This resolves the ISO C++
warning:
  warning: ISO C++ requires the name after '::~' to be found in the
           same scope as the name before '::~' [-Wdtor-name]

Affected files:
  - source/source_lcao/module_operator_lcao/nonlocal.cpp
  - source/source_lcao/module_operator_lcao/overlap.cpp

* fix: add missing variadic macro argument in Tensor::sync

REQUIRES_OK(expr, ...) is a variadic macro defined in macros.h.
C++14 requires at least one argument be passed for the ... parameter;
omitting it is a C++20 extension that triggers -Wvariadic-macro-arguments-omitted
under icpx -pedantic.

Tensor::sync was the only call site in the whole codebase that omitted the
second argument. Add a descriptive error message to keep the macro usage
consistent with every other REQUIRES_OK call.

* build(make): link occ_matrix.o to fix undefined reference to OccupationMatrix::get_flat

occ_matrix.cpp was missing from Makefile.Objects, so the Intel Makefile
build did not compile/link occ_matrix.o, causing an undefined reference
to OccupationMatrix::get_flat in dftu_nao_op.cpp. Add it to OBJS_ELECSTAT
to mirror source_estate/CMakeLists.txt, which already lists occ_matrix.cpp
in the elecstate object library.

* fix(Makefile): resolve multiple definitions and missing YukawaScreening link

- Remove 4 duplicate objects (dftu_nao_fs_k/for_r/fs_r/str_r.o) from
  OBJS_HAMILT_LCAO; they are already listed in OBJS_DFTU and both
  lists merge into OBJS_ABACUS, causing "multiple definition" linker errors.
- Add missing yukawa_screening.o to OBJS_SRCPW so YukawaScreening::*
  symbols resolve; it is already present in CMakeLists.txt module_pwdft.

Verified with `make -n` (dry-run): dftu_nao_fs_k.o appears exactly once
in the final link line; yukawa_screening.o is compiled from
source_pw/module_pwdft/yukawa_screening.cpp.

* fix(dftu): clear stale YukawaScreening when init_base reruns with yukawa_potential=false

Before the refactor, use_yukawa_ was assigned on every init_base() call,
so the state always matched the latest argument. Now the state is
inferred from yukawa_, but the pointer was only updated on the true
branch; a true -> false re-initialization left a stale object alive.
PW's before_scf() -> setup_pot() may call init_base() repeatedly on the
same Plus_U object, so clear the pointer in the disabled branch to
preserve the old semantics. Add unit tests for both switch directions
(reverse-verified: they fail with the stale-object behavior).

* fix(dfpt): use mark_occ_mat_initialized in pw_data test

The test called a nonexistent Plus_U_Base::set_occ_mat_initialized(bool);
the actual API is mark_occ_mat_initialized(). Verified locally:
MODULE_DFPT_pw_data_test 6/6 passed.

---------

Co-authored-by: abacus_fixer <mohanchen@pku.eud.cn>
Co-authored-by: TRAE <noreply@trae.ai>

Author: 3 people

AGENTS.md

@@ -103,6 +103,9 @@ rules. Read the complete governance document before making or reviewing changes:
 - Member -> free function: inventory `this->` reads; pass as params (const
   for config, ref for mutable state); move only when body is `this`-free;
   keep thin wrapper; compile each step.
+- Extract a base-class nested-vector member in three steps (hold + forward,
+  switch writers, delete legacy) so no commit mixes old-storage writes with
+  new-storage reads.
 
 ## Local Commands
 

source/Makefile.Objects

@@ -282,6 +282,7 @@ OBJS_ELECSTAT=elecstate.o\
     read_orb.o\
     setup_estate_pw.o\
     update_pot.o\
+    occ_matrix.o
 
 OBJS_ELECSTAT_LCAO=elecstate_lcao.o\
       init_dm.o\
@@ -402,13 +403,12 @@ OBJS_HAMILT_LCAO=hamilt_lcao.o\
     veff_lcao.o\
     veff_dh.o\
     meta_lcao.o\
-    dftu_lcao_op.o\
+    dftu_nao_op.o\
     deepks_lcao.o\
     op_exx_lcao.o\
     dspin_lcao.o\
     dspin_fs.o\
     setup_dftu_lcao.o\
-    dftu_fs.o\
     operator_fs_utils.o\
 
 OBJS_HCONTAINER=base_matrix.o\
@@ -813,9 +813,10 @@ OBJS_SRCPW=h_ewald_pw.o\
     setup_pwwfc.o\
     update_cell_pw.o\
     dftu_base.o\
-    dftu_output.o\
-    dftu_tools_pw.o\
-    dftu_cal_occ_pw.o\
+    dftu_base_io.o\
+    dftu_base_occ.o\
+    dftu_base_tools.o\
+    yukawa_screening.o\
     setup_dftu_pw.o\
     deltaspin_pw.o\
     deltaspin_pw_impl.o\
@@ -890,14 +891,16 @@ OBJS_VDW=vdw.o\
     vdwd3_autoset_xcname.o\
     vdwd3_auto_xcpar.o
 
-OBJS_DFTU=dftu_lcao.o\
-      dftu_force.o\
-      dftu_yukawa.o\
-      dftu_folding.o\
-      dftu_lcao_pots.o\
-      dftu_lcao_energy.o\
-      dftu_lcao_op_legacy.o\
-      dftu_lcao_occ.o\
+OBJS_DFTU=dftu_nao.o\
+      dftu_nao_fs_k.o\
+      dftu_nao_for_r.o\
+      dftu_nao_fs_r.o\
+      dftu_nao_str_r.o\
+      dftu_nao_folding.o\
+      dftu_nao_pots.o\
+      dftu_nao_energy.o\
+      dftu_nao_op_legacy.o\
+      dftu_nao_occ.o\
       dftu_hamilt.o
 
 OBJS_DELTASPIN=basic_funcs.o\

source/source_base/module_container/ATen/core/tensor.cpp

@@ -295,7 +295,8 @@ bool Tensor::AllocateFrom(const Tensor& other, const TensorShape& shape) {
 
 void Tensor::sync(const Tensor& rhs) {
     REQUIRES_OK(this->data_type_ == rhs.data_type_ 
-        && this->device_ == rhs.device_)
+        && this->device_ == rhs.device_,
+        "sync: data_type and device must match between tensors")
 
     if (this->shape_ == rhs.shape_) {
         TEMPLATE_ALL_2(data_type_, device_,

source/source_base/module_container/ATen/kernels/memory.h

@@ -81,7 +81,7 @@ struct synchronize_memory_stride {
         const std::vector<int64_t>& out_size,
         const std::vector<int64_t>& in_size)
     {
-        REQUIRES_OK(in_size.size() == out_size.size() && in_size.size() <= 2);
+        REQUIRES_OK(in_size.size() == out_size.size() && in_size.size() <= 2, "rank mismatch: in_size and out_size must have the same rank <= 2");
         if (in_size.size() == 1) {
             synchronize_memory<T, Device_out, Device_in>()(arr_out, arr_in, in_size[0]);
         }

source/source_base/module_container/base/macros/macros.h

@@ -70,7 +70,7 @@
             __func__,                                   \
             __FILE__,                                   \
             static_cast<uint32_t>(__LINE__),            \
-            CHECK_MSG(expr, ##__VA_ARGS__));            \
+            CHECK_MSG(expr, __VA_ARGS__));             \
     }
 
 // The macro TEMPLATE_1() expands to a switch statement conditioned on

source/source_esolver/esolver_ks.cpp

@@ -13,7 +13,7 @@
 #include "source_hamilt/module_xc/xc_functional.h"
 #include "source_io/module_output/output_log.h" // use write_head
 #include "source_estate/elecstate_print.h" // print_etot
-#include "source_lcao/module_dftu/dftu_lcao.h" // mohan add 2025-11-07
+#include "source_lcao/module_dftu/dftu_nao.h" // mohan add 2025-11-07
 #include "source_hamilt/module_xc/general_exx_info.h" // for init_general_exx_info
 
 namespace ModuleESolver

source/source_esolver/esolver_ks.h

@@ -8,7 +8,7 @@
 #include "source_hamilt/hamilt.h"                      // use Hamiltonian
 #include "source_hamilt/hamilt_base.h"                 // use Hamiltonian base class
 #include "source_hamilt/module_xc/general_exx_info.h"  // ESolver owns General_Exx_Info value
-#include "source_lcao/module_dftu/dftu_lcao.h"              // mohan add 20251107
+#include "source_lcao/module_dftu/dftu_nao.h"              // mohan add 20251107
 #include "source_pw/module_pwdft/vnl_pw.h"
 
 namespace ModuleESolver

source/source_esolver/esolver_ks_pw.cpp

@@ -202,7 +202,7 @@ void ESolver_KS_PW<T, Device>::iter_init(UnitCell& ucell, const int istep, const
 
     // update local occupations for DFT+U
     // should before lambda loop in DeltaSpin
-    pw::iter_init_dftu_pw(iter,
+    DFTU_BASE::iter_init_dftu_pw(iter,
                           istep,
                           this->dftu,
                           this->stp.template get_psi_t<T, Device>(),

source/source_esolver/lcao_others.cpp

@@ -15,7 +15,7 @@
 #include "source_lcao/hamilt_lcao.h"
 #include "source_lcao/lcao_domain.h"
 #include "source_lcao/module_deltaspin/spin_constrain.h"
-#include "source_lcao/module_dftu/dftu_lcao.h"
+#include "source_lcao/module_dftu/dftu_nao.h"
 #include "source_lcao/module_operator_lcao/op_exx_lcao.h"
 #include "source_lcao/module_operator_lcao/operator_lcao.h"
 

source/source_estate/CMakeLists.txt

@@ -42,6 +42,7 @@ list(APPEND objects
     module_charge/symm_rhog.cpp
     fp_energy.cpp
     occupy.cpp
+    occ_matrix.cpp
     param_update.cpp
     setup_estate_pw.cpp
     update_pot.cpp