Subspace acceleration for LCAO spin-constrained DFT (opt-in)

[dyzheng]

Background

Background

LCAO DeltaSpin calculations spend a large fraction of time in full Hamiltonian diagonalization inside the lambda loop. This issue adds an opt-in subspace acceleration path for LCAO spin-constrained DFT that works in a reduced subspace, with a mixed-precision GEMM implementation, controlled by the sc_strategy parameter (normal by default, i.e. no behavior change).

Feature work

1. Subspace engine (lcao_subspace.cpp, ~870 lines): build the constraint subspace, project H/S, solve the reduced problem, and rotate back; supports nspin=4 LCAO subspace with Pauli sign fixes.
2. Diagonalization engine (diagonalization_engine.{h,cpp}, ~1.1k lines): a reusable engine abstracting the (generalized) eigensolver calls used by the subspace path; C++11-compatible implementation.
3. Mixed-precision GEMM: FP32 accumulation with FP64 storage for the LCAO subspace GEMMs, reducing cost while keeping accuracy.
4. Correct subspace projector matrices: replace cal_PI_sub with calculate_PI_sub_from_hr for computing P_I = D_I^dag * D_I; add cal_PI_sub() to DeltaSpin<OperatorLCAO>.
5. ScaLAPACK correctness: use global NLOCAL instead of local nrow in pzgemm calls for the subspace acceleration.
6. Performance: eliminate gather redundancy in lcao_PI_sub_save_ and reduce BFGS allocation jitter.
7. RI_2D_Comm extensions: add comm_map2 and set_value_add overloads needed by the DeltaSpin LCAO subspace path (also removes 114 duplicate template definitions in RI_2D_Comm.hpp that broke the GNU toolchain CI build).
8. ElecStateLCAO support: add init_DM()/get_DM() for the DeltaSpin LCAO subspace path.

Safeguards

• Subspace path is opt-in via sc_strategy; default normal reproduces existing results bit-for-bit.
• Subspace is disabled for nspin=4 where it is not applicable; a final full diagonalization is performed after the subspace loop for nspin=4.

Scope

• source/source_lcao/module_deltaspin/ (lcao_subspace.cpp, diagonalization_engine., lambda_loop.cpp, spin_constrain.)
• source/source_estate/elecstate_lcao.h
• source/source_lcao/module_ri/RI_2D_Comm.hpp
• Docs: subspace acceleration usage guide
• Unit tests for the subspace/diagonalization engine

Testing

• Compare sc_strategy=normal vs fast on LCAO DeltaSpin cases: total energy and constrained moments must agree within tolerance.
• GNU toolchain CI build must pass (RI_2D_Comm redefinition fix).
• Unit tests: DeltaHcc_GemmContribution (column-major GEMM indexing), subspace engine tests.

Dependencies

• Depends on Issue 3 (DeltaSpin lambda strategies and SpinConstrain refactor).

Related

Split out from PR #7693.

Describe the solution you'd like

Above.

Task list only for developers

• Notice possible changes of behavior
• Explain the changes of codes in core modules of ESolver, HSolver, ElecState, Hamilt, Operator or Psi

Notice Possible Changes of Behavior (Reminder only for developers)

No response

Notice any changes of core modules (Reminder only for developers)

No response

Notice Possible Changes of Core Modules (Reminder only for developers)

No response

Additional Context

No response

Task list for Issue attackers (only for developers)

• Review and understand the proposed feature and its importance.
• Research on the existing solutions and relevant research articles/resources.
• Discuss with the team to evaluate the feasibility of implementing the feature.
• Create a design document outlining the proposed solution and implementation details.
• Get feedback from the team on the design document.
• Develop the feature following the agreed design.
• Write unit tests and integration tests for the feature.
• Update the documentation to include the new feature.
• Perform code review and address any issues.
• Merge the feature into the main branch.
• Monitor for any issues or bugs reported by users after the feature is released.
• Address any issues or bugs reported by users and continuously improve the feature.