DeltaSpin for PW basis (nspin=1/2/4), lambda update strategies, and direction_only mode

[dyzheng]

Background

Background

DeltaSpin (constrained magnetic moment DFT) previously had limited basis/nspin coverage. This issue ports DeltaSpin to the PW basis for nspin=1/2/4, introduces configurable lambda update strategies, and adds a direction_only constraint mode for noncollinear calculations. Several correctness bugs in the existing implementation are fixed along the way.

Bugs to fix

1. Wrong E_lambda formula: change from -sum(lambda*Mi) to -sum(lambda*(Mi - Mtarget)), and remove the is_Mi_converged gate.
2. Inconsistent lambda sign convention between PW and LCAO paths: unify to E' = E + lambda*(M - Mtarget).
3. reduce_double_allpool uses wrong communicator size: use GlobalV::NPROC_IN_POOL (fixes nspin=4 reference mismatches under kpar>1).
4. run_lambda_loop iteration indexing error in the PW path.
5. SCF crash and charge-density sync issues in LCAO DeltaSpin.
6. Segfault in cal_escon(): add empty-check guard.
7. Memory leak in cal_pre_HR() when reinitialized.
8. current_spin not propagated through the operator chain in init().

Feature work

• PW nspin=1/2/4 support: npol_ member, get_spin_sign(ik), accumulate_Mi_from_becp(), pauli_to_moment(); PW-specific update_psi_charge_pw_cpu/gpu() using subspace diagonalization.
• Lambda update strategies selectable via new input sc_lambda_strategy: BFGS (default), linear_response, augmented_lagrangian, hybrid_delayed.
• direction_only mode (sc_direction_only, default false): project lambda perpendicular to the target magnetization; two-phase BFGS with sc_dir_phase1_steps (default 10) phase-1 steps; useful for noncollinear constraints.
• SCF threshold mode sc_scf_thr_mode (off/immediate, default off).
• Execution strategy sc_strategy (normal/fast/off, default normal).
• Full/incremental lambda update strategies for both PW and LCAO paths.
• Remove the deprecated sc_scf_nmin parameter and dead parameters (sc_mu_init, sc_mu_max, sc_mu_growth, sc_mix_beta).
• Refactor: cache frequently-used PARAM.inp values as SpinConstrain members; add getters for basis_type/ks_solver/nbands; add #ifdef __LCAO guards for LCAO-only code.

New INPUT parameters

Parameter	Description	Default
sc_lambda_strategy	Lambda update strategy	BFGS
sc_direction_only	Project lambda perpendicular to target moment	false
sc_scf_thr_mode	SCF threshold mode (off/immediate)	off
sc_dir_phase1_steps	Phase-1 BFGS steps for direction_only mode	10
sc_strategy	Execution strategy (normal/fast/off)	normal

Scope

• source/source_lcao/module_deltaspin/ (spin_constrain., lambda_loop.cpp, cal_mw, init_sc.cpp, deltaspin_lcao.*)
• source/source_pw/module_pwdft/deltaspin_pw.cpp, setup_pot.cpp, op_pw_nl.*
• source/source_esolver/esolver_ks_lcao.cpp, lcao_others.cpp
• source/source_estate/elecstate_pw.*, elecstate_lcao.h, module_dm/
• Input registration: read_input_item_*.cpp, parameters.yaml, input-main.md
• Unit tests: module_deltaspin/test/deltaspin_pw_test.cpp, strategy tests
• Integration tests: DeltaSpin-only and DFTU+DeltaSpin cases under tests/17_DS_DFTU/
• Docs: comprehensive DeltaSpin guide in docs/advanced/scf/spin.md

Testing

• PW and LCAO DeltaSpin cases for nspin=1/2/4, including ReadLam, threshold variants, BFGS strategy, and direction_only cases.
• Verify PW/LCAO lambda sign consistency on the same system.

Dependencies

• Depends on Issue 1 (onsite projector npol interfaces, setup_pot plumbing).

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.