Docs: SchmidtOrth in david (deepmodeling#4855)

source/module_hsolver/diago_david.cpp

@@ -1,6 +1,6 @@
 #include "diago_david.h"
 
-#include "module_base/memory.h"
+// #include "module_base/memory.h"
 #include "module_base/timer.h"
 #include "module_base/module_device/device.h"
 
@@ -112,6 +112,7 @@ DiagoDavid<T, Device>::DiagoDavid(const Real* precondition_in,
     setmem_complex_op()(this->ctx, this->lagrange_matrix, 0, nband * nband);
 
 #if defined(__CUDA) || defined(__ROCM)
+    // device precondition array
     if (this->device == base_device::GpuDevice)
     {
         resmem_var_op()(this->ctx, this->d_precondition, dim);
@@ -933,6 +934,19 @@ void DiagoDavid<T, Device>::refresh(const int& dim,
     return;
 }
 
+/**
+ * SchmidtOrth function performs orthogonalization of the starting eigenfunction to those already calculated.
+ * It takes the dimension of the basis, number of bands, index of the current band, starting eigenfunction psi_m,
+ * lagrange_m array, mm_size, and mv_size as input parameters.
+ *
+ * @param dim The dimension of the basis.
+ * @param nband The number of bands.
+ * @param m The index of the current band.
+ * @param spsi Pointer to the starting eigenfunction psi_m.
+ * @param lagrange_m Pointer to the lagrange_m array.
+ * @param mm_size The size of the square matrix for future lagranges.
+ * @param mv_size The size of the lagrange_m array.
+ */
 template <typename T, typename Device>
 void DiagoDavid<T, Device>::SchmidtOrth(const int& dim,
                                             const int nband,
@@ -955,6 +969,7 @@ void DiagoDavid<T, Device>::SchmidtOrth(const int& dim,
     assert(m >= 0);
     assert(m < nband);
 
+    // psi_m = basis[m]
     T* psi_m = basis + dim*m;
 
     // std::complex<double> *lagrange = new std::complex<double>[m + 1];
@@ -963,7 +978,8 @@ void DiagoDavid<T, Device>::SchmidtOrth(const int& dim,
     // calculate the square matrix for future lagranges
     if (mm_size != 0)
     {
-        //<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+        // lagrange_m[m - mv_size + 1 - mm_size]
+        // = basis[m - mv_size + 1 - mm_size]' * spsi[m]
         gemm_op<T, Device>()(this->ctx,
                                   'C',
                                   'N',
@@ -981,6 +997,8 @@ void DiagoDavid<T, Device>::SchmidtOrth(const int& dim,
         );
     }
     // calculate other lagranges for this band
+    // lagrange_m[m - mv_size + 1]
+    // = basis[m - mv_size + 1]' * spsi[m]
     gemv_op<T, Device>()(this->ctx,
                               'C',
                               dim,
@@ -1002,6 +1020,8 @@ void DiagoDavid<T, Device>::SchmidtOrth(const int& dim,
 
     assert(psi_norm > 0.0);
 
+    // / psi_m = psi_m - \sum_{i < m} \langle psi(i)|S|psi(m) \rangle psi(i)
+    // psi_m = psi_m - basis * lagrange_m
     gemv_op<T, Device>()(this->ctx,
                               'N',
                               dim,
@@ -1015,6 +1035,7 @@ void DiagoDavid<T, Device>::SchmidtOrth(const int& dim,
                               psi_m,
                               1);
 
+    // psi_norm = psi_norm - lagrange_m · lagrange_m
     psi_norm -= dot_real_op<T, Device>()(this->ctx, m, lagrange_m, lagrange_m, false);
 
     // for (int j = 0; j < m; j++)
@@ -1041,6 +1062,7 @@ void DiagoDavid<T, Device>::SchmidtOrth(const int& dim,
     }
     else
     {
+        // psi_m = psi_m / psi_norm
         vector_div_constant_op<T, Device>()(this->ctx, dim, psi_m, psi_m, psi_norm);
         // for (int i = 0; i < npw; i++)
         // {
@@ -1053,6 +1075,15 @@ void DiagoDavid<T, Device>::SchmidtOrth(const int& dim,
     return;
 }
 
+/**
+ * @brief Plans the Schmidt orthogonalization for a given number of bands.
+ * 
+ * @tparam T The type of the elements in the vectors.
+ * @tparam Device The device on which the computation will be performed.
+ * @param nband The number of bands.
+ * @param pre_matrix_mm_m The vector to store the matrix sizes.
+ * @param pre_matrix_mv_m The vector to store the number of matrix-vector multiplications.
+ */
 template <typename T, typename Device>
 void DiagoDavid<T, Device>::planSchmidtOrth(const int nband, std::vector<int>& pre_matrix_mm_m, std::vector<int>& pre_matrix_mv_m)
 {