added documentation for SCF complex environment part (#1301)

* modified doc advanced.md

* added documentation for SCF complex environment part

Co-authored-by: hongriTianqi <hongriTianqi@users.noreply.github.com>
Co-authored-by: Wenfei Li <38569667+wenfei-li@users.noreply.github.com>

docs/advanced/scf/advanced.md

@@ -2,12 +2,89 @@
 
 ## Implicit Solvation Model
 
-## External Electric Field
+Solid-liquid interfaces are ubiquitous in nature and frequently encountered and employed in materials simulation. The solvation effect should be taken into account in first-principles calculations of such systems so as to obtain accurate predictions.  
 
-##  Compensating Charge
+Implicit solvation model is a well-developed method to deal with solvation effects, which has been widely used in finite and periodic systems. This approach treats the solvent as a continuous medium instead of individual “explicit” solvent molecules, which means that the solute embedded in an implicit solvent, and the average over the solvent degrees of freedom becomes implicit in the properties of the solvent bath. Compared to the “explicit” method, such implicit solvation model can provide qualitatively correct results with much less computational cost, which is particularly suited for large and complex systems. The implicit solvation model implemented in ABACUS follows the [methodology](https://aip.scitation.org/doi/10.1063/1.4865107) developed by Mathew, Sundararaman, Letchworth-Weaver, Arias, and Hennig in 2014. 
 
-## Van-der-Waals Correction
+Input parameters that control the implicit solvation model are listed as follows with detailed explaination and recommended values provided on this [webpage](https://github.com/deepmodeling/abacus-develop/blob/develop/docs/input-main.md#implicit-solvation-model):
+
+```
+INPUT_PARAMETERS
+imp_sol                 1
+eb_k                    80
+tau                     0.000010798
+sigma_k                 0.6
+nc_k                    0.00037
+```
+
+Example of running DFT calculation with the implicit solvation model is provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/implicit_solvation_model/Pt-slab).
+
+## External Electric Field 
+
+A saw-like potential simulating an electric field
+can be added to the bare ionic potential, which is a simplified simulation to the field-effect measurements, in which the system is separated from the gate electrode by a dielectric such as silicon oxide.
+
+Whether to apply the external field is controlled via the keyword `efield_flag` in `INPUT` (setting to 1 to turn on the field). Related keywords that control the external field are listed as follows with detailed explaination provided [here](https://github.com/deepmodeling/abacus-develop/blob/develop/docs/input-main.md#electric-field-and-dipole-correction):
+```
+INPUT_PARAMETERS
+efield_flag        1
+efield_dir         2
+efield_pos_max     0.5
+efield_pos_dec     0.1
+efield_amp         0.001
+```
+
+Example of running DFT calculation with added external electric field is provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/electric_field/Pt-slab). 
+
+
+## Dipole correction
+A dipole correction can be added to the bare ionic potential, which can compensate for the artificial dipole field within the context of a periodic supercell calculation. The dipole correction implemented in ABACUS follows the [methodology](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.59.12301) proposed by Bengtsson in 1999. This correction must be used ONLY in a slab geometry, for surface calculations, with the discontinuity FALLING IN THE EMPTY SPACE. Note that the common input parameters shared between the external electric field and dipole correction, with detailed explaination provided [here](https://github.com/deepmodeling/abacus-develop/blob/develop/docs/input-main.md#electric-field-and-dipole-correction). The following keywords settings add dipole correction only without applying any external electric field:
+```
+INPUT_PARAMETERS
+efield_flag        1
+dip_cor_flag       1
+efield_dir         2
+efield_pos_max     0.5
+efield_pos_dec     0.1
+efield_amp         0
+```
+
+While The external electric field and dipole correction can also be added together to the bare ionic potential as follows: 
+```
+INPUT_PARAMETERS
+efield_flag        1
+dip_cor_flag       1
+efield_dir         2
+efield_pos_max     0.5
+efield_pos_dec     0.1
+efield_amp         0.001
+```
 
+Examples of running DFT calculations with dipole correction are provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/dipole_correction/Pt-slab). There are two input files, where `INPUT1` considers only the dipole correction without no applied external field, while `INPUT2` considers the dipole correction under an applied external field.
+
+To run any of the two cases, users may enter the directory, copy the corresponding input file to `INPUT`, and run ABACUS.
+
+
+## Compensating Charge
+
+Modeling a constant-potential electronchemcial surface reaction requires adjustment of electron numbers in a simulation cell. At the mean time, we need to maintain the supercell's neutrality due to the periodic boundary condition. A distribution of compensating charge thus needs to be implemented in the vacuum region of surface models when extra electrons are added/extracted from the system.
+
+The compensating charge implemented in ABACUS follows the [methodology](http://dx.doi.org/10.1103/PhysRevB.89.245406) developed by Brumme, Calandra, and Mauri in 2014. Input parameters that control the compensating charge are listed as follows with detailed explaination provided [here](https://github.com/deepmodeling/abacus-develop/blob/develop/docs/input-main.md#gate-field-compensating-charge): 
+
+```
+INPUT_PARAMETERS
+gate_field         1
+efield_dir         2
+zgate              0.5
+block              1
+block_down         0.45
+block_up           0.55
+block_height       0.1
+```
+
+Example of running DFT calculation with the compensating charge is provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/compensating_charge/Pt-slab). 
+
+## Van-der-Waals Correction
 Conventional DFT functionals often suffer from an inadequate treatment of long-range dispersion, or Van der Waals (VdW) interactions. In order to describe materials where VdW interactions are prominent, one simple and popular approach is to add a Lennard-Jones type term. The resulting VdW-corrected DFT has been proved to be a very effective method for description of both short-range chemical bonding and long-range dispersive interactions.
 
 Currently ABACUS provides three Grimme DFT-D methods, including [D2](https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.20495), [D3(0)](https://aip.scitation.org/doi/10.1063/1.3382344) and [D3(BJ)](https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.21759), to describe Van der Waals interactions. Among them, the D3 method has been implemented in ABACUS based on the
@@ -26,4 +103,3 @@ Examples of VdW-corrected DFT calculations are provided in this [directory](http
 
 To run any of the two cases, users may enter the directory, copy the corresponding input file to `INPUT`, and run ABACUS.
 
-## Dipole Correction

docs/input-main.md

@@ -1040,66 +1040,65 @@ is added to the bare ionic potential.
 #### dip_cor_flag
 
 - **Type**: Boolean
-- **Description**: If dip_cor_flag == true and efield_flag == true,  a dipole correction is also
-added to the bare ionic potential. If you want no electric field, parameter efield_amp  should be zero. Must be used ONLY in a slab geometry for surface calculations, with the discontinuity FALLING IN THE EMPTY SPACE.
+- **Description**: Set to true for dipole correction. For calculations with no applied external field, `efield_amp` should set to 0. Must be used ONLY in a slab geometry for surface calculations, with the discontinuity FALLING IN THE EMPTY SPACE. Used only if `efield_flag` == true.
 - **Default**: false
 
 #### efield_dir
 
 - **Type**: Integer
-- **Description**: The direction of the electric field or dipole correction is parallel to the reciprocal lattice vector, so the potential is constant in planes defined by FFT grid points, efield_dir = 0, 1 or 2. Used only if efield_flag == true.
+- **Description**: The direction of the electric field or dipole correction, which is parallel to the reciprocal lattice vector. `efield_dir` = 0, 1, and 2 correspond to the *x*, *y*, and *z* direction, respectively. Used only if `efield_flag` == true.
 - **Default**: 2
 
 #### efield_pos_max
 
 - **Type**: Real
-- **Description**: Position of the maximum of the saw-like potential along crystal axis efield_dir, within the  unit cell, 0 < efield_pos_max < 1. Used only if efield_flag == true.
+- **Description**: Position of the maximum of the saw-like potential along crystal axis efield_dir, within the  unit cell, which should satisfy 0 < `efield_pos_max` < 1. Used only if `efield_flag` == true. This is a fractional position in the unit of the crystal vector along the direction specified via `efield_dir`.
 - **Default**: 0.5
 
 #### efield_pos_dec
 
 - **Type**: Real
-- **Description**: Zone in the unit cell where the saw-like potential decreases, 0 < efield_pos_dec < 1. Used only if efield_flag == true.
+- **Description**: Zone in the unit cell where the saw-like potential decreases, which should satisfy 0 < `efield_pos_dec` < 1. Used only if `efield_flag` == true. This is a fractional position in the unit of the crystal vector along the direction specified via `efield_dir`.
 - **Default**: 0.1
 
 #### efield_amp
 
 - **Type**: Real
-- **Description**: Amplitude of the electric field, in ***Hartree*** a.u.; 1 a.u. = 51.4220632*10^10 V/m. Used only if efield_flag == true. The saw-like potential increases with slope efield_amp  in the region from (efield_pos_max+efield_pos_dec-1) to (efield_pos_max), then decreases until (efield_pos_max+efield_pos_dec), in units of the crystal vector efield_dir. Important: the change of slope of this potential must be located in the empty region, or else unphysical forces will result.
+- **Description**: Amplitude of the electric field. Used only if `efield_flag` == true. The saw-like potential increases with slope `efield_amp`  in the region from (`efield_pos_max` + `efield_pos_dec`-1) to (`efield_pos_max`), then decreases until (`efield_pos_max` + `efield_pos_dec`). Important: the change of slope of this potential must be located in the empty region, or else unphysical forces will result.
 - **Default**: 0.0
 
 ### Gate field (compensating charge)
 
-This part of variables are relevant to gate field (compensating charge)
+This part of variables control the gate field (compensating charge).
 
 #### gate_flag
 
 - **Type**: Boolean
-- **Description**: In the case of charged cells, setting gate_flag == true represents the addition of compensating charge by a charged plate, which is placed at **zgate**. Note that the direction is specified by **efield_dir**.
+- **Description**: In the case of charged cells, setting `gate_flag` to true enables the addition of compensating charge by a charged plate, which is placed at `zgate`. **Note that the direction is specified by `efield_dir`**.
 - **Default**: false
 
 #### zgate
 
 - **Type**: Real
-- **Description**: Specify the position of the charged plate in units of the unit cell (0 <= **zgate** < 1).
+- **Description**: The position of the charged plate in units of the unit cell, which should satisfy 0 <= `zgate` < 1.
 - **Default**: 0.5
 
 #### block
 
 - **Type**: Boolean
-- **Description**: Add a potential barrier to the total potential to avoid electrons spilling into the vacuum region for electron doping. Potential barrier is from **block_down** to **block_up** and has a height of **block_height**. If **dip_cor_flag** == true, **efield_pos_dec** is used for a smooth increase and decrease of the potential barrier.
+- **Description**: If set to true, a potential barrier will be added to the total potential to avoid electrons spilling into the vacuum region for electron doping. Potential barrier forms from `block_down` to `block_up` and has a height of `block_height`. If `dip_cor_flag` == true, `efield_pos_dec` is used for a smooth increase and decrease of the potential barrier.
 - **Default**: false
 
 #### block_down
 
 - **Type**: Real
-- **Description**: Lower beginning of the potential barrier in units of the unit cell size (0 <= **block_down** < **block_up** < 1).
+- **Description**: Lower limit of the potential barrier in units of the unit cell size, which should satisfy 0 <= `block_down` < `block_up` < 1.
 - **Default**: 0.45
 
 #### block_up
 
 - **Type**: Real
-- **Description**: Upper beginning of the potential barrier in units of the unit cell size (0 <= **block_down** < **block_up** < 1).
+- **Description**: Upper limit of the potential barrier in units of the unit cell size, which should satisfy 0 <= `block_down` < `block_up` < 1).
 - **Default**: 0.55
 
 #### block_height
@@ -1732,25 +1731,24 @@ This part of variables are used to control the usage of implicit solvation model
 #### eb_k
 
 - **Type**: Real
-- **Description**: The relative permittivity of the bulk solvent, 80 for water. Used only if `imp_sol` == true.
+- **Description**: The relative permittivity of the bulk solvent, e.g., 80 for water. Used only if `imp_sol` == true. Set it to be the relative permittivity of any desired solvent. 
 - **Default**: 80
 
 #### tau
 
 - **Type**: Real
-- **Description**: The effective surface tension parameter, which describes the cavitation, the dispersion, and the repulsion interaction between the solute and the solvent that are not captured by the electrostatic terms. The unit is $Ry/Bohr^{2}$.
+- **Description**: The effective surface tension parameter, which describes the cavitation, the dispersion, and the repulsion interaction between the solute and the solvent that are not captured by the electrostatic terms. The unit is $Ry/Bohr^{2}$. Used only if `imp_sol` == true. Default value is recommended. 
 - **Default**: 1.0798e-05
 
 #### sigma_k
 
 - **Type**: Real
-- **Description**: We assume a diffuse cavity that is implicitly determined by the electronic structure of the solute.
-`sigma_k` is the parameter that describes the width of the diffuse cavity.
+- **Description**: The width of the diffuse cavity. Used only if `imp_sol` == true. Default value is recommended. 
 - **Default**: 0.6
 
 #### nc_k
 
 - **Type**: Real
-- **Description**: It determines at what value of the electron density the dielectric cavity forms. 
-The unit is $Bohr^{-3}$.
+- **Description**: `nc_k` is the cut-off charge density, i.e., the value of the electron
+density at which the dielectric cavity forms. The unit is $Bohr^{-3}$. Used only if `imp_sol` == true. Default value is recommended. 
 - **Default**: 0.00037

examples/compensating_charge/Pt-slab/INPUT

@@ -0,0 +1,25 @@
+INPUT_PARAMETERS
+pseudo_dir	  ./
+ntype		  1
+dft_functional    pbe
+symmetry	  0
+cal_force	  1
+calculation       scf
+ecutwfc		  60
+scf_nmax	  200
+scf_thr		  1.0e-7
+basis_type	  pw
+gamma_only        1
+smearing_method	  gauss
+smearing_sigma	  0.02
+mixing_type       pulay
+mixing_beta       0.4
+
+#Parameters (compensating charge)
+gate_flag           1
+zgate               0.7
+block_down          0.65
+block_up            0.75
+block_height        0.01
+block               1
+nelec               487