Add WFN-history backend for Gamma-only NAO calculations

[Growl1234]

This PR introduces an optional WFN-based initialization path for NAO calculations.

A new wfc_extrap use_prev_wf path is added. It stores the converged wavefunction from the previous ionic step, rebuilds the current overlap matrix, reorthonormalizes the previous wavefunction with the current overlap matrix, and then reconstructs the density matrix and charge density before entering the normal SCF cycle. When this path is enabled, the existing charge-density extrapolation is skipped, so the initial density is generated from the WFN-history backend instead of being extrapolated directly in real space.

The implementation currently focuses on the Gamma-only backend, including MPI-distributed matrices. This is intended as a common backend for future improvements and more WFN-based predictors such as ASPC and GExt_PROJ.

Here's a simple test that shows the accuracy and effectiveness of the WFN-based path: test.zip. The regtesting is left for a next commit.

What's planned to resolve in the future PRs:

• Further reducing SCF iterations requires a more accurate WFN prediction, which would probably be more involved because the wavefunction coefficients live in a nonorthogonal moving NAO basis. The backend therefore has to handle wavefunction history ownership, current-overlap reconstruction, distributed matrix layout, S-orthonormalization, occupation handling, and density reconstruction consistently.
• For k-point case it's even more complicated because the backend has to handle complex per-k wavefunctions, k-dependent overlap matrices $S(k)$, local/global k-point ownership, density-matrix reconstruction from all k-points, and PBC phase or convention corrections between ionic steps.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds Gamma-only LCAO wavefunction-history extrapolation (use_prev_wf) by snapshotting the previous step’s coefficients and reorthonormalizing them against the current overlap matrix before SCF.

Changes:

• Introduces LCAO wavefunction snapshot/history helpers and a Gamma-only reorthonormalization routine.
• Wires extrapolation into the LCAO ESolver flow and adds wfc_extrap input validation/handling (including skipping charge extrapolation when enabled).
• Updates CMake to enforce a minimum C++ standard and adds a new module_extrap subdirectory target.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
source/source_lcao/module_extrap/wf_snapshot_lcao.h	Stores/restores full Psi coefficient snapshots plus occupations.
source/source_lcao/module_extrap/wf_orthonormalize_lcao.h	Declares Gamma-only reorthonormalization API + diagnostic result struct.
source/source_lcao/module_extrap/wf_orthonormalize_lcao.cpp	Implements MPI-aware assembly + Cholesky-based reorthonormalization.
source/source_lcao/module_extrap/wf_history_lcao.h	Defines wavefunction history class and apply-result diagnostics.
source/source_lcao/module_extrap/wf_history_lcao.cpp	Implements history management and use_prev_wf apply path.
source/source_lcao/module_extrap/wf_extrap_method.h	Adds extrapolation method/status enums and string conversions.
source/source_lcao/module_extrap/CMakeLists.txt	Adds lcao_extrap object library target for new module sources.
source/source_lcao/CMakeLists.txt	Enables module_extrap subdir and adds new sources to LCAO objects list.
source/source_io/module_parameter/read_input_item_system.cpp	Adds wfc_extrap input item, docs, and validation checks.
source/source_io/module_parameter/input_parameter.h	Adds wfc_extrap parameter with default "none".
source/source_esolver/esolver_ks_lcao.h	Adds wf_history_lcao_ member to ESolver.
source/source_esolver/esolver_ks_lcao.cpp	Initializes history, prepares overlap early, applies extrapolation, rebuilds density, updates history after SCF.
source/source_esolver/esolver_fp.cpp	Skips charge extrapolation when wfc_extrap is enabled (LCAO, istep>0).
CMakeLists.txt	Enforces a minimum C++ standard globally (now 14).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Growl1234]

I think the extrapolation quality itself is reliable at this point: the WFN-based path gives an initial state that is consistently closer to the converged solution than the charge-density path, while preserving the final result.

However, the practical gain is still limited by the remaining SCF iterations. I suspect that this is no longer mainly an issue with the WFN initialization itself. This might be something I plan to investigate before moving on to k-point support and higher-order predictors, but for a seperate PR.

Therefore, I consider this PR ready now and would prefer not to delay it for further changes. Any review comments on this PR?

[mohanchen]

Thank you for your pull request. This PR presents a creative idea, and we are open to merging it, yet several issues need to be discussed first:
First, has this algorithm been formally published? Are there other software packages that implement similar algorithms? Could you also document the relevant algorithm details within this issue thread?
Second, we need to confirm whether this algorithm delivers tangible performance benefits. Integrating it will require substantial modifications to the code framework and complicate the runtime logic of the LCAO module. We only intend to merge acceleration algorithms with proven practical value. If the feature ends up unused after merging, there is no justification for introducing extra complexity to the codebase.
Third, we prefer minimal edits to esolver files for all new feature implementations. For instance, the current implementation adds over one hundred lines of code to esolver_ks_lcao.cpp, which is not acceptable. Modifications limited to fewer than ten lines would be reasonable. The core design principle of the esolver module is to maintain a streamlined workflow; it is not meant to host detailed implementations of specific algorithms.

[Growl1234]

Thank you for reviewing!

the current implementation adds over one hundred lines of code to esolver_ks_lcao.cpp

Those code is most likely for debugging and finding errors. Once further validation from maintainer's side is done, they could be considered dropped.

[Growl1234]

First, has this algorithm been formally published? Are there other software packages that implement similar algorithms? Could you also document the relevant algorithm details within this issue thread?

This is not intended to introduce a "creative algorithm" or any "new method". It just implements the basic, lowest-order wavefunction-history initialization referred to as use_prev_wf here: the converged wavefunction from the previous ionic step is retained, reorthonormalized with respect to the current overlap matrix, and then used to reconstruct the density matrix and charge density before the normal SCF cycle.

This basic idea is already used, in various forms, in many quantum-chemistry and electronic-structure packages, including Gaussian, ORCA, and CP2K. In particular, the CP2K implementation was the direct motivation for introducing this capability in ABACUS. Its USE_PREV_WF path, together with methods built on top of the same infrastructure, especially ASPC, often performs well in practical geometry optimizations and molecular-dynamics calculations and is one of the useful strengths of CP2K in this area.

Moreover, this low-level capability is also a necessary foundation for introducing formally published higher-order wavefunction-extrapolation methods, such as ASPC. These methods do not merely "extrapolate" MO coefficient matrix; they require a consistent wavefunction-history backend, including the reorthonormalization of predicted orbitals in the current basis and the subsequent reconstruction of the density matrix and charge density.

[Growl1234]

Second, we need to confirm whether this algorithm delivers tangible performance benefits. Integrating it will require substantial modifications to the code framework and complicate the runtime logic of the LCAO module. We only intend to merge acceleration algorithms with proven practical value. If the feature ends up unused after merging, there is no justification for introducing extra complexity to the codebase.

For the current Gamma-only NAO benchmark, the WFN-based initialization reduces the total number of SCF iterations from 44 to 35 and reduces the total runtime from about 32.7 s to 28.2 s, while preserving the final result. This is the result from small-cell test, but if tested with large cells, the improvements should be more significant. That said, since it is not yet implemented with k-points, this PR should not be regarded as broadly applicable or as demonstrating general performance improvements across all ABACUS workflows.

[Growl1234]

Third, we prefer minimal edits to esolver files for all new feature implementations. For instance, the current implementation adds over one hundred lines of code to esolver_ks_lcao.cpp, which is not acceptable. Modifications limited to fewer than ten lines would be reasonable. The core design principle of the esolver module is to maintain a streamlined workflow; it is not meant to host detailed implementations of specific algorithms.

I agree with this point. The current implementation leaves too much WFN-specific logic in ESolver_KS_LCAO, while the esolver should only coordinate the general SCF workflow. I will attempt to move the parts regarding WFN-based extrapolation path into module_extrap later. This should reduce the feature-specific changes in the esolver files to a few calls and keep the detailed algorithmic implementation self-contained in module_extrap.

Btw, the diagnostics part in the implementation most likely can be dropped.