Skip to content

Commit

Permalink
Docs: update the docs for deeptb (#34)
Browse files Browse the repository at this point in the history
* remove the redundant doc folder, since  docs folder is already there.

* update the band figures for hBN in docs/img folder.

* 📃 docs(update index and quick start)

* update example hBN

* docs: update hands_on.md

* 📃 docs(all): update dptb docs

modify the docs template from abacus, make it to docs for deeptb.
This commit contains  most of docs for deeptb, but many of the documents is still empty only created with a title.
  • Loading branch information
QG-phy authored Oct 18, 2023
1 parent 697ce71 commit bbc0d09
Show file tree
Hide file tree
Showing 69 changed files with 392 additions and 7,068 deletions.
Binary file removed doc/img/Electronic_structure_of_materials.jpg
Binary file not shown.
Binary file removed doc/img/err_hist.png
Binary file not shown.
Binary file removed doc/img/flexibility.png
Binary file not shown.
Binary file removed doc/img/gap_64_strain.png
Binary file not shown.
Binary file removed doc/img/million_atoms.png
Binary file not shown.
300 changes: 12 additions & 288 deletions docs/CONTRIBUTING.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/DevelopingTeam.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

# Development team
The current development team consists the following research groups/affiliations:
- Peking University (Dr. Qiangqiang Gu)
- AI for Science Institute, Beijing (Dr. Qiangqiang Gu)
- Tianjin University (Dr. Zhanghao Zhouyin)
- Beijing AI for Science Institute
- AI for Science Institute, Beijing
42 changes: 4 additions & 38 deletions docs/advanced/acceleration/cuda.md
Original file line number Diff line number Diff line change
@@ -1,53 +1,19 @@
# 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.
# GPU Implementations

## 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
## Building DeePTB with the GPU support:

- 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.
```

4 changes: 1 addition & 3 deletions docs/advanced/acceleration/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,7 @@
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.
This section describes various methods for improving DeePTB performance for different classes of problems running on different kinds of devices.

.. toctree::
:maxdepth: 2
Expand Down
1 change: 1 addition & 0 deletions docs/advanced/dptb_env.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Environment-dependent TB
73 changes: 0 additions & 73 deletions docs/advanced/elec_properties/Berry_phase.md

This file was deleted.

62 changes: 0 additions & 62 deletions docs/advanced/elec_properties/Mulliken.md

This file was deleted.

94 changes: 1 addition & 93 deletions docs/advanced/elec_properties/band.md
Original file line number Diff line number Diff line change
@@ -1,93 +1 @@
# 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)
# Band structure
43 changes: 0 additions & 43 deletions docs/advanced/elec_properties/charge.md

This file was deleted.

Loading

0 comments on commit bbc0d09

Please sign in to comment.