Doc: modify input parameters for symmetry and Exx

docs/advanced/input_files/input-main.md

@@ -7,6 +7,7 @@
 		- [calculation](#calculation)
 		- [esolver\_type](#esolver_type)
 		- [symmetry](#symmetry)
+		- [symmetry\_prec](#symmetry_prec)
 		- [kpar](#kpar)
 		- [bndpar](#bndpar)
 		- [latname](#latname)
@@ -24,7 +25,6 @@
 		- [nbspline](#nbspline)
 		- [kspacing](#kspacing)
 		- [min\_dist\_coef](#min_dist_coef)
-		- [symmetry\_prec](#symmetry_prec)
 		- [device](#device)
 	- [Variables related to input files](#variables-related-to-input-files)
 		- [stru\_file](#stru_file)
@@ -394,11 +394,24 @@ These variables are used to control general system parameters.
 ### symmetry
 
 - **Type**: Integer
-- **Description**:
-  - -1: no symmetry will be considered.
-  - 0: only time reversal symmetry would be considered in symmetry operations, which implied k point and -k point would be treated as a single k point with twice the weight.
-  - 1: symmetry analysis will be performed to determine the type of Bravais lattice and associated symmetry operations. (point groups only)
-- **Default**: 0
+- **Description**: takes value 1, 0 or -1.
+  - -1: No symmetry will be considered.
+  - 0: Only time reversal symmetry would be considered in symmetry operations, which implied k point and -k point would be treated as a single k point with twice the weight.
+  - 1: Symmetry analysis will be performed to determine the type of Bravais lattice and associated symmetry operations. (point groups, space groups, primitive cells, and irreducible k-points)
+- **Default**: 
+  - -1: if (*[dft_fuctional](#dft_functional)==hse/hf/pbe0/scan0/opt_orb* or *[rpa](#rpa)==True*) and *[calculation](#calculation)!=nscf*. Currently symmetry is not supported in EXX (exact exchange) calculation.
+  - 0: if *[calculation](#calculation)==md/nscf/istate/ienvelope/get_S* or *[gamma_only]==True*
+  - 1: else
+
+### symmetry_prec
+
+- **Type**: Real
+- **Description**: The accuracy for symmetry judgment. Usually the default value is good enough, but if the lattice parameters or atom positions in STRU file is not accurate enough, this value should be enlarged. 
+
+  Note: if *[calculation](#calculation)=cell_relax*, this value can be dynamically enlarged corresponding to the accuracy loss of the lattice parameters and atom positions during the relaxation. There will be a warning message in that case.
+
+- **Default**: 1.0e-5
+- **Unit**:  Bohr
 
 ### kpar
 
@@ -555,13 +568,6 @@ If only one value is set (such as `kspacing 0.5`), then kspacing values of a/b/c
 - **Description**: a factor related to the allowed minimum distance between two atoms. At the beginning, ABACUS will check the structure, and if the distance of two atoms is shorter than min_dist_coef*(standard covalent bond length), we think this structure is unreasonable. If you want to calculate some structures in extreme conditions like high pressure, you should set this parameter as a smaller value or even 0.
 - **Default**: 0.2
 
-### symmetry_prec
-
-- **Type**: Real
-- **Description**: The accuracy for symmetry judgment.
-- **Default**: 1.0e-5
-- **Unit**: Bohr
-
 ### device
 
 - **Type**: String
@@ -1823,41 +1829,50 @@ These variables are relevant to gate field (compensating charge)
 
 ## Exact Exchange
 
-These variables are relevant when using hybrid functionals
+These variables are relevant when using hybrid functionals.
+
+**Availablity**: *[dft_functional](#dft_functional)==hse/hf/pbe0/scan0/opt_orb* or *[rpa](#rpa)==True*, and *[basis_type](#basis_type)==lcao/lcao_in_pw*
 
 ### exx_hybrid_alpha
 
 - **Type**: Real
 - **Description**: fraction of Fock exchange in hybrid functionals, so that $E_{X}=\alpha E_{X}+(1-\alpha)E_{X,\text{LDA/GGA}}$
-- **Default**: 1 if dft_functional==hf else 0.25
+- **Default**: 
+  - 1: if *[dft_functional](#dft_functional)==hf*
+  - 0.25: else
 
 ### exx_hse_omega
 
 - **Type**: Real
-- **Description**: range-separation parameter in HSE functional, such that $1/r=\text{erfc}(\omega r)/r+\text{erf}(\omega r)/r$.
+- **Description**: range-separation parameter in HSE functional, such that $1/r=\text{erfc}(\omega r)/r+\text{erf}(\omega r)/r$
 - **Default**: 0.11
 
 ### exx_separate_loop
 
 - **Type**: Boolean
-- **Description**: There are two types of iterative approaches provided by ABACUS to evaluate Fock exchange. If this parameter is set to 0, it will start with a GGA-Loop, and then Hybrid-Loop, in which EXX Hamiltonian $H_{exx}$ is updated with electronic iterations. If this parameter is set to 1, a two-step method is employed, i.e. in the inner iterations, density matrix is updated, while in the outer iterations, $H_{exx}$ is calculated based on density matrix that converges in the inner iteration. 
-- **Default**: 1
+- **Description**: There are two types of iterative approaches provided by ABACUS to evaluate Fock exchange. 
+  - False: Start with a GGA-Loop, and then Hybrid-Loop, in which EXX Hamiltonian $H_{exx}$ is updated with electronic iterations.
+  - True: A two-step method is employed, i.e. in the inner iterations, density matrix is updated, while in the outer iterations, $H_{exx}$ is calculated based on density matrix that converges in the inner iteration. 
+- **Default**: True
 
 ### exx_hybrid_step
 
 - **Type**: Integer
-- **Description**: This variable indicates the maximal electronic iteration number in the evaluation of Fock exchange.
+- **Availability**: *[exx_seperate_loop](#exx_separate_loop)==1*
+- **Description**: the maximal iteration number of the outer-loop, where the Fock exchange is calculated
 - **Default**: 100
 
 ### exx_mixing_beta
 
 - **Type**: Real
-- **Description**: mixing_beta for outer-loop when exx_separate_loop=1
+- **Availability**: *[exx_seperate_loop](#exx_separate_loop)==1*
+- **Description**: mixing_beta for densty matrix in each iteration of the outer-loop
 - **Default**: 1.0
 
 ### exx_lambda
 
 - **Type**: Real
+- **Availability**: *[basis_type](#basis_type)==lcao_in_pw*
 - **Description**: It is used to compensate for divergence points at G=0 in the evaluation of Fock exchange using *lcao_in_pw* method.
 - **Default**: 0.3
 
@@ -1931,37 +1946,50 @@ These variables are relevant when using hybrid functionals
 
 - **Type**: Real
 - **Description**: This parameter determines how many times larger the radial mesh required for calculating Columb potential is to that of atomic orbitals. For HSE, setting it to 1 is enough. But for PBE0, a much larger number must be used.
-- **Default**: 1.5 if dft_functional==hse else 5
+- **Default**: 
+  - 1.5: if *[dft_functional](#dft_functional)==hse*
+  - 5: else
 
 ### exx_distribute_type
 
 - **Type**: String
-- **Description**: When running in parallel, the evaluation of Fock exchange is done by distributing atom pairs on different threads, then gather the results. exx_distribute_type governs the mechanism of distribution. Available options are `htime`, `order`, `kmean1` and `kmeans2`. `order` is where atom pairs are simply distributed by their orders. `hmeans` is a distribution where the balance in time is achieved on each processor, hence if the memory is sufficient, this is the recommended method. `kmeans1` and `kmeans2` are two methods where the k-means clustering method is used to reduce memory requirement. They might be necessary for very large systems. (Currently not used)
+- **Description**: When running in parallel, the evaluation of Fock exchange is done by distributing atom pairs on different threads, then gather the results. exx_distribute_type governs the mechanism of distribution. Available options are `htime`, `order`, `kmean1` and `kmeans2`. 
+  - `order`: Atom pairs are simply distributed by their orders. 
+  - `hmeans`: The balance in time is achieved on each processor, hence if the memory is sufficient, this is the recommended method. 
+  - `kmeans1` ,   `kmeans2`: Two methods where the k-means clustering method is used to reduce memory requirement. They might be necessary for very large systems. (Currently not used)
 - **Default**: `htime`
 
 ### exx_opt_orb_lmax
 
 - **Type**: Integer
-- **Description**: See also the entry [dft_functional](#dft_functional). This parameter is only relevant when dft_functional=`opt_orb`. The radial part of opt-ABFs are generated as linear combinations of spherical Bessel functions. exx_opt_orb_lmax gives the maximum l of the spherical Bessel functions. A reasonable choice is 2.
+- **Availability**: *[dft_functional](#dft_functional)==opt_orb*
+- **Description**: The maximum l of the spherical Bessel functions, when the radial part of opt-ABFs are generated as linear combinations of spherical Bessel functions. A reasonable choice is 2.
 - **Default**: 0
 
 ### exx_opt_orb_ecut
 
 - **Type**: Real
-- **Description**: See also the entry [dft_functional](#dft_functional). This parameter is only relevant when dft_functional=`opt_orb`. A plane wave basis is used to optimize the radial ABFs. This parameter thus gives the cut-off of plane wave expansion, in Ry. A reasonable choice is 60.
+- **Availability**: *[dft_functional](#dft_functional)==opt_orb*
+- **Description**: The cut-off of plane wave expansion, when the plane wave basis is used to optimize the radial ABFs. A reasonable choice is 60.
 - **Default**: 0
+- **Unit**: Ry
 
 ### exx_opt_orb_tolerence
 
 - **Type**: Real
-- **Description**: See also the entry [dft_functional](#dft_functional). This parameter is only relevant when dft_functional=`opt_orb`. exx_opt_orb_tolerence determines the threshold when solving for the zeros of spherical Bessel functions. A reasonable choice is 1e-12.
+- **Availability**: *[dft_functional](#dft_functional)==opt_orb*
+- **Description**: The threshold when solving for the zeros of spherical Bessel functions. A reasonable choice is 1e-12.
 - **Default**: 0
 
 ### exx_real_number
 
 - **Type**: Boolean
-- **Description**: If set to 1, it will enforce LIBRI to use `double` data type, otherwise, it will enforce LIBRI to use `complex` data type. The default value depends on the [gamma_only](#gamma_only) option.
-- **Default**: 1 if gamma_only else 0
+- **Description**: 
+  - True: Enforce LIBRI to use `double` data type.
+  - False: Enforce LIBRI to use `complex` data type.
+- **Default**: depends on the [gamma_only](#gamma_only) option
+  - True: if gamma_only 
+  - False: else 
 
 [back to top](#full-list-of-input-keywords)
 

source/module_io/input.cpp

@@ -196,7 +196,7 @@ void Input::Default(void)
     ks_solver = "default"; // xiaohui add 2013-09-01
     search_radius = -1.0; // unit: a.u. -1.0 has no meaning.
     search_pbc = true;
-    symmetry = 0;
+    symmetry = "default";
     init_vel = false;
     ref_cell_factor = 1.0;
     symmetry_prec = 1.0e-5; // LiuXh add 2021-08-12, accuracy for symmetry
@@ -2489,6 +2489,13 @@ void Input::Default_2(void) // jiyy add 2019-08-04
         else if (dft_functional == "hse")
             exx_ccp_rmesh_times = "1.5";
     }
+    if (symmetry == "default")
+    {   //deal with no-forced default value
+        if (gamma_only || calculation == "nscf" || calculation == "get_S" || calculation == "istate" || calculation == "ienvelope")
+            symmetry = "0";     //if md or exx, symmetry will be force-set to 0 or -1 later
+        else
+            symmetry = "1";
+    }
     if (diago_proc <= 0)
     {
         diago_proc = GlobalV::NPROC;
@@ -2591,7 +2598,7 @@ void Input::Default_2(void) // jiyy add 2019-08-04
     else if (calculation == "md") // mohan add 2011-11-04
     {
         GlobalV::CALCULATION = "md";
-        symmetry = 0;
+        symmetry = "0";
         cal_force = 1;
         if (mdp.md_nstep == 0)
         {
@@ -2812,7 +2819,7 @@ void Input::Bcast()
     Parallel_Common::bcast_double(search_radius);
     Parallel_Common::bcast_bool(search_pbc);
     Parallel_Common::bcast_double(search_radius);
-    Parallel_Common::bcast_int(symmetry);
+    Parallel_Common::bcast_string(symmetry);
     Parallel_Common::bcast_bool(init_vel); // liuyu 2021-07-14
     Parallel_Common::bcast_double(ref_cell_factor);
     Parallel_Common::bcast_double(symmetry_prec); // LiuXh add 2021-08-12, accuracy for symmetry
@@ -3249,7 +3256,7 @@ void Input::Check(void)
     //----------------------------------------------------------
     if (calculation == "nscf" || calculation == "get_S")
     {
-        if (out_dos == 3 && symmetry)
+        if (out_dos == 3 && symmetry == "1")
         {
             ModuleBase::WARNING_QUIT("Input::Check",
                                      "symmetry can't be used for out_dos==3(Fermi Surface Plotting) by now.");

source/module_io/input.h

@@ -53,7 +53,7 @@ class Input
       -1, no symmetry at all; 
       0, only basic time reversal would be considered; 
       1, point group symmetry would be considered*/
-    int symmetry; 
+    string symmetry; 
     double symmetry_prec; // LiuXh add 2021-08-12, accuracy for symmetry
     int kpar; // ecch pool is for one k point
 

source/module_io/input_conv.cpp

@@ -311,7 +311,7 @@ void Input_Conv::Convert(void)
     GlobalV::OUT_LEVEL = INPUT.out_level;
     Ions_Move_CG::RELAX_CG_THR = INPUT.relax_cg_thr; // pengfei add 2013-09-09
 
-    ModuleSymmetry::Symmetry::symm_flag = INPUT.symmetry; // 9
+    ModuleSymmetry::Symmetry::symm_flag = std::stoi(INPUT.symmetry);
     GlobalC::symm.epsilon = INPUT.symmetry_prec; // LiuXh add 2021-08-12, accuracy for symmetry
     GlobalV::BASIS_TYPE = INPUT.basis_type;
     GlobalV::KS_SOLVER = INPUT.ks_solver;

source/module_io/test/input_test.cpp

@@ -79,7 +79,7 @@ TEST_F(InputTest, Default)
         EXPECT_EQ(INPUT.ks_solver,"default");
         EXPECT_DOUBLE_EQ(INPUT.search_radius,-1.0);
         EXPECT_TRUE(INPUT.search_pbc);
-        EXPECT_EQ(INPUT.symmetry,0);
+        EXPECT_EQ(INPUT.symmetry,"default");
         EXPECT_FALSE(INPUT.init_vel);
         EXPECT_DOUBLE_EQ(INPUT.ref_cell_factor,1.0);
         EXPECT_DOUBLE_EQ(INPUT.symmetry_prec,1.0e-5);
@@ -415,7 +415,7 @@ TEST_F(InputTest, Read)
         EXPECT_EQ(INPUT.ks_solver,"genelpa");
         EXPECT_DOUBLE_EQ(INPUT.search_radius,-1.0);
         EXPECT_TRUE(INPUT.search_pbc);
-        EXPECT_EQ(INPUT.symmetry,1);
+        EXPECT_EQ(INPUT.symmetry,"1");
         EXPECT_FALSE(INPUT.init_vel);
         EXPECT_DOUBLE_EQ(INPUT.symmetry_prec,1.0e-5);
         EXPECT_EQ(INPUT.cal_force, 0);
@@ -833,12 +833,14 @@ TEST_F(InputTest, Default_2)
 	//==================================================
 	// prepare default parameters for the 4th calling
 	INPUT.calculation = "istate";
+    INPUT.symmetry = "default";
 	// the 4th calling
 	INPUT.Default_2();
 	// ^^^^^^^^^^^^^^
 	EXPECT_EQ(GlobalV::CALCULATION,"istate");
-	EXPECT_EQ(INPUT.relax_nmax,1);
-	EXPECT_EQ(INPUT.out_stru,0);
+    EXPECT_EQ(INPUT.relax_nmax, 1);
+    EXPECT_EQ(INPUT.out_stru, 0);
+    EXPECT_EQ(INPUT.symmetry, "0");
 	EXPECT_EQ(INPUT.out_band,0);
 	EXPECT_EQ(INPUT.out_proj_band,0);
 	EXPECT_EQ(INPUT.cal_force,0);
@@ -852,12 +854,14 @@ TEST_F(InputTest, Default_2)
 	//==================================================
 	// prepare default parameters for the 5th calling
 	INPUT.calculation = "ienvelope";
+    INPUT.symmetry = "default";
 	// the 5th calling
 	INPUT.Default_2();
 	// ^^^^^^^^^^^^^^
 	EXPECT_EQ(GlobalV::CALCULATION,"ienvelope");
-	EXPECT_EQ(INPUT.relax_nmax,1);
-	EXPECT_EQ(INPUT.out_stru,0);
+    EXPECT_EQ(INPUT.relax_nmax, 1);
+    EXPECT_EQ(INPUT.symmetry, "0");
+    EXPECT_EQ(INPUT.out_stru, 0);
 	EXPECT_EQ(INPUT.out_band,0);
 	EXPECT_EQ(INPUT.out_proj_band,0);
 	EXPECT_EQ(INPUT.cal_force,0);
@@ -884,7 +888,7 @@ TEST_F(InputTest, Default_2)
 	INPUT.Default_2();
 	// ^^^^^^^^^^^^^^
 	EXPECT_EQ(GlobalV::CALCULATION,"md");
-	EXPECT_EQ(INPUT.symmetry,0);
+	EXPECT_EQ(INPUT.symmetry,"0");
 	EXPECT_EQ(INPUT.cal_force,1);
 	EXPECT_EQ(INPUT.mdp.md_nstep,50);
 	EXPECT_EQ(INPUT.out_level,"m");
@@ -994,12 +998,12 @@ TEST_F(InputTest, Check)
 	//
 	INPUT.calculation = "nscf";
 	INPUT.out_dos = 3;
-	INPUT.symmetry = 1;
+	INPUT.symmetry = "1";
 	testing::internal::CaptureStdout();
 	EXPECT_EXIT(INPUT.Check(),::testing::ExitedWithCode(0), "");
 	output = testing::internal::GetCapturedStdout();
 	EXPECT_THAT(output,testing::HasSubstr("symmetry can't be used for out_dos==3(Fermi Surface Plotting) by now."));
-	INPUT.symmetry = 0;
+	INPUT.symmetry = "0";
 	INPUT.out_dos = 0;
 	//
 	INPUT.calculation = "istate";

source/module_io/test/input_test_para.cpp

@@ -86,7 +86,7 @@ TEST_F(InputParaTest,Bcast)
         EXPECT_EQ(INPUT.ks_solver,"default");
         EXPECT_DOUBLE_EQ(INPUT.search_radius,-1.0);
         EXPECT_TRUE(INPUT.search_pbc);
-        EXPECT_EQ(INPUT.symmetry,0);
+        EXPECT_EQ(INPUT.symmetry,"default");
         EXPECT_FALSE(INPUT.init_vel);
         EXPECT_DOUBLE_EQ(INPUT.symmetry_prec,1.0e-5);
         EXPECT_EQ(INPUT.cal_force, 0);

tests/integrate/109_PW_CR_fix_a/INPUT

@@ -5,6 +5,7 @@ pseudo_dir	../../PP_ORB
 
 nbands			    8
 calculation         cell-relax
+symmetry        0
 
 #Parameters (Accuracy)
 ecutwfc			    20

tests/integrate/109_PW_CR_fix_ab/INPUT

@@ -5,6 +5,7 @@ pseudo_dir	../../PP_ORB
 
 nbands			    8
 calculation         cell-relax
+symmetry        0
 
 #Parameters (Accuracy)
 ecutwfc			    20

tests/integrate/109_PW_CR_fix_ac/INPUT

@@ -5,6 +5,7 @@ pseudo_dir	../../PP_ORB
 
 nbands			    8
 calculation         cell-relax
+symmetry        0
 
 #Parameters (Accuracy)
 ecutwfc			    20

tests/integrate/109_PW_CR_fix_b/INPUT

@@ -5,6 +5,7 @@ pseudo_dir	../../PP_ORB
 
 nbands			    8
 calculation         cell-relax
+symmetry        0
 
 #Parameters (Accuracy)
 ecutwfc			    20

tests/integrate/109_PW_CR_fix_bc/INPUT

@@ -5,6 +5,7 @@ pseudo_dir	../../PP_ORB
 
 nbands			    8
 calculation         cell-relax
+symmetry        0
 
 #Parameters (Accuracy)
 ecutwfc			    20

tests/integrate/109_PW_CR_fix_c/INPUT

@@ -5,6 +5,7 @@ pseudo_dir	../../PP_ORB
 
 nbands			    8
 calculation         cell-relax
+symmetry        0
 
 #Parameters (Accuracy)
 ecutwfc			    20

tests/integrate/212_NO_wfc_ienvelope/INPUT

@@ -1,6 +1,7 @@
 INPUT_PARAMETERS
 #Parameters	(System)
 suffix                  autotest
+symmetry        0
 
 nbands			4
 stru_file		STRU

tests/integrate/212_NO_wfc_out/INPUT

@@ -1,6 +1,7 @@
 INPUT_PARAMETERS
 #Parameters	(System)
 suffix                  autotest
+symmetry        0
 
 nbands			4
 stru_file		STRU