Split some large files (fs_nonlocal_tools.cpp, onsite_proj.cpp, to_wannier90_lcao.cpp, etc.) into smaller ones

[mohanchen]

Split some large files into smaller ones

Refactor xc_grad pipeline: pack stage arguments into internal structs

The gradcorr pipeline stages (gradcorr_prepare_rho / gradcorr_xc_kernel /
gradcorr_assemble_vxc) took 20+ mostly same-typed scalar parameters
(pointer/array pairs for per-spin buffers, plus several int/bool flags
with fixed ordering conventions). This made silent argument swaps easy
to introduce and hard to review.

Move the three stage functions out of the XC_Functional class into
internal free functions declared in a new xc_grad_internal.h, which is
included only by the xc_grad*.cpp implementation files. Their parameters
are packed into two structs:

• GradCorrParams: read-only inputs (charge, basis, ucell, spin flags,
  hybrid parameters, functional metadata), built once by
  XC_Functional::gradcorr and passed by const reference;
• GradCorrBuffers: per-spin scratch arrays (rhotmp/rhogsum/gdr/h/lapl/
  vlapl/vsave/vgg/neg) allocated by the prepare stage and consumed by
  the kernel and assemble stages.

The static-members use_libxc/func_type/func_id, which the stage
functions previously read implicitly across translation units, are now
explicit fields of GradCorrParams. The public entry point
XC_Functional::gradcorr keeps its exact signature, so no caller changes.
Also drop the unused leftover epsg constant and need_laplacian unpacking
in the kernel stage.

Verification: xc_ target builds (ENABLE_LIBXC=OFF, gnu++14 + OpenMP);
g++ -fsyntax-only -D__LIBXC over the xc_grad*.cpp files covers the libxc
branch; nm confirms XC_Functional::gradcorr signature unchanged and a
single definition of each stage function; MODULE_ESTATE_elecstate_pw
builds, links and passes under OMP_NUM_THREADS=1; agent governance
check reports no findings.

This PR also renames the wannier90 module to w90: all files, classes and
references under source/source_io/module_wannier are shortened from
to_wannier90_* to to_w90_* (renames done with git mv to preserve file
history; CMakeLists.txt and Makefile.Objects updated accordingly).

On top of the rename, the touched code is hardened:

• Replace raw new/delete with std::vector/std::unique_ptr across the
  module (toW90 member arrays, local buffers in pw/lcao setup/io/overlap,
  FR_overlap Leb_grid/FR_container, unk_inLcao and psi_initer_ ownership
  in lcao_pw), removing all manual delete[] cleanup.
• Fix naming (MGT -> mgt_, NULL -> nullptr), tab indentation and
  overlong lines.
• Remove global dependencies: nspin, nbands, nqx, dq and npol are
  now passed explicitly through the toW90 constructor chain, so the module
  no longer reads PARAM.inp.* / PARAM.globalv.* for these.
• Drop 12 redundant #ifdef __MPI guards around
  Parallel_Reduce::reduce_all calls. To make serial builds safe for
  broadcast as well, parallel_common.cpp is restructured so every
  bcast_* function keeps its #ifdef __MPI inside the function body
  (no-op definitions when built without MPI, following the
  parallel_reduce.cpp style). This also fixes the "build without MPI"
  link failure reported by CI (undefined reference to
  Parallel_Common::bcast_bool).

Verification: every step was committed only after a clean incremental build;
g++ -fsyntax-only of parallel_common.cpp passes without __MPI; the
code-quality score of the changed files improved from 76.2 to 78.8 with
13/16 files passing (remaining deductions are pre-existing global-dependency
and cyclomatic-complexity debt, proposed for follow-up PRs). The branch was
rebased onto the latest develop (DFT+U step 5); 13 zero-net-effect
split+revert commits were dropped during the rebase to keep the history
linear, with tree content verified identical before and after.

[Critsium-xy]

I pulled this PR locally and mechanically checked each of the 12 split groups: for every group I stripped comments, normalized whitespace, dropped #include lines, and sorted the content of the original file and of the union of the resulting files, then diffed them to see whether any code was actually added or removed. The splits are faithful overall — 11 of the 12 groups are token-for-token equivalent to the original, with the only differences being duplicated includes / #ifdef guards and template instantiation lines. Three things worth raising.

1. Duplicated whole-class explicit template instantiations

After the split, the same specialization is explicitly instantiated in multiple TUs:

• atom_pair.cpp / atom_pair_kernels.cpp / atom_pair_output.cpp: each file carries 3 lines of template class AtomPair<float/double/std::complex<double>>;
• hcontainer.cpp / hcontainer_insert.cpp / hcontainer_math.cpp: likewise 3 lines each of template class HContainer<...>;
• force_pw.cpp / force_pw_driver.cpp / force_pw_ew.cpp: 2 lines each of template class Forces<double, DEVICE_CPU/DEVICE_GPU>;
• force_stress_lcao_driver.cpp / _integral.cpp / _pw.cpp / _utility.cpp: 2 lines each of template class Force_Stress_LCAO<double/std::complex<double>>;

Per [temp.explicit]/13, a given specialization may have at most one explicit instantiation definition in a program; violating this is IFNDR. GCC/Clang link it fine via COMDAT weak symbols, which is why CI is green — but the practical effect is that every TU re-instantiates all members visible from the headers, inflating object size and link time. That works against the compile-time speedup the split is meant to deliver.

onsite_proj.cpp and onsite_proj_tools.cpp in this same PR use per-member instantiation (template void X<...>::f(...);), which is the correct form. I checked all 12 out-of-line members of OnsiteProjector (including get_instance and the destructor) and none are missing. Suggest switching the hcontainer / force groups to per-member instantiation as well.

2. force_stress_lcao lost 118 lines of explanatory comments

While moving code from force_stress_lcao.cpp into force_stress_lcao_driver.cpp and friends, 118 comment lines were not carried over. These are not commented-out dead code — they carry real information, e.g.:

// The legacy dft_plus_u==2 force/stress path is currently broken.
// With symmetry switched on, the forces assembled above are built from IBZ-reduced ...
// Force symmetrization is linear, so it commutes with the removal of a ...
// Force contribution from DFT+U, Quxin add on 20201029
// Background: Plus_U::force_stress relies on ForceStressArrays

I confirmed with git grep that these no longer exist anywhere on the PR branch. The first one is the most costly to lose — it flags a known defect. Suggest restoring this batch of comments.

Comment loss in the other groups is minor (11 lines in force_pw, 15 in numerical_basis) and is almost entirely commented-out dead code, which is fine to drop.

3. xc_grad is not a pure split — worth calling out in the PR description

Beyond splitting files, the xc_grad group contains a substantive refactor: raw new[]/delete[] pointers were converted to std::vector (removing 20 delete[] calls), and double** vgg / double** vsave became flat arrays, changing indexing from vgg[is][ir] to vgg[is*nrxx+ir].

I checked the prepare / kernel / assemble sections one by one and the semantics are equivalent: vgg is allocated as nspin0*nrxx and vsave as nspin*nrxx, matching the indexing; the 310-line kernel section is a verbatim move (diff -w shows only the function header/footer); and passing vtxcgc by value, accumulating into it, then doing vtxc += vtxcgc behaves the same as the original local variable. The change itself is a good direction.

But the PR description currently only says "Split some large files into smaller ones", so a reader will assume this is a purely mechanical move and skip the xc_grad diff. Suggest stating explicitly in the description that this group also rewrites memory management and indexing, or splitting it into its own PR to keep future bisects clean.

Separately, the three new public static functions added to xc_functional.h take 26 / 27 / 24 parameters, all bool, double and raw pointers — getting the argument order wrong would not be caught by the compiler. That header is also widely included, so touching it forces a full rebuild, which offsets the benefit of the split. Suggest packing the parameters into a struct and moving these declarations to an internal header (e.g. xc_grad_internal.h) rather than the public section of xc_functional.h.

[Critsium-xy]

Second review pass. I ran a stronger verification than last time and found one build-level issue plus a few smaller ones.

Verification: the split is mechanically sound

My first pass only compared sorted line sets, which cannot rule out statements being reordered inside a function. This time I parsed both trees into {signature -> body} maps via brace matching (descending into namespace blocks) and compared bodies pairwise across all 12 split groups.

Result: no function lost, no function added, no statement reordering anywhere. Only four bodies differ at all:

• Force_Stress_LCAO<T>::getForceStress — whitespace only (isforce, isstress, false ); -> false);)
• OnsiteProjector<T, Device>::init — whitespace only (for(int it=0;it<ntype;++it) -> for(int it=0; it<ntype; ++it))
• Numerical_Basis::output_overlap_V — a stray empty statement ; removed
• the xc_grad family — the RAII refactor noted in my previous review

Onsite_Proj_tools::cal_becp moved from inside namespace hamilt { } to a qualified hamilt:: definition; the body is byte-identical.

I also checked grad_rho and grad_dot individually since they are part of the xc_grad conversion: gdrtmp is still nmaxgr, aux is still nmaxgr, gaux is still npw — buffer sizes and call arguments all line up, so the conversion is faithful.

One more thing that could have gone wrong but did not: neither the original files nor the new ones contain static free functions or anonymous namespaces, so no previously TU-local helper was silently promoted to external linkage.

1. source/Makefile.Objects was not updated — the Makefile build will not link

None of the 36 new .cpp files are registered there, while source/Makefile includes it at line 195 and builds FP_OBJS from it at line 217. Missing entries mean undefined references at link time.

This file is actively maintained, not abandoned — on develop it covers essentially every .cpp in the directories this PR touches:

directory	unregistered / total .cpp on develop
source_lcao	0 / 31
module_xc	1 / 17
module_hcontainer	0 / 8
module_symmetry	1 / 12
module_wannier	0 / 5
module_bessel	0 / 4
module_pwdft	1 / 60

Of the three exceptions, deltaspin_pw_impl.cpp is #included into other .cpp files rather than compiled standalone.

Worth flagging separately: the Build with Makefile & Intel compilers job would normally catch this, but its Build step takes 0 seconds (13:53:17 -> 13:53:17 on run 33177252527). I checked the last three runs of that workflow on develop and the Build step is 0 seconds there too, going back to at least 2026-07-20. So that job has been a no-op since before this PR — a pre-existing problem, but it means nothing will stop this from landing broken.

2. Include blocks were copied wholesale into every new TU

Across the 12 groups, #include lines went from 144 to 496 (3.4x), because each new file carries a verbatim copy of the original include block regardless of what it needs:

• All six xc_grad TUs carry the same 11-line block. xc_grad_utils.cpp uses neither ATen nor libxc (0 references once the use_libxc static member is excluded), yet pulls in <ATen/core/tensor.h>, xc_functional_op.h, libxc_abacus.h and exx_info.h.
• All five force_stress_lcao TUs carry the same 27 includes. force_stress_lcao_pw.cpp is 73 lines of matrix accumulation but pulls in the full DeePKS / DFT+U / surchem / vdw / TDDFT / operator_lcao header set.
• The pre-existing duplicate #include "source_io/module_parameter/parameter.h" (already present twice on develop) got replicated into four more TUs.

AGENTS.md rule 3 is "Keep header dependencies minimal". Together with the duplicated whole-class instantiations from my previous review, this is the concrete mechanism by which the split can increase total compile work rather than reduce it.

3. The three new xc_functional.h functions should be private

gradcorr_prepare_rho, gradcorr_xc_kernel and gradcorr_assemble_vxc each have exactly one call site, all inside gradcorr in xc_grad.cpp, but they were added to the public: section. Moving them to private: is free and avoids turning three 24-27 parameter internal helpers into public API.

4. Stale file header in xc_grad.cpp

The header comment still reads:

// it contains 5 subroutines:
// 1. gradcorr ... 2. grad_wfc ... 3. grad_rho ... 4. grad_dot ... 5. noncolin_rho

After the split the file contains only gradcorr; the other four live in xc_grad_utils.cpp and xc_grad_wfc.cpp, neither of which has a header comment. This navigation comment now points readers to the wrong file.

5. Repository governance checker output

python tools/03_code_analysis/agent_governance_check.py \
  --base 5fb17a6ac --head <pr head> --format text

Exit code 0, no ERROR, but two WARNINGs:

• Test evidence review: Source code changed without test path changes or PR test evidence.
• Documentation sync review: Source changes have no docs change or explicit no-docs-needed statement.

Both look legitimate here. AGENTS.md rule 6 requires focused tests for core-module refactors, and AGENTS.md also asks contributors to "Report the exact verification performed". The PR description is currently a single line with no verification statement, which matters more than usual given the xc_grad memory-management rewrite. Stating which suites were run (or why tests are not required) would resolve both warnings.

Things that check out

• Global dependency budget is net -13 (323 GlobalV/GlobalC/PARAM references added, 336 removed), so rule 1's migration-neutral requirement is satisfied.
• Rules 8 and 9 show exactly symmetric add/remove counts — MPI_Barrier 6/6, MPI_COMM_WORLD 13/13, MPI_Send 5/5, MPI_Recv 5/5, comma-separated declarations 4/4 — so these are pure moves with no new violations introduced.
• The new[]/delete[] to std::vector conversion in xc_grad matches the AGENTS.md guidance to "Prefer std::vector over raw new/delete for dynamic arrays".

[Critsium-xy]

This is OK for now. But I notice that wannier_method 1 and 2 have no test cases now. This may need to be added in the future.