rename doc as docs

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+formats: all
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+   version: 3.8
+   install:
+   - requirements: docs/requirements.txt

docs/CITATIONS.md

@@ -0,0 +1,35 @@
+# How to Cite
+
+The following references are required to be cited when using ABACUS. Specifically:
+
+- **For general purpose:**
+
+    Mohan Chen, G. C. Guo, and Lixin He. "Systematically improvable optimized atomic basis sets for ab initio calculations." Journal of Physics: Condensed Matter 22.44 (2010): 445501.
+
+    Pengfei Li, et al. "Large-scale ab initio simulations based on systematically improvable atomic basis." Computational Materials Science 112 (2016): 503-517.
+
+- **If Stochastic DFT is used:**
+
+    Qianrui Liu, and Mohan Chen. "Plane-Wave-Based Stochastic-Deterministic Density Functional Theory for Extended Systems." <https://arxiv.org/abs/2204.05662>.
+
+- **If DFT+U is used:**
+
+    Xin Qu, et al. "DFT+ U within the framework of linear combination of numerical atomic orbitals." The Journal of Chemical Physics (2022).
+
+- **If second generation numerical orbital basis is used:**
+
+    Peize Lin, Xinguo Ren, and Lixin He. "Strategy for constructing compact numerical atomic orbital basis sets by incorporating the gradients of reference wavefunctions." Physical Review B 103.23 (2021): 235131.
+
+- **If berry curvature calculation is used in LCAO base:**
+
+    Gan Jin, Daye Zheng, and Lixin He. "Calculation of Berry curvature using non-orthogonal atomic orbitals." Journal of Physics: Condensed Matter 33.32 (2021): 325503.
+
+- **If DeePKS is used:**
+
+    Wenfei Li, Qi Ou, et al. "DeePKS+ABACUS as a Bridge between Expensive Quantum Mechanical Models and Machine Learning Potentials." <https://arxiv.org/abs/2206.10093>.
+
+- **If hybrid functional is used:**
+
+    Peize Lin, Xinguo Ren, and Lixin He. "Efficient Hybrid Density Functional Calculations for Large Periodic Systems Using Numerical Atomic Orbitals." Journal of Chemical Theory and Computation 2021, 17(1), 222–239.
+
+    Peize Lin, Xinguo Ren, and Lixin He. "Accuracy of Localized Resolution of the Identity in Periodic Hybrid Functional Calculations with Numerical Atomic Orbitals." Journal of Physical Chemistry Letters 2020, 11, 3082-3088.

docs/DevelopingTeam.md

@@ -0,0 +1,8 @@
+
+# Development team
+The current development team consists the following research groups/affiliations:
+- University of Science and Technology of China (Dr. Lixin He)
+- Peking University (Dr. Mohan Chen)
+- Institute of Physics, Chinese Academy of Sciences (Dr. Xinguo Ren)
+- Beijing AI for Science Institute
+- Institute of Artificial Intelligence, Hefei Comprehensive National Science Center. 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = $(PWD)
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/advanced/acceleration/cuda.md

@@ -0,0 +1,53 @@
+# CUDA GPU Implementations
+
+In ABACUS, we provide the option to use the GPU devices to accelerate the performance.
+And it has the following general features:
+
+- **Full gpu implementations**: During the SCF progress, `Psi`, `Hamilt`, `Hsolver`, `DiagCG`, and `DiagoDavid` classes are stored or calculated by the GPU devices.
+
+- **Electronic state data**: (e.g. electronic density) are moved from the GPU to the CPU(s) every scf step.
+
+- **Acclerated by the NVIDIA libraries**: `cuBLAS` for common linear algebra calculations, `cuSolver` for eigen values/vectors, and `cuFFT` for the conversions between the real and recip spaces.
+
+- **Multi GPU supprted**: Using multiple MPI tasks will often give the best performance. Note each MPI task will be bind to a GPU device with automatically computing load balancing.
+
+- **Parallel strategy**: K point parallel.
+
+## Required hardware/software
+
+To compile and use ABACUS in CUDA mode, you currently need to have an NVIDIA GPU and install the corresponding NVIDIA CUDA toolkit software on your system (this is only tested on Linux and unsupported on Windows):
+
+- Check if you have an NVIDIA GPU: cat /proc/driver/nvidia/gpus/*/information
+
+- Go to https://developer.nvidia.com/cuda-downloads
+
+- Install a driver and toolkit appropriate for your system (SDK is not necessary)
+
+
+## Building ABACUS with the GPU support:
+
+Check the [Advanced Installation Options](https://abacus-rtd.readthedocs.io/en/latest/advanced/install.html#build-with-cuda-support) for the installation of CUDA version support.
+
+## Run with the GPU support by editing the INPUT script:
+
+In `INPUT` file we need to set the value keyword [device](../input_files/input-main.md#device) to be `gpu`.
+
+## Examples
+We provides [examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/gpu) of gpu calculations.
+
+## Known limitations
+
+- CG and Davidson methods are supported, so the input keyword `ks_solver` can take the values `cg` or `dav`,
+- Only PW basis is supported, so the input keyword `basis_type` can only take the value `pw`,
+- Only k point parallelization is supported, so the input keyword `kpar` will be set to match the number of MPI tasks automatically.
+- Supported CUDA architectures:
+  - 60 # P100, 1080ti
+  - 70 # V100
+  - 75 # T4
+  - 80 # A100, 3090
+
+## FAQ
+```
+Q: Does the GPU implementations support atomic orbital basis sets?
+A: Currently no.
+```

docs/advanced/acceleration/index.rst

@@ -0,0 +1,12 @@
+=================================================
+Accelerate Performance
+=================================================
+
+This section describes various methods for improving ABACUS performance for different classes of problems running on different kinds of devices.
+
+Accelerated versions of CUDA GPU implementations have been added to ABACUS, which will typically run faster than the standard non-accelerated versions. This requires appropriate hardware to be present on your system, e.g. NVIDIA GPUs.
+
+.. toctree::
+   :maxdepth: 2
+
+   cuda

docs/advanced/elec_properties/Berry_phase.md

@@ -0,0 +1,73 @@
+# Berry Phase Calculation
+
+From version 2.0.0, ABACUS is capable of calculating macroscopic polarization of insulators by using the Berry phase method, known as the ["modern theory of polarization"](https://www.sciencedirect.com/science/article/abs/pii/S0022459612003234). To calculate the polarization, you need first to do a self-consistent calculation to get the converged charge density. Then, do a non-self-consistent calculation with berry_phase setting to 1. You need also to specify the direction of the polarization you want to calculate. An example is given in the directory [examples/berryphase/lcao_PbTiO3](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/berryphase/lcao_PbTiO3).
+
+To run this example, first do a self-consistent calculation:
+```
+cp INPUT-scf INPUT
+cp KPT-scf KPT
+mpirun -np 4 abacus
+```
+Then run a non-self-consistent berry-phase calculation:
+```
+cp INPUT-nscf-c INPUT
+cp KPT-nscf-c KPT
+mpirun -np 4 abacus
+```
+
+In this example, we calculate the electric polarization along c axis for PbTiO~3~, and below are the INPUT file (nscf) and KPT file (nscf):
+
+```
+INPUT_PARAMETERS
+pseudo_dir      ../../../tests/PP_ORB  //the path to locate the pesudopotential files
+orbital_dir     ../../../tests/PP_ORB  //the path to locate the numerical orbital files
+ntype         3
+ecutwfc       50 // Ry
+symmetry      0 // turn off symmetry
+calculation   nscf // non-self-consistent calculation
+basis_type    lcao // atomic basis
+init_chg  file // read charge from files
+berry_phase   1 // calculate Berry phase
+gdir          3 // calculate polarization along c axis
+```
+
+Note: You need to turn off the symmetry when do Berry phase calculations. Currently, ABACUS support Berry phase calculation with nspin=1 and nspin=2. The Berry phase can be calculated in both pw and lcao bases.
+- [berry_phase](../input_files/input-main.md#berry_phase) : 1, calculate berry phase; 0, no calculate berry phase.
+- [gdir](../input_files/input-main.md#gdir) : 1, 2, 3, the lattice vector direction of the polarization you want to calculate.
+
+The KPT file need to be modified according to gdir in the INPUT file. Generally, you need denser k points along this direction. For example, in the following KPT file, 4 k-points are taken along the a and b axes, and 8 k-points are taken along the c-axis. You should check the convergence of the k points when calculating the polarization.
+
+```
+K_POINTS
+0
+Gamma
+4 4 8 0 0 0
+```
+The results of the berry phase calculation are written in the “running_nscf.log” in the OUT folder. You may search for these results by searching for keywords “POLARIZATION CALCULATION”.
+
+The results are shown as follows:
+```
+ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+ |                                                                    |
+ | POLARIZATION CALCULATION:                                          |
+ |                  Modern Theory of Polarization                     |
+ | calculate the Macroscopic polarization of a crystalline insulator  |
+ | by using Berry Phase method.                                       |
+ |                                                                    |
+ <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+
+ VALUES OF POLARIZATION
+
+  The Ionic Phase:   -0.10600
+ Electronic Phase:    0.92508
+
+ The calculated polarization direction is in R3 direction
+
+ P =    7.4095194  (mod   18.0922373)  (   0.0000000,   0.0000000,   7.4095194) (e/Omega).bohr
+
+ P =    0.0155792  (mod    0.0380407)  (   0.0000000,   0.0000000,   0.0155792) e/bohr^2
+
+ P =    0.8906925  (mod    2.1748536)  (   0.0000000,   0.0000000,   0.8906925) C/m^2
+```
+
+The electric polarization **P** is multivalued, which modulo a quantum e**R**/V~cell~. Note: the values in parentheses are the components of the **P** along the c axis in the x, y, z Cartesian coordinates when set gdir = 3 in INPUT file.

docs/advanced/elec_properties/Mulliken.md

@@ -0,0 +1,62 @@
+# Mulliken Charge Analysis
+
+From version 2.1.0, ABACUS has the function of Mulliken population analysis. The example can be found in [examples/mulliken](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/mulliken). \
+To use this function, set [out_mul](./input-main.md#out_mul) to `1` in the INPUT file. After calculation, there will be an output file named `mulliken.txt` in the output directory. In MD calculations, the output interval is controlled by the keyword [out_interval](./input-main.md#out_interval). In the file, there are contents like (`nspin 1`):
+
+```
+STEP: 0
+CALCULATE THE MULLIkEN ANALYSIS FOR EACH ATOM
+ Total charge of spin 1:	8
+ Total charge:	8
+Decomposed Mulliken populations
+0                 Zeta of Si                        Spin 1
+s                        0                       1.2553358
+  sum over m                                     1.2553358
+s                        1                    -0.030782972
+  sum over m                                  -0.030782972
+  sum over m+zeta                                1.2245529
+px                        0                      0.85945806
+py                        0                      0.85945806
+pz                        0                      0.85945806
+  sum over m                                     2.5783742
+px                        1                    0.0065801228
+py                        1                    0.0065801228
+pz                        1                    0.0065801228
+  sum over m                                   0.019740368
+  sum over m+zeta                                2.5981145
+d3z^2-r^2                        0                       0.0189287
+dxy                        0                     0.046491729
+dxz                        0                     0.046491729
+dx^2-y^2                        0                       0.0189287
+dyz                        0                     0.046491729
+  sum over m                                    0.17733259
+  sum over m+zeta                               0.17733259
+Total Charge on atom:  Si                   4
+ ...
+```
+
+The file gives Mulliken charge in turn according to the order of atoms in the system. For example, the following block is for the first atom in system (`nspin 2`),
+
+```
+0            Zeta of Si               Spin 1              Spin 2                Sum                Diff
+...
+Total Charge on atom:  Si                   4
+Total Magnetism on atom:  Si      -1.2739809e-14
+```
+
+And the next block is for the second atom in system, and so on.
+
+```
+1            Zeta of Si               Spin 1              Spin 2                Sum                Diff
+...
+```
+
+For each atom, the file gives detailed Mulliken population analysis at different levels,
+
+-   magnetic quantum number level: such as lines beigin with ‘s,px,py,pz,...’
+-   azimuthal quantum number level: such as lines begin with ‘sum over m’.
+-   principal quantum number level: such as lines begin with ‘sum over m+zeta’. Here ‘zeta’
+    equals ‘zeta’ in the file, which means how many radial atomic orbitals there are for a given orbital angular momentum.
+-   atomic level: such as lines begin with ‘Total Charge on atom’.
+
+More orbital information can be found in 'Orbital' file output with 'mulliken.txt' when `out_mul 1`

docs/advanced/elec_properties/band.md

@@ -0,0 +1,93 @@
+# Extracting Band Structure
+
+ABACUS can calculate the energy band structure, and the examples can be found in [examples/band](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/band).
+Similar to the [DOS case](https://abacus-rtd.readthedocs.io/en/latest/advanced/elec_properties/dos.html), we first, do a ground-state energy calculation ***with one additional keyword "[out_chg](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-chg)" in the INPUT file***:
+
+```
+out_chg             1
+```
+
+This will produce the converged charge density, which is contained in the file SPIN1_CHG.cube.
+Then, use the same `STRU` file, pseudopotential file and atomic orbital file (and the local density matrix file onsite.dm if DFT+U is used) to do a non-self-consistent calculation. In this example, the potential is constructed from the ground-state charge density from the proceeding calculation. Now the INPUT file is like:
+
+```
+INPUT_PARAMETERS
+#Parameters (General)
+ntype 1
+nbands 8
+calculation nscf
+basis_type lcao
+read_file_dir   ./
+
+#Parameters (Accuracy)
+ecutwfc 60
+scf_nmax 50
+scf_thr 1.0e-9
+pw_diag_thr 1.0e-7
+
+#Parameters (File)
+init_chg file
+out_band 1
+out_proj_band 1
+
+#Parameters (Smearing)
+smearing_method gaussian
+smearing_sigma 0.02
+```
+
+Here the the relevant k-point file KPT looks like,
+
+```
+K_POINTS # keyword for start
+6 # number of high symmetry lines
+Line # line-mode
+0.5 0.0 0.5 20 # X
+0.0 0.0 0.0 20 # G
+0.5 0.5 0.5 20 # L
+0.5 0.25 0.75 20 # W
+0.375 0.375 0.75 20 # K
+0.0 0.0 0.0 1 # G
+```
+
+This means we are using:
+
+- 6 number of k points, here means 6 k points:
+  (0.5, 0.0, 0.5) (0.0, 0.0, 0.0) (0.5, 0.5, 0.5) (0.5, 0.25, 0.75) (0.375, 0.375, 0.75) (0.0, 0.0,
+  0.0)
+- 20/1 number of k points along the segment line, which is constructed by two adjacent k
+  points.
+
+Run the program, and you will see a file named BANDS_1.dat in the output directory. Plot it
+to get energy band structure.
+
+If "out_proj_band" set 1, it will also produce the projected band structure in a file called PBAND_1 in xml format.
+
+The PBAND_1 file starts with number of atomic orbitals in the system, the text contents of element `<band structure>` is the same as data in the BANDS_1.dat file, such as:
+
+```
+<pband>
+<nspin>1</nspin>
+<norbitals>153</norbitals>
+<band_structure nkpoints="96" nbands="50" units="eV">
+...
+
+```
+
+The rest of the files arranged in sections, each section with a header such as below:
+
+```
+<orbital
+ index="                                       1"
+ atom_index="                                       1"
+ species="Si"
+ l="                                       0"
+ m="                                       0"
+ z="                                       1"
+>
+<data>
+...
+</data>
+
+```
+
+The shape of text contents of element `<data>` is (Number of k-points, Number of bands)