Dev (#18)

* add two dict. onsideDB_ev onsiteDB_hartree now the onsiteDB equals onsiteDB_hartree. the onsideDB_ev is just for reader to read the values. (#2) Co-authored-by: qqgu <[email protected]> * update the model_arch in doc/imag * update silicon example * add silicon notebook * update readme add the deeptb paper link. * update readme Gallary * update readme include deeptb paper link. * Merge the workflow to dev (#13) * update readme (#5) * update readme includes the deeptb paper link. --------- * Update README.md * add 1 million atoms figure * Update README.md * Update README.md * Add files via upload * Add files via upload * Add files via upload add flexibility figure * Nrl qg (#7) * update hBN example * add the xdat.traj in hbn sparse data. * Create unit_test.yml add unit test config file * Update unit_test.yml * update unit test for github * update unit test * update unit test config * try install openblas in advance * test * test * test * test * test * test * test * test * test * test * test * test * update * update Dockerfile image automaking and unit test * test action * add Dockerfile * update Dockerfile * update dockerfile * update dockerfile * update dockerfile * update dockerfile * update dockerfile * update dockerfile * update dockerfile * update * update unit_test.yml * update uni_test.yml * update unit_test * test ut (#12) * test ut * update unit_test * update unit_test * update unit_test * update unit_test * update unit_test * update unit_test * update unit_test * update * update unit_test * update unit_test * update unit_Test * update unit_test * update unit_test * update unit_test * update self-hosted runner * update unit_test * update unit_test * test output * update unit_test * update unit_test * update unit_test * update * update * update * update unit_test * update why it does not work??? * update ut * update unit_test * update unit_test * update unit_test * update unit test * update unit_test * update unit_test * update unit_test * update unit_test to remove push trigger --------- Co-authored-by: Qiangqiang Gu <[email protected]> * update docs (#14) * rename doc as docs (#15) * update docs * rename doc to docs * delete doc * rename some essential things * update conf.py * add doc issue template: by create documentation.yml --------- Co-authored-by: Qiang Gu <[email protected]> Co-authored-by: qqgu <[email protected]> Co-authored-by: Yinzhanghao Zhou <[email protected]> Co-authored-by: zhanghao <[email protected]>
deepmodeling · Sep 14, 2023 · 3db0ceb · 3db0ceb
1 parent f84d1c1
commit 3db0ceb
Show file tree

Hide file tree

Showing 63 changed files with 7,505 additions and 0 deletions.
diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml
@@ -0,0 +1,18 @@
+name: Docs
+description: For users or developers to report issues related to software documentation, such as missing or incomplete documentation, or documentation that is difficult to understand.
+labels: [Docs]
+assignees: Qiangqiang Gu
+body:
+- type: textarea
+  attributes:
+    label: Details
+    description: |
+      Please provide details about the documentation issue you are experiencing. Include any relevant information such as the specific section of the documentation, the information that is missing or unclear, and any suggestions for improvement. 
+    placeholder: |
+      Example: The documentation for the band structure calculations is missing. I have read the online manual, but I am still not sure how to do it. My suggestion is to add a new section to the online manual that describes this.
+  validations:
+      required: true
+- type: markdown
+  attributes:
+    value: >
+      Thank you for reporting this documentation issue. We will review and update the documentation as necessary. 📚
diff --git a/.readthedocs.yaml b/.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
diff --git a/docs/CITATIONS.md b/docs/CITATIONS.md
@@ -0,0 +1,7 @@
+# How to Cite
+
+The following references are required to be cited when using ABACUS. Specifically:
+
+- **For general purpose:**
+
+    Gu, Qiangqiang, et al. "DeePTB: A deep learning-based tight-binding approach with $ ab$ $ initio $ accuracy." arXiv preprint arXiv:2307.04638 (2023).
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
diff --git a/docs/DevelopingTeam.md b/docs/DevelopingTeam.md
@@ -0,0 +1,6 @@
+
+# Development team
+The current development team consists the following research groups/affiliations:
+- Peking University (Dr. Qiangqiang Gu)
+- Tianjin University (Dr. Zhanghao Zhouyin)
+- Beijing AI for Science Institute
diff --git a/docs/Makefile b/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)
diff --git a/docs/advanced/acceleration/cuda.md b/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.
+```
diff --git a/docs/advanced/acceleration/index.rst b/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
diff --git a/docs/advanced/elec_properties/Berry_phase.md b/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.
diff --git a/docs/advanced/elec_properties/Mulliken.md b/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`
diff --git a/docs/advanced/elec_properties/band.md b/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)