Background

Currently, the standard SCF (Self-Consistent Field) initialization typically relies on the superposition of atomic densities (or random wavefunctions/potentials). While robust for simple systems, this approach can lead to slow convergence or convergence to local minima for complex systems (e.g., strongly correlated materials, large magnetic supercells, or systems with topological orders).There are scenarios where a high-quality Hamiltonian guess is available in real space (e.g., from Machine Learning potentials, Wannier90 tight-binding models, or previous lower-precision calculations). Currently, there is no direct interface to inject this Hamiltonian $H(\mathbf{R})$ to construct the initial density matrix.

Describe the solution you'd like

I propose adding functionality to initialize the SCF cycle by reading a provided real-space Hamiltonian matrix.Workflow:Input: The user provides a file containing the real-space Hamiltonian matrix elements (e.g., H_real_space.dat or similar format). The format is sparse matrix format (CSR).

Process:

Read the hopping parameters $\langle \phi_i(\mathbf{0}) | \hat{H} | \phi_j(\mathbf{R}) \rangle$ .

Perform a Fourier transform to construct the $k$-space Hamiltonian $H(\mathbf{k})$ .

Diagonalize $H(\mathbf{k})$ to obtain the initial wavefunctions/eigenvalues.

Construct the initial density matrix $\rho_{init}$ from these eigenstates.Execution: Start the first SCF iteration using this calculated $\rho_{init}$.

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.