Merge pull request #206 from deepmodeling/develop

Merge: update 3.0.0 docs to abacusmodeling/abacus-develop.git

Author: dyzheng

docs/CONTRIBUTING.md

@@ -22,7 +22,7 @@ If you would like to implement a new feature, please submit an issue with a prop
 
 ## Structure of the package
 
-Please refer to [our instructions](./install.md) on how to installing ABACUS.
+Please refer to [our instructions](./quick_start/easy_install.md) on how to installing ABACUS.
 The source code of ABACUS is based on several modules. Under the ABACUS root directory, there are the following folders:
 
 - `cmake`: relevant files for finding required packages when compiling the code with cmake;

docs/advanced/input_files/input-main.md

@@ -4,8 +4,6 @@
 - [Set k-points explicitly](#set-k-points-explicitly)
 - [Band structure calculations](#band-structure-calculations)
 
-   [back to main page](../README.md)
-
 ABACUS uses periodic boundary conditions for both crystals and finite systems. For isolated systems, such as atoms, molecules, clusters, etc., one uses the so-called supercell model. Lattice vectors of the supercell are set in the `STRU` file. For the input k-point (`KPT`) file, the file should either contain the k-point coordinates and weights or the mesh size for creating the k-point gird. Both options are allowed in `ABACUS`.
 
 ## Gamma-only Calculations
@@ -39,7 +37,7 @@ The first three numbers of the last line are integers, which give the MP k grid
 the rest three are real numbers, which give the offset of the k grid. In this example, the numbers
 `0 0 0` means that there is no offset, and this is the a standard 2by2by2 k grid.
 
-[back to top](#kpt-file)
+[back to top](#the-kpt-file)
 
 ## Set k-points explicitly
 
@@ -60,7 +58,7 @@ Direct //`Direct' or `Cartesian' coordinate
 0.5 0.5 0.5 0.125
 ```
 
-[back to top](#kpt-file)
+[back to top](#the-kpt-file)
 
 ## Band structure calculations
 
@@ -84,4 +82,4 @@ Line // line-mode
 The fourth line and the following are special k-point coordinates and number of k-points
 between this special k-point and the next.
 
-[back to top](#kpt-file)
+[back to top](#the-kpt-file)

docs/advanced/input_files/kpt.md

@@ -5,8 +5,6 @@
   - [latname fcc](#latname-fcc)
 - [Structure of the file](#structure-of-the-file)
 
-    [back to main page](../README.md)
-
 ## Examples
 
 The `STRU` file contains the information about the lattice geometry, the name(s) and/or location(s) of the pseudopotential and numerical orbital files, as well as the structural information about the system.

docs/advanced/input_files/stru.md

@@ -41,7 +41,7 @@ In ABACUS, we implemented the CG method for doing fixed-cell structural relaxati
 Apart from conventional optimization where all degrees of freedom are allowed to move, we also offer the option of doing constrained optimization in ABACUS.
 
 ### Fixing Atomic Positions  
-Users may note that in the above-mentioned [example](), the atomic positions in STRU file are given along with three integers:
+Users may note that in the above-mentioned example, the atomic positions in STRU file are given along with three integers:
 
 ```
 Al
@@ -69,4 +69,4 @@ then the first Al atom will not be allowed to move in z direction.
 Fixing atomic position is sometimes helpful during relaxation of isolated molecule/cluster, to prevent the system from drifting in space.
 
 ### Fixing Cell Parameters
-Sometimes we want to do variable-cell relaxation with some of the cell degrees of freedom fixed. This is achieved by the [fixed_axes](./input_files/input-main.md#fixed_axes) keyword. We offer the options of fixing certain axis(axes), or fixing the volume.
+Sometimes we want to do variable-cell relaxation with some of the cell degrees of freedom fixed. This is achieved by the [fixed_axes](./input_files/input-main.md#fixed_axes) keyword. We offer the options of fixing certain axis(axes), or fixing the volume.

docs/advanced/opt.md

@@ -45,7 +45,7 @@ Here, we use a simple [example calculation](https://github.com/deepmodeling/abac
     dft_functional SCAN
     ```
     
-    Note that in the case of PBE and SCAN, we are using 'short-hand' names to represent the entire functional, which is made up of individual exchange and correlation components. A complete list of 'short-hand' expressions supported by ABACUS can be found in [source code](../source/module_xc/xc_functional.cpp).
+    Note that in the case of PBE and SCAN, we are using 'short-hand' names to represent the entire functional, which is made up of individual exchange and correlation components. A complete list of 'short-hand' expressions supported by ABACUS can be found in [source code](../../../source/module_xc/xc_functional.cpp).
 
     Apart from the 'short-hand' names, ABACUS also allow supplying exchange-correlation functionals as combinations of LIBXC keywords for functional components, joined by plus sign, for example, setting:
 
@@ -84,6 +84,6 @@ Here, we use a simple [example calculation](https://github.com/deepmodeling/abac
 
 Conventional functionals, e.g., L(S)DA and GGAs, encounter failures in strongly correlated systems, usually characterized by partially filled *d*/*f* shells. These include transition metals (TM) and their oxides, rare-earth compounds, and actinides, to name a few, where L(S)DA/GGAs typically yield quantitatively or even qualitatively wrong results. To address this failure, an efficient and successful method named DFT+*U*, which inherits the efficiency of L(S)DA/GGA but gains the strength of the Hubbard model in describing the physics of strongly correlatedsystems, has been developed.
 
-Now the DFT+*U* method is accessible in ABACUS. The details of the DFT+*U* method could be found in this [paper](https://doi.org/10.1063/5.0090122). It should be noted that the DFT+*U* works only within the NAO scheme, which means that the value of the keyword `basis_type` must be lcao when DFT+*U* is called. To turn on DFT+*U*, users need to set the value of the `dft_plus_u` keyword in the `INPUT` file to be 1. All relevant parmeters used in DFT+*U* calculations are listed in the [DFT+*U* correction](../input_files/input-main.md#DFTU-correction) part of the [list of keywords](../input_files/input-main.md).
+Now the DFT+*U* method is accessible in ABACUS. The details of the DFT+*U* method could be found in this [paper](https://doi.org/10.1063/5.0090122). It should be noted that the DFT+*U* works only within the NAO scheme, which means that the value of the keyword `basis_type` must be lcao when DFT+*U* is called. To turn on DFT+*U*, users need to set the value of the `dft_plus_u` keyword in the `INPUT` file to be 1. All relevant parmeters used in DFT+*U* calculations are listed in the [DFT+*U* correction](../input_files/input-main.md#dftu-correction) part of the [list of keywords](../input_files/input-main.md).
 
-Examples of DFT+*U* calculations are provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/dft_plus_u).
+Examples of DFT+*U* calculations are provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/dft_plus_u).

docs/advanced/scf/construct_H.md

@@ -9,7 +9,7 @@ When "basis_type = pw", `ks_solver` can be `cg` or `dav`. The default setting `c
 When "basis_type = lcao", `ks_solver` can be `genelpa` or `scalapack_gvx`. The default setting `genelpa` is recommended, which is based on ELPA (EIGENVALUE SOLVERS FOR PETAFLOP APPLICATIONS) (https://elpa.mpcdf.mpg.de/) and the kernel is auto choosed by GENELPA(https://github.com/pplab/GenELPA), usually faster than the setting of "scalapack_gvx", which is based on ScaLAPACK(Scalable Linear Algebra PACKage)  
 
 ## Stochasic DFT
-We support stochastic DFT calculation (SDFT) or mixed stochastic-deterministic DFT (MDFT) with plane-wave basis [[Phys. Rev. B 106, 125132 (2022)](https://doi.org/10.1103/PhysRevB.106.125132)]. Different from traditional KSDFT with the explicit diagonalization method, SDFT and MDFT calculate physical quantities with trace of the corresponding operators. The advantages of SDFT and MDFT compared to the traditional KSDFT are the ability to simulate larger sizes and higher temperatures. In our package, SDFT and MDFT can be used by setting the `calculation` parameter to `sto-scf` or `sto-md` for SCF calculations or MD calculations. To start with, you can refer to an easy [example](../../examples/stochastic.md) and an explanation of the [input variables](../../input-main.md#electronic-structure-sdft).
+We support stochastic DFT calculation (SDFT) or mixed stochastic-deterministic DFT (MDFT) with plane-wave basis [[Phys. Rev. B 106, 125132 (2022)](https://doi.org/10.1103/PhysRevB.106.125132)]. Different from traditional KSDFT with the explicit diagonalization method, SDFT and MDFT calculate physical quantities with trace of the corresponding operators. The advantages of SDFT and MDFT compared to the traditional KSDFT are the ability to simulate larger sizes and higher temperatures. In our package, SDFT and MDFT can be used by setting the `calculation` parameter to `sto-scf` or `sto-md` for SCF calculations or MD calculations. To start with, you can refer to two [examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/stochastic) and an explanation of the [input variables](../input_files/input-main.md#electronic-structure-sdft).
 
 When we have a hamiltonian, the electronic density can be calculated with:
 
@@ -31,4 +31,4 @@ $\ket{\tilde\chi_i}=\ket{\chi_i}-\sum_{n=1}^{N_\phi}\braket{\phi_n|\chi_i}\ket{\
 
 Here the number of KS orbitals $N_\phi$ is controlled by the parameter `nbands` while the number of stochastic orbitals $N_\chi$ is controlled by `nbands_sto`.
 
-Besides, although SDFT does not diagonalize the hamiltonian, it can also caluclate DOS and electronic conductivities with parameters `out_dos` and `cal_cond` separately.
+Besides, although SDFT does not diagonalize the hamiltonian, it can also caluclate DOS and electronic conductivities with parameters `out_dos` and `cal_cond` separately.

docs/advanced/scf/hsolver.md

@@ -1,4 +1,4 @@
-# Spin-polarization
+# Spin-polarization and SOC
 
 ## Non-spin-polarized Calculations
 Setting of **"nspin 1"** in INPUT file means calculation with non-polarized spin. 
@@ -25,7 +25,7 @@ In this case, nspin is automatically set to 4, which is usually not required to
 The weight of each band will not change, but the number of occupied states will be double. 
 If the nbands parameter is set manually, it is generally set to twice what it would be when nspin<4.
 
-In general, non-collinear magnetic moment settings are often used in calculations considering [SOC effects](./soc.md). When **"lspinorb 1"** in INPUT file, "nspin" is also automatically set to 4. 
+In general, non-collinear magnetic moment settings are often used in calculations considering [SOC effects](#soc-effects). When **"lspinorb 1"** in INPUT file, "nspin" is also automatically set to 4. 
 Note: different settings for "noncolin" and "lspinorb" correspond to different calculations:
  - noncolin=0 lspinorb=0 nspin<4 : 
 Non-collinear magnetic moments and SOC effects are not considered.
@@ -42,3 +42,30 @@ The SOC effect and non-collinear magnetic moment are both calculated.
 - Continuation job for "nspin 1" need file "SPIN1_CHG" which is generated by setting "out_chg=1" in task before. By setting "init_chg file" in new job's INPUT file, charge density will start from file but not atomic. 
 - Continuation job for "nspin 2" need files "SPIN1_CHG" and "SPIN2_CHG" which are generated by "out_chg 1" with "nspin 2", and refer to spin-up and spin-down charge densities respectively. It should be note that reading "SPIN1_CHG" only for the continuation target magnetic moment job is not supported now.
 - Continuation job for "nspin 4" need files "SPIN%s_CHG", where %s in {1,2,3,4}, which are generated by "out_chg 1" with any variable setting leading to 'nspin'=4, and refer to charge densities in Pauli spin matrixes. It should be note that reading charge density files printing by 'nspin'=2 case is supported, which means only $\sigma_{tot}$ and $\sigma_{z}$ are read.
+
+# SOC Effects
+## SOC 
+`lspinorb` is used for control whether or not SOC(spin-orbit coupling) effects should be considered.
+
+Both `basis_type=pw` and `basis_type=lcao` support `scf` and `nscf` calculation with SOC effects.
+
+Atomic forces and cell stresses can not be calculated with SOC effects yet. 
+
+## Pseudopotentials and Numerical Atomic Orbitals
+For Norm-Conserving pseudopotentials, there are differences between SOC version and non-SOC version.
+
+Please check your pseudopotential files before calculating.
+In `PP_HEADER` part, keyword `has_so=1` and `relativistic="full"` refer to SOC effects have been considered, 
+which would lead to different `PP_NONLOCAL` and `PP_PSWFC` parts.
+Please be careful that `relativistic="full"` version can be used for SOC or non-SOC calculation, but `relativistic="scalar"` version only can be used for non-SOC calculation.
+When full-relativistic pseudopotential is used for non-SOC calculation, ABACUS will automatically transform it to scalar-relativistic version.
+
+Numerical atomic orbitals in ABACUS are unrelated with spin, and same orbital file can be used for SOC and non-SOC calculation.
+
+## Partial-relativistic SOC Effect
+Sometimes, for some real materials, both scalar-relativistic and full-relativistic can not describe the exact spin-orbit coupling. 
+Artificial modulation can help for these cases.
+
+`soc_lambda`, which has value range [0.0, 1.0] , is used for modulate SOC effect.
+In particular, `soc_lambda 0.0` refers to scalar-relativistic case and `soc_lambda 1.0` refers to full-relativistic case.
+