Update docs related to inputs, scf_thr and ase-abacus (#5922)

* update brief intro for INPUT

* update bohr raduis in input.md

* scf_thr recommendation

* add dots

* add suffix meaning

* update ase.md

* update description of scf_thr_type

* update Unit in scf_thr

* update suggestions

* update "see documents for detail"

* update input.md

Author: QuantumMisaka

docs/advanced/input_files/input-main.md

@@ -20,8 +20,8 @@
     - [kspacing](#kspacing)
     - [min\_dist\_coef](#min_dist_coef)
     - [device](#device)
-    - [nb2d](#nb2d)
     - [precision](#precision)
+    - [nb2d](#nb2d)
   - [Variables related to input files](#variables-related-to-input-files)
     - [stru\_file](#stru_file)
     - [kpoint\_file](#kpoint_file)
@@ -224,6 +224,8 @@
     - [of\_ml\_q](#of_ml_q)
     - [of\_ml\_tanhp](#of_ml_tanhp)
     - [of\_ml\_tanhq](#of_ml_tanhq)
+    - [of\_ml\_chi\_p](#of_ml_chi_p)
+    - [of\_ml\_chi\_q](#of_ml_chi_q)
     - [of\_ml\_gammanl](#of_ml_gammanl)
     - [of\_ml\_pnl](#of_ml_pnl)
     - [of\_ml\_qnl](#of_ml_qnl)
@@ -234,8 +236,6 @@
     - [of\_ml\_tanh\_qnl](#of_ml_tanh_qnl)
     - [of\_ml\_tanhp\_nl](#of_ml_tanhp_nl)
     - [of\_ml\_tanhq\_nl](#of_ml_tanhq_nl)
-    - [of\_ml\_chi\_p](#of_ml_chi_p)
-    - [of\_ml\_chi\_q](#of_ml_chi_q)
     - [of\_ml\_chi\_xi](#of_ml_chi_xi)
     - [of\_ml\_chi\_pnl](#of_ml_chi_pnl)
     - [of\_ml\_chi\_qnl](#of_ml_chi_qnl)
@@ -1236,6 +1236,7 @@ Note: In new angle mixing, you should set `mixing_beta_mag >> mixing_beta`. The
 - **Type**: Real
 - **Description**: It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. Usually for local orbitals, usually 1e-6 may be accurate enough.
 - **Default**: 1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis).
+- **Unit**: Ry if `scf_thr_type=1`, **dimensionless** if `scf_thr_type=2`
 
 ### scf_ene_thr
 
@@ -1248,10 +1249,8 @@ Note: In new angle mixing, you should set `mixing_beta_mag >> mixing_beta`. The
 
 - **Type**: Integer
 - **Description**: Choose the calculation method of convergence criterion.
-  - **1**: the criterion is defined as $\Delta\rho_G = \frac{1}{2}\iint{\frac{\Delta\rho(r)\Delta\rho(r')}{|r-r'|}d^3r d^3r'}$.
-  - **2**: the criterion is defined as $\Delta\rho_R = \frac{1}{N_e}\int{|\Delta\rho(r)|d^3r}$, where $N_e$ is the number of electron.
-
-  Note: This parameter is still under testing and the default setting is usually sufficient.
+  - **1**: the criterion is defined as $\Delta\rho_G = \frac{1}{2}\iint{\frac{\Delta\rho(r)\Delta\rho(r')}{|r-r'|}d^3r d^3r'}$, which is used in SCF of PW basis with unit Ry. 
+  - **2**: the criterion is defined as $\Delta\rho_R = \frac{1}{N_e}\int{|\Delta\rho(r)|d^3r}$, where $N_e$ is the number of electron, which is used in SCF of LCAO with unit **dimensionless**.
 
 - **Default**: 1 (plane-wave basis), or 2 (localized atomic orbital basis).
 

docs/advanced/interface/ase.md

@@ -9,7 +9,12 @@
 ```bash
 git clone https://gitlab.com/1041176461/ase-abacus.git
 cd ase-abacus
-python3 setup.py install
+pip install .
+```
+
+Another direct way:
+```bash
+pip install git+https://gitlab.com/1041176461/ase-abacus.git
 ```
 
 ## Environment variables
@@ -25,6 +30,8 @@ python3 setup.py install
 
 For PW calculations, only `ABACUS_PP_PATH` is needed. For LCAO calculations, both `ABACUS_PP_PATH` and `ABACUS_ORBITAL_PATH` should be set.
 
+Also, one can manally set the paths of PP and ORB when using ABACUS calculator in ASE.
+
 ## ABACUS Calculator
 
 The default initialization command for the ABACUS calculator is
@@ -49,22 +56,41 @@ For more information on pseudopotentials and numerical orbitals, please visit [A
 
 The input parameters can be set like::
 ```python
-  calc = Abacus(profile=profile, ntype=1, ecutwfc=50, scf_nmax=50, smearing_method='gaussian', smearing_sigma=0.01, basis_type='pw', ks_solver='cg', calculation='scf' pp=pp, basis=basis, kpts=kpts)
+  # for ABACUS calculator
+  calc = Abacus(profile=profile, 
+                ecutwfc=100, 
+                scf_nmax=100, 
+                smearing_method='gaussian', 
+                smearing_sigma=0.01, 
+                basis_type='pw', 
+                ks_solver='dav', 
+                calculation='scf', 
+                pp=pp, 
+                basis=basis, 
+                kpts=kpts)
 ```
 
 The command to run jobs can be set by specifying `AbacusProfile`::
 
 ```python
   from ase.calculators.abacus import AbacusProfile
-  abacus = '/usr/local/bin/abacus'
-  profile = AbacusProfile(argv=['mpirun','-n','2',abacus])
+  # for OpenMP setting inside python env
+  import os
+  os.environ("OMP_NUM_THREADS") = 1
+  # for MPI setting used in abacus
+  mpi_num = 4
+  # for ABACUS Profile
+  abacus = '/usr/local/bin/abacus' # specify abacus exec
+  profile = AbacusProfile(command=f'mpirun -n {mpi_num} {abacus}')  # directly the command for running ABACUS
 ```
 
 in which `abacus` sets the absolute path of the `abacus` executable.
 
 ## MD Analysis
 After molecular dynamics calculations, the log file `running_md.log` can be read. If the 'STRU_MD_*' files are not continuous (e.g. 'STRU_MD_0', 'STRU_MD_5', 'STRU_MD_10'...), the index parameter of read should be as a slice object. For example, when using the command `read('running_md.log', index=slice(0, 15, 5), format='abacus-out')` to parse 'running_md.log', 'STRU_MD_0', 'STRU_MD_5' and 'STRU_MD_10' will be read.
 
+The `MD_dump` file is also supported to be read-in by `read('MD_dump', format='abacus-md')`
+
 
 ## SPAP Analysis
 

docs/quick_start/input.md

@@ -10,15 +10,14 @@ Below is an example `INPUT` file with some of the most important parameters that
 
 ```plaintext
 INPUT_PARAMETERS
-suffix                  MgO
-ntype                   2
-pseudo_dir              ./
-orbital_dir             ./
+suffix                  MgO  # the output files will be in OUT.{suffix} directory 
+pseudo_dir              ./   # where the pseudopotential for each element is
+orbital_dir             ./   # where the orbital file for each element is
 ecutwfc                 100  # in Rydberg
-scf_thr                 1e-4 # Rydberg
-basis_type              lcao
+scf_thr                 1e-6 # dimensionless for LCAO, Rydberg for PW. See documents for details.
+basis_type              lcao # lcao or pw
 calculation             scf  # this is the key parameter telling abacus to do a scf calculation
-out_chg                 True
+out_chg                 0    # only output binary charge file for restart
 ```
 
 The parameter list always starts with key word `INPUT_PARAMETERS`. Any content before `INPUT_PARAMETERS` will be ignored.
@@ -36,19 +35,18 @@ Furthermore, if a given parameter name appeared more than once in the input file
 
 In the above example, the meanings of the parameters are:
 
-- `suffix` : the name of the system, default `ABACUS`
-- `ntype` : how many types of elements in the unit cell
-- `pseudo_dir` : the directory where pseudopotential files are provided
-- `orbital_dir` : the directory where orbital files are provided
-- `ecutwfc` : the plane-wave energy cutoff for the wave function expansion (UNIT: Rydberg)
-- `scf_thr` : the threshold for the convergence of charge density (UNIT: Rydberg)
-- `basis_type` : the type of basis set for expanding the electronic wave functions
+- `suffix` : the name of the system, default `ABACUS`, and output files will be in OUT.{suffix} directory. 
+- `pseudo_dir` : the directory where pseudopotential files are provided.
+- `orbital_dir` : the directory where orbital files are provided.
+- `ecutwfc` : the plane-wave energy cutoff for the wave function expansion (UNIT: Rydberg).
+- `scf_thr` : the threshold for the convergence of charge density (UNIT: Rydberg for PW, dimensionless for LCAO), we recommend `1e-7` for LCAO and `1e-9` for PW basis.
+- `basis_type` : the type of basis set for expanding the electronic wave functions, one can set lcao or pw.
 - `calculation` : the type of calculation to be performed by ABACUS
-- `out_chg` : if true, output the charge density on real space grid
+- `out_chg` : setting for output the charge density in real space grid, -1 for no output, 0 for binary output, 1 for binary and cube output.
 
 For a complete list of input parameters, please consult this [instruction](../advanced/input_files/input-main.md).
 
-> **Note:** Users cannot change the filename “INPUT” to other names. Boolean paramerters such as `out_chg` can be set by using `True` and `False`, `1` and `0`, or `T` and `F`. It is case insensitive so that other preferences such as `true` and `false`, `TRUE` and `FALSE`, and `t` and `f` for setting boolean values are also supported. Specifically for the `out_chg`, `-1` option is also available, which means turn off the checkpoint of charge density in binary (always dumped in `OUT.{suffix}`, whose name ends with `CHARGE-DENSITY.restart`). Some parameters controlling the output also support a second option to control the output precision, e.g., `out_chg True 8` will output the charge density on realspace grid with 8 digits after the decimal point.
+> **Note:** Users cannot change the filename “INPUT” to other names. Boolean paramerters such as `out_chg` can be set by using `True` and `False`, `1` and `0`, or `T` and `F`. It is case insensitive so that other preferences such as `true` and `false`, `TRUE` and `FALSE`, and `t` and `f` for setting boolean values are also supported. Specifically for the `out_chg`, `-1` option is also available, which means turn off the checkpoint of charge density in binary (always dumped in `OUT.{suffix}`, whose name ends with `CHARGE-DENSITY.restart`). Some parameters controlling the output also support a second option to control the output precision, e.g., `out_chg 1 8` will output the charge density on realspace grid with 8 digits after the decimal point.
 
 ## *STRU*
 
@@ -69,7 +67,8 @@ Mg_gga_8au_100Ry_4s2p1d.orb
 O_gga_8au_100Ry_2s2p1d.orb
 
 LATTICE_CONSTANT
-1.8897259886 # 1.8897259886 Bohr =  1.0 Angstrom
+1.889726126 # 1.0 Ang = 1/a_0 = 1/0.529177210544
+# Bohr radius ref: https://physics.nist.gov/cgi-bin/cuu/Value?bohrrada0
 
 LATTICE_VECTORS
 4.25648 0.00000 0.00000