deepmodeling · mohanchen · Sep 9, 2026 · Sep 7, 2026 · Sep 8, 2026 · Sep 8, 2026
diff --git a/source/source_base/matrix_block.h b/source/source_base/matrix_block.h
@@ -0,0 +1,33 @@
+#ifndef MODULE_BASE_MATRIX_BLOCK_H
+#define MODULE_BASE_MATRIX_BLOCK_H
+
+#include <cstddef>
+
+namespace ModuleBase
+{
+
+/**
+ * @brief A non-owning description of a matrix stored in memory.
+ *
+ * It records only where the matrix lives and how it is laid out: the data
+ * pointer, the local number of rows and columns, and the BLACS array
+ * descriptor when the matrix is block-cyclically distributed. It carries no
+ * physical meaning, so it can be shared between the code that fills a matrix
+ * and the code that diagonalizes it without either side depending on the
+ * other.
+ *
+ * @note This is an aggregate on purpose; several call sites brace-initialize
+ * it as MatrixBlock<T>{p, row, col, desc}.
+ */
+template <typename T> struct MatrixBlock
+{
+    /* would change to Eigen in the future */
+    T* p;
+    size_t row;
+    size_t col;
+    const int* desc;
+};
+
+} // namespace ModuleBase
+
+#endif // MODULE_BASE_MATRIX_BLOCK_H
diff --git a/source/source_hamilt/matrixblock.h b/source/source_hamilt/matrixblock.h
@@ -1,19 +1,19 @@
 #ifndef MATRIXBLOCK_H
 #define MATRIXBLOCK_H
 
-#include <cstddef>
+#include "source_base/matrix_block.h"
+
 namespace hamilt
 {
 
-template <typename T> struct MatrixBlock
-{
-    /* this is a simple template block of a matrix
-       would change to Eigen in the future */
-    T* p;
-    size_t row;
-    size_t col;
-    const int* desc;
-};
+/// MatrixBlock only describes a memory layout, so it now lives in source_base
+/// and eigensolvers can use it without including the Hamiltonian interface.
+/// This alias keeps the historical hamilt::MatrixBlock spelling working.
+///
+/// TODO: this header is a temporary compatibility shim. Once every call site
+/// spells the type as ModuleBase::MatrixBlock and includes
+/// source_base/matrix_block.h directly, delete this file.
+using ModuleBase::MatrixBlock;
 
 } // namespace hamilt
-#endif
+#endif
diff --git a/source/source_hsolver/diago_bpcg.h b/source/source_hsolver/diago_bpcg.h
@@ -7,7 +7,6 @@
 #include "source_base/module_device/memory_op.h"
 #include "source_base/module_device/types.h"
 #include "source_base/para_gemm.h"
-#include "source_hamilt/hamilt.h"
 #include "source_hsolver/kernels/hegvd_op.h"
 #include "source_hsolver/para_lin_tf.h"
 

diff --git a/source/source_hsolver/diago_cusolver.cpp b/source/source_hsolver/diago_cusolver.cpp
@@ -32,8 +32,8 @@ DiagoCusolver<T>::~DiagoCusolver()
 // Diagonalization function
 template <typename T>
 void DiagoCusolver<T>::diag(
-    hamilt::MatrixBlock<T>& h_mat,
-    hamilt::MatrixBlock<T>& s_mat,
+    ModuleBase::MatrixBlock<T>& h_mat,
+    ModuleBase::MatrixBlock<T>& s_mat,
     psi::Psi<T>& psi,
     Real* eigenvalue_in)
 {

diff --git a/source/source_hsolver/diago_cusolver.h b/source/source_hsolver/diago_cusolver.h
@@ -2,9 +2,9 @@
 #define DIAGOCUSOLVER_H
 
 #include "source_base/macros.h"   // GetRealType
-#include "source_hamilt/hamilt.h"
-#include "source_basis/module_ao/parallel_orbitals.h"
+#include "source_base/matrix_block.h"
 #include "source_hsolver/kernels/cuda/diag_cusolver.cuh"
+#include "source_psi/psi.h"
 
 namespace hsolver
 {
@@ -26,8 +26,8 @@ class DiagoCusolver
 
     // Override the diag function for CUSOLVER diagonalization
     void diag(
-      hamilt::MatrixBlock<T>& h_mat,
-      hamilt::MatrixBlock<T>& s_mat,
+      ModuleBase::MatrixBlock<T>& h_mat,
+      ModuleBase::MatrixBlock<T>& s_mat,
       psi::Psi<T>& psi,
       Real* eigenvalue_in);
 

diff --git a/source/source_hsolver/diago_cusolvermp.cpp b/source/source_hsolver/diago_cusolvermp.cpp
@@ -2,6 +2,7 @@
 
 #include "diago_cusolvermp.h"
 
+#include "source_base/matrix_block.h"
 #include "source_base/module_external/blas_connector.h"
 #include "source_base/timer.h"
 #include "source_base/tool_title.h"
@@ -14,7 +15,7 @@ template <typename T>
 void DiagoCusolverMP<T>::diag(hamilt::Hamilt<T>* phm_in, psi::Psi<T>& psi, Real* eigenvalue_in)
 {
     ModuleBase::TITLE("DiagoCusolverMP", "diag");
-    hamilt::MatrixBlock<T> h_mat, s_mat;
+    ModuleBase::MatrixBlock<T> h_mat, s_mat;
     phm_in->matrix(h_mat, s_mat);
 
     std::vector<Real> eigen(this->nlocal, 0.0);

diff --git a/source/source_hsolver/diago_elpa.cpp b/source/source_hsolver/diago_elpa.cpp
@@ -7,8 +7,8 @@
 #include "source_base/tool_title.h"
 #include "source_base/tool_quit.h"
 
-typedef hamilt::MatrixBlock<double> matd;
-typedef hamilt::MatrixBlock<std::complex<double>> matcd;
+typedef ModuleBase::MatrixBlock<double> matd;
+typedef ModuleBase::MatrixBlock<std::complex<double>> matcd;
 
 namespace hsolver {
 #ifdef __MPI
@@ -141,8 +141,8 @@ void DiagoElpa<double>::diag(hamilt::Hamilt<double>* phm_in,
 
 #ifdef __MPI
 template <>
-void DiagoElpa<std::complex<double>>::diag_pool(hamilt::MatrixBlock<std::complex<double>>& h_mat,
-    hamilt::MatrixBlock<std::complex<double>>& s_mat,
+void DiagoElpa<std::complex<double>>::diag_pool(ModuleBase::MatrixBlock<std::complex<double>>& h_mat,
+    ModuleBase::MatrixBlock<std::complex<double>>& s_mat,
     psi::Psi<std::complex<double>>& psi,
     Real* eigenvalue_in,
     MPI_Comm& comm)
@@ -170,8 +170,8 @@ void DiagoElpa<std::complex<double>>::diag_pool(hamilt::MatrixBlock<std::complex
 }
 
 template <>
-void DiagoElpa<double>::diag_pool(hamilt::MatrixBlock<double>& h_mat,
-    hamilt::MatrixBlock<double>& s_mat,
+void DiagoElpa<double>::diag_pool(ModuleBase::MatrixBlock<double>& h_mat,
+    ModuleBase::MatrixBlock<double>& s_mat,
     psi::Psi<double>& psi,
     Real* eigenvalue_in,
     MPI_Comm& comm)

diff --git a/source/source_hsolver/diago_elpa.h b/source/source_hsolver/diago_elpa.h
@@ -2,6 +2,7 @@
 #define DIAGOELPA_H
 
 #include "source_base/macros.h"   // GetRealType
+#include "source_base/matrix_block.h"
 #include "source_hamilt/hamilt.h"
 #include "source_basis/module_ao/parallel_orbitals.h"
 
@@ -22,7 +23,7 @@ class DiagoElpa
     void diag(hamilt::Hamilt<T>* phm_in, psi::Psi<T>& psi, Real* eigenvalue_in);
 #ifdef __MPI
     // diagnolization used in parallel-k case
-    void diag_pool(hamilt::MatrixBlock<T>& h_mat, hamilt::MatrixBlock<T>& s_mat, psi::Psi<T>& psi, Real* eigenvalue_in, MPI_Comm& comm);
+    void diag_pool(ModuleBase::MatrixBlock<T>& h_mat, ModuleBase::MatrixBlock<T>& s_mat, psi::Psi<T>& psi, Real* eigenvalue_in, MPI_Comm& comm);
     MPI_Comm setmpicomm(); // set mpi comm;
     static int elpa_num_thread;  // need to set mpi_comm or not,-1 not,else the number of mpi needed
 #endif

diff --git a/source/source_hsolver/diago_elpa_native.cpp b/source/source_hsolver/diago_elpa_native.cpp
@@ -48,8 +48,8 @@ MPI_Comm DiagoElpaNative<T>::setmpicomm()
 
 #ifdef __MPI
 template <typename T>
-void DiagoElpaNative<T>::diag_pool(hamilt::MatrixBlock<T>& h_mat,
-                                   hamilt::MatrixBlock<T>& s_mat,
+void DiagoElpaNative<T>::diag_pool(ModuleBase::MatrixBlock<T>& h_mat,
+                                   ModuleBase::MatrixBlock<T>& s_mat,
                                    psi::Psi<T>& psi,
                                    Real* eigenvalue_in,
                                    MPI_Comm& comm)
@@ -147,7 +147,7 @@ void DiagoElpaNative<T>::diag(hamilt::Hamilt<T>* phm_in, psi::Psi<T>& psi, Real*
 {
     ModuleBase::TITLE("DiagoElpaNative", "diag");
 #ifdef __MPI
-    hamilt::MatrixBlock<T> h_mat, s_mat;
+    ModuleBase::MatrixBlock<T> h_mat, s_mat;
     phm_in->matrix(h_mat, s_mat);
     MPI_Comm COMM_DIAG = setmpicomm(); // set mpi_comm needed
     diag_pool(h_mat, s_mat, psi, eigenvalue_in, COMM_DIAG);

diff --git a/source/source_hsolver/diago_elpa_native.h b/source/source_hsolver/diago_elpa_native.h
@@ -2,6 +2,7 @@
 #define DIAGOELPANATIVE_H
 
 #include "source_base/macros.h"   // GetRealType
+#include "source_base/matrix_block.h"
 #include "source_hamilt/hamilt.h"
 #include "source_basis/module_ao/parallel_orbitals.h"
 
@@ -24,7 +25,7 @@ class DiagoElpaNative
     void diag(hamilt::Hamilt<T>* phm_in, psi::Psi<T>& psi, Real* eigenvalue_in);
 #ifdef __MPI
     // diagnolization used in parallel-k case
-    void diag_pool(hamilt::MatrixBlock<T>& h_mat, hamilt::MatrixBlock<T>& s_mat, psi::Psi<T>& psi, Real* eigenvalue_in, MPI_Comm& comm);
+    void diag_pool(ModuleBase::MatrixBlock<T>& h_mat, ModuleBase::MatrixBlock<T>& s_mat, psi::Psi<T>& psi, Real* eigenvalue_in, MPI_Comm& comm);
     MPI_Comm setmpicomm(); // set mpi comm;
     static int elpa_num_thread;  // need to set mpi_comm or not,-1 not,else the number of mpi needed
     static int lastmpinum; // last using mpi;

diff --git a/source/source_hsolver/diago_lapack.cpp b/source/source_hsolver/diago_lapack.cpp
@@ -8,16 +8,16 @@
 
 #include <cstring>
 
-typedef hamilt::MatrixBlock<double> matd;
-typedef hamilt::MatrixBlock<std::complex<double>> matcd;
+typedef ModuleBase::MatrixBlock<double> matd;
+typedef ModuleBase::MatrixBlock<std::complex<double>> matcd;
 
 namespace hsolver
 {
 namespace
 {
 template <typename T>
-void check_lapack_layout(const hamilt::MatrixBlock<T>& h_mat,
-                         const hamilt::MatrixBlock<T>& s_mat,
+void check_lapack_layout(const ModuleBase::MatrixBlock<T>& h_mat,
+                         const ModuleBase::MatrixBlock<T>& s_mat,
                          const std::size_t n)
 {
     if (h_mat.row != n || h_mat.col != n || s_mat.row != n || s_mat.col != n)
@@ -68,8 +68,8 @@ void DiagoLapack<std::complex<double>>::diag(hamilt::Hamilt<std::complex<double>
 
 #ifdef __MPI
  template<>
-    void DiagoLapack<double>::diag_pool(hamilt::MatrixBlock<double>& h_mat,
-    hamilt::MatrixBlock<double>& s_mat,
+    void DiagoLapack<double>::diag_pool(ModuleBase::MatrixBlock<double>& h_mat,
+    ModuleBase::MatrixBlock<double>& s_mat,
     psi::Psi<double>& psi,
     Real* eigenvalue_in,
     MPI_Comm& comm)
@@ -83,8 +83,8 @@ void DiagoLapack<std::complex<double>>::diag(hamilt::Hamilt<std::complex<double>
     BlasConnector::copy(this->nbands, eigen.data(), inc, eigenvalue_in, inc);
 }
     template<>
-    void DiagoLapack<std::complex<double>>::diag_pool(hamilt::MatrixBlock<std::complex<double>>& h_mat,
-    hamilt::MatrixBlock<std::complex<double>>& s_mat,
+    void DiagoLapack<std::complex<double>>::diag_pool(ModuleBase::MatrixBlock<std::complex<double>>& h_mat,
+    ModuleBase::MatrixBlock<std::complex<double>>& s_mat,
     psi::Psi<std::complex<double>>& psi,
     Real* eigenvalue_in,
     MPI_Comm& comm)

diff --git a/source/source_hsolver/diago_lapack.h b/source/source_hsolver/diago_lapack.h
@@ -9,6 +9,7 @@
 #define DIAGOLAPACK_H
 
 #include "source_base/macros.h"   // GetRealType
+#include "source_base/matrix_block.h"
 #include "source_hamilt/hamilt.h"
 #include "source_base/matrix.h"
 #include "source_basis/module_ao/parallel_orbitals.h"
@@ -33,7 +34,7 @@ class DiagoLapack
     void diag(hamilt::Hamilt<T>* phm_in, psi::Psi<T>& psi, Real* eigenvalue_in);
   #ifdef __MPI
     // diagnolization used in parallel-k case
-    void diag_pool(hamilt::MatrixBlock<T>& h_mat, hamilt::MatrixBlock<T>& s_mat, psi::Psi<T>& psi, Real* eigenvalue_in, MPI_Comm& comm);
+    void diag_pool(ModuleBase::MatrixBlock<T>& h_mat, ModuleBase::MatrixBlock<T>& s_mat, psi::Psi<T>& psi, Real* eigenvalue_in, MPI_Comm& comm);
 #endif
 
     void dsygvx_diag(const int ncol,

diff --git a/source/source_hsolver/diago_pexsi.cpp b/source/source_hsolver/diago_pexsi.cpp
@@ -3,13 +3,14 @@
 #include <memory>
 #ifdef __PEXSI
 #include "diago_pexsi.h"
+#include "source_base/matrix_block.h"
 #include "source_base/tool_title.h"
 #include "source_base/tool_quit.h"
 #include "source_basis/module_ao/parallel_orbitals.h"
 #include "module_pexsi/pexsi_solver.h"
 
-typedef hamilt::MatrixBlock<double> matd;
-typedef hamilt::MatrixBlock<std::complex<double>> matcd;
+typedef ModuleBase::MatrixBlock<double> matd;
+typedef ModuleBase::MatrixBlock<std::complex<double>> matcd;
 
 namespace hsolver
 {

diff --git a/source/source_hsolver/diago_scalapack.cpp b/source/source_hsolver/diago_scalapack.cpp
@@ -8,15 +8,15 @@
 #include "diago_scalapack.h"
 
 #include "source_base/global_function.h"
+#include "source_base/matrix_block.h"
 #include "source_base/module_external/blacs_connector.h"
 #include "source_base/module_external/scalapack_connector.h"
-#include "source_hamilt/matrixblock.h"
 
 #include <cassert>
 #include <cstring>
 
-typedef hamilt::MatrixBlock<double> matd;
-typedef hamilt::MatrixBlock<std::complex<double>> matcd;
+typedef ModuleBase::MatrixBlock<double> matd;
+typedef ModuleBase::MatrixBlock<std::complex<double>> matcd;
 
 namespace hsolver
 {
@@ -59,8 +59,8 @@ int blacs_grid_size(const int* const desc)
 
 #ifdef __MPI
  template<>
-    void DiagoScalapack<double>::diag_pool(hamilt::MatrixBlock<double>& h_mat,
-    hamilt::MatrixBlock<double>& s_mat,
+    void DiagoScalapack<double>::diag_pool(ModuleBase::MatrixBlock<double>& h_mat,
+    ModuleBase::MatrixBlock<double>& s_mat,
     psi::Psi<double>& psi,
     Real* eigenvalue_in,
     MPI_Comm& comm)
@@ -73,8 +73,8 @@ int blacs_grid_size(const int* const desc)
     BlasConnector::copy(this->nbands, eigen.data(), inc, eigenvalue_in, inc);
 }
     template<>
-    void DiagoScalapack<std::complex<double>>::diag_pool(hamilt::MatrixBlock<std::complex<double>>& h_mat,
-    hamilt::MatrixBlock<std::complex<double>>& s_mat,
+    void DiagoScalapack<std::complex<double>>::diag_pool(ModuleBase::MatrixBlock<std::complex<double>>& h_mat,
+    ModuleBase::MatrixBlock<std::complex<double>>& s_mat,
     psi::Psi<std::complex<double>>& psi,
     Real* eigenvalue_in,
     MPI_Comm& comm)

diff --git a/source/source_hsolver/diago_scalapack.h b/source/source_hsolver/diago_scalapack.h
@@ -13,6 +13,7 @@
 #include <vector>
 
 #include "source_base/macros.h"   // GetRealType
+#include "source_base/matrix_block.h"
 #include "source_hamilt/hamilt.h"
 #include "source_psi/psi.h"
 #include "source_base/complexmatrix.h"
@@ -34,7 +35,7 @@ namespace hsolver
     void diag(hamilt::Hamilt<T>* phm_in, psi::Psi<T>& psi, Real* eigenvalue_in);
 #ifdef __MPI
     // diagnolization used in parallel-k case
-    void diag_pool(hamilt::MatrixBlock<T>& h_mat, hamilt::MatrixBlock<T>& s_mat, psi::Psi<T>& psi, Real* eigenvalue_in, MPI_Comm& comm);
+    void diag_pool(ModuleBase::MatrixBlock<T>& h_mat, ModuleBase::MatrixBlock<T>& s_mat, psi::Psi<T>& psi, Real* eigenvalue_in, MPI_Comm& comm);
 #endif
 
   private: