comment: modify comments for pw module

Author: Qianruipku

source/module_pw/fft.h

@@ -27,10 +27,16 @@ class FFT
 
 	FFT();
 	~FFT();
+	
+	// init parameters of fft
 	void initfft(int nx_in, int bigny_in, int nz_in, int liy_in, int riy_in, int ns_in, int nplane_in, 
 				 int nproc_in, bool gamma_only_in, bool mpifft_in = false);
-	void setupFFT();
-	void cleanFFT();
+
+	//init fftw_plans
+	void setupFFT(); 
+
+	//destroy fftw_plans
+	void cleanFFT(); 
 
 	void fftzfor(std::complex<double>* & in, std::complex<double>* & out);
 	void fftzbac(std::complex<double>* & in, std::complex<double>* & out);
@@ -50,10 +56,12 @@ class FFT
 #endif
 
 public:
-	void initplan();
+	//init fftw_plans
+	void initplan(); 
 	void initplan_mpi();
 #ifdef __MIX_PRECISION
-	void initplanf();
+	//init fftwf_plans
+	void initplanf(); 
 	void initplanf_mpi();
 #endif
 

source/module_pw/pw_basis.cpp

@@ -52,6 +52,11 @@ PW_Basis:: ~PW_Basis()
     if(startr != NULL) delete[] startr;
 }
 
+/// 
+/// distribute plane wave basis and real-space grids to different processors
+/// set up maps for fft and create arrays for MPI_Alltoall
+/// set up ffts
+///
 void PW_Basis::setuptransform()
 {
     this->distribute_r();
@@ -96,11 +101,11 @@ void PW_Basis::getstartgr()
     return;
 }
 
-//
-// Collect planewaves on current core, and construct gg, gdirect, gcar according to ig2isz and is2ixy.
-// known: ig2isz, is2ixy
-// output: gg, gdirect, gcar
-// 
+///
+/// Collect planewaves on current core, and construct gg, gdirect, gcar according to ig2isz and is2ixy.
+/// known: ig2isz, is2ixy
+/// output: gg, gdirect, gcar
+/// 
 void PW_Basis::collect_local_pw()
 {
     if(gg != NULL) delete[] gg;

source/module_pw/pw_basis.h

@@ -93,13 +93,12 @@ class PW_Basis
     //distribute real-space grids to different processors
     void distribute_r();
 
+    //prepare for MPI_Alltoall
     void getstartgr();
 
-    //distribute plane waves to different processors
-    void distribution_method1(); // x varies fast
-    void distribution_method2(); // sticks sorted according to ixy
-    // void distribution_method3(); // y varies fast
 
+
+    //prepare for transforms between real and reciprocal spaces
     void collect_local_pw();
 
     // void collect_tot_pw(
@@ -120,38 +119,52 @@ class PW_Basis
     int distribution_type;
     int poolnproc;
     int poolrank;
-   
+    //distribute plane waves to different processors
+
+    //method 1: first consider number of plane waves
+    void distribution_method1(); 
+    // Distribute sticks to cores in method 1.
+    void divide_sticks_1(
+        int* st_i,          // x or x + nx (if x < 0) of stick.
+        int* st_j,          // y or y + ny (if y < 0) of stick.
+        int* st_length,     // the stick on (ix, iy) consists of st_length[ix*ny+iy] planewaves.
+        int* npw_per       // number of planewaves on each core.
+    );
 
-// for both distributeg_method1 and distributeg_method2
+    //method 2: first consider number of sticks
+    void distribution_method2();
+    // Distribute sticks to cores in method 2.
+    void divide_sticks_2();
+   
+    //Count the total number of planewaves (tot_npw) and sticks (this->nstot) (in distributeg method1 and method2)
     void count_pw_st(
         int &tot_npw,     // total number of planewaves.
         int* st_length2D, // the number of planewaves that belong to the stick located on (x, y).
         int* st_bottom2D  // the z-coordinate of the bottom of stick on (x, y).
     );
+
+    //get ig2isz and is2ixy
     void get_ig2isz_is2ixy(
         int* st_bottom,     // minimum z of stick, stored in 1d array with tot_nst elements.
         int* st_length     // the stick on (x, y) consists of st_length[x*ny+y] planewaves.
     );
-// for distributeg_method1
+
+    //Collect the x, y indexs, length of the sticks (in distributeg method1)
     void collect_st(
         int* st_length2D,                               // the number of planewaves that belong to the stick located on (x, y), stored in 2d x-y plane.
         int* st_bottom2D,                               // the z-coordinate of the bottom of stick on (x, y), stored in 2d x-y plane.
         int* st_i,                                      // x or x + nx (if x < 0) of stick.
         int* st_j,                                      // y or y + ny (if y < 0) of stick.
         int* st_length                                 // number of planewaves in stick, stored in 1d array with tot_nst elements.
     );
-    void divide_sticks(
-        int* st_i,          // x or x + nx (if x < 0) of stick.
-        int* st_j,          // y or y + ny (if y < 0) of stick.
-        int* st_length,     // the stick on (x, y) consists of st_length[x*ny+y] planewaves.
-        int* npw_per       // number of planewaves on each core.
-    );
+
+    //get istot2bigixy
     void get_istot2bigixy(
         int* st_i,          // x or x + nx (if x < 0) of stick.
         int* st_j          // y or y + ny (if y < 0) of stick.
     );
-// for distributeg_method2
-    void divide_sticks2();
+
+    //Create the maps from ixy to (in method 2)
     void create_maps(
         int* st_length2D,  // the number of planewaves that belong to the stick located on (x, y), stored in 2d x-y plane.
         int* npw_per       // number of planewaves on each core.
@@ -179,16 +192,14 @@ class PW_Basis
     void recip2real(std::complex<float> * in, float *out); //in:(nz, ns)  ; out(nplane,nx*ny)
     void recip2real(std::complex<float> * in, std::complex<float> * out); //in:(nz, ns)  ; out(nplane,nx*ny)
 #endif
+    //gather planes and scatter sticks of all processors
     template<typename T>
-    void gatherp_scatters(std::complex<T> *in, std::complex<T> *out); //gather planes and scatter sticks of all processors
-    template<typename T>
-    void gathers_scatterp(std::complex<T> *in, std::complex<T> *out); //gather sticks of and scatter planes of all processors
-    // void gathers_scatterp2(std::complex<double> *in, std::complex<double> *out); //gather sticks of and scatter planes of all processors
-    // void gatherp_scatters2(std::complex<double> *in, std::complex<double> *out); //gather sticks of and scatter planes of all processors
-    // void gatherp_scatters_gamma(std::complex<double> *in, std::complex<double> *out); //gather planes and scatter sticks of all processors, used when gamma_only
-    // void gathers_scatterp_gamma(std::complex<double> *in, std::complex<double> *out); //gather sticks of and scatter planes of all processors, used when gamma only
+    void gatherp_scatters(std::complex<T> *in, std::complex<T> *out); 
 
+    //gather sticks of and scatter planes of all processors
+    template<typename T>
+    void gathers_scatterp(std::complex<T> *in, std::complex<T> *out); 
 };
 
 }
-#endif //PlaneWave class
+#endif //PlaneWave 

source/module_pw/pw_basis_k.cpp

@@ -99,6 +99,12 @@ void PW_Basis_K::setupIndGk()
 
     return;
 }
+
+/// 
+/// distribute plane wave basis and real-space grids to different processors
+/// set up maps for fft and create arrays for MPI_Alltoall
+/// set up ffts
+///
 void PW_Basis_K::setuptransform()
 {
     this->distribute_r();

source/module_pw/pw_basis_k.h

@@ -8,7 +8,8 @@ namespace ModulePW
 ///
 /// Special pw_basis class.
 /// It includes different k-points
-/// plane waves: <r|g,k>=1/sqrt(V) * exp(i(k+g)r)
+/// plane waves: <r|g,k> = 1/sqrt(V) * exp(i(k+g)r)
+/// f(r) = 1/sqrt(V) * \sum_g{c(g)*exp(i(k+g)r)}
 ///
 class PW_Basis_K : public PW_Basis
 {
@@ -17,6 +18,7 @@ class PW_Basis_K : public PW_Basis
     PW_Basis_K();
     ~PW_Basis_K();
 
+    //init parameters of pw_basis_k class
     void initparameters(
         bool gamma_only_in,
         double ecut_in,
@@ -35,9 +37,15 @@ class PW_Basis_K : public PW_Basis
     double gk_ecut; //Energy cut off for (g+k)^2/2
 
 public:
+    //prepare for transforms between real and reciprocal spaces
     void setuptransform();
+    
+    //create igl2isz_k map array for fft
     void setupIndGk();
+
     int *igl2isz_k; //[npwk_max*nks] map (ig,ik) to (is,iz) 
+
+    //create Direct coordinate, Cartesian coordinate, norm2 of plane waves in each processor
     void collect_local_pw();
 
 public:
@@ -54,9 +62,13 @@ class PW_Basis_K : public PW_Basis
 #endif
 
 public:
-    //operator
+    //operator:
+
+    //calculate g+k
     ModuleBase::Vector3<double> get_GPlusK_cartesian(const int ik, const int ig) const;
+    //calculate g+k.x/y/z
     double get_GPlusK_cartesian_projection(const int ik, const int ig, const int axis) const;
+    //calculate (g+k)^2
     double get_SquareGPlusK_cartesian(const int ik, const int ig) const;
 };
 

source/module_pw/pw_distributeg.cpp

@@ -4,11 +4,11 @@
 
 namespace ModulePW
 {
-//
-//distribute plane waves to different cores
-//Known: G, GT, GGT, nx, ny, nz, poolnproc, poolrank, ggecut
-//output: ig2isz[ig], istot2ixy[is], ixy2istot[ixy], is2ixy[is], ixy2ip[ixy], startnsz_per[ip], nstnz_per[ip], gg[ig], gcar[ig], gdirect[ig], nst, nstot
-//
+/// 
+/// distribute plane waves to different cores
+/// Known: G, GT, GGT, nx, ny, nz, poolnproc, poolrank, ggecut
+/// output: ig2isz[ig], istot2ixy[is], ixy2istot[ixy], is2ixy[is], ixy2ip[ixy], startnsz_per[ip], nstnz_per[ip], gg[ig], gcar[ig], gdirect[ig], nst, nstot
+/// 
 void PW_Basis::distribute_g()
 {
     if(this->distribution_type == 1)
@@ -26,13 +26,13 @@ void PW_Basis::distribute_g()
     return;
 }
 
-//
-// (1) We count the total number of planewaves (tot_npw) and sticks (this->nstot) here.
-// Meanwhile, we record the number of planewaves on (x, y) in st_length2D, and store the smallest z-coordinate of each stick in st_bottom2D,
-// so that we can scan a much smaller area in step(2).
-// known: nx, ny, nz, ggecut, GGT
-// output: tot_npw, this->nstot, st_length2D, st_bottom2D
-//
+///
+/// (1) We count the total number of planewaves (tot_npw) and sticks (this->nstot) here.
+/// Meanwhile, we record the number of planewaves on (x, y) in st_length2D, and store the smallest z-coordinate of each stick in st_bottom2D,
+/// so that we can scan a much smaller area in step(2).
+/// known: nx, ny, nz, ggecut, GGT
+/// output: tot_npw, this->nstot, st_length2D, st_bottom2D
+///
 void PW_Basis::count_pw_st(
         int &tot_npw,     // total number of planewaves.
         int* st_length2D, // the number of planewaves that belong to the stick located on (x, y).
@@ -96,14 +96,14 @@ void PW_Basis::count_pw_st(
     return;
 }
 
-//
-// (5) Construct ig2isz, and is2ixy.
-// is2ixy contains the x-coordinate and y-coordinate of sticks on current core.
-// ig2isz contains the z-coordinate of planewaves on current core.
-// We will scan all the sticks and find the planewaves on them, then store the information into ig2isz and is2ixy.
-// known: this->nstot, st_bottom2D, st_length2D
-// output: ig2isz, is2ixy
-// 
+///
+/// (5) Construct ig2isz, and is2ixy.
+/// is2ixy contains the x-coordinate and y-coordinate of sticks on current core.
+/// ig2isz contains the z-coordinate of planewaves on current core.
+/// We will scan all the sticks and find the planewaves on them, then store the information into ig2isz and is2ixy.
+/// known: this->nstot, st_bottom2D, st_length2D
+/// output: ig2isz, is2ixy
+/// 
 void PW_Basis::get_ig2isz_is2ixy(
     int* st_bottom2D,     // minimum z of stick, stored in 1d array with this->nstot elements.
     int* st_length2D     // the stick on (x, y) consists of st_length[x*ny+y] planewaves.