Skip to content

Commit

Permalink
Merge pull request #1296 from hongriTianqi/docs_quick
Browse files Browse the repository at this point in the history 
docs: add lcao quick example
  • Loading branch information
@hongriTianqi
hongriTianqi committed Sep 26, 2022
2 parents 752633f + 2ee0e56 commit b6d5b10
Show file tree
Hide file tree
Showing 2 changed files with 128 additions and 57 deletions.
2 changes: 0 additions & 2 deletions docs/examples/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,13 @@ Examples
BSSE
dispersion
dos
dpgen
electric_dipole
force
hybrid
implicit-sol
magnetic
md
mulliken
phonopy
potential
stochastic
stress
Expand Down
183 changes: 128 additions & 55 deletions docs/quick_start/hands_on.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

## Running SCF Calculation

Here, we take FCC MgO as a quick start example. Firstly we need to build the structure file. The default name of a structure file in ABACUS is `STRU`, e.g.:
### A quick LCAO example

ABACUS is well known for its support of LCAO (Linear Combination of Atomic Orbital) basis set in calculating periodic condensed matter systems, so it's a good choice to start from a LCAO example of self-consistent field (SCF) calculation. Here, FCC MgO has been chosen as a quick start example. The default name of a structure file in ABACUS is `STRU`. The `STRU` file for FCC MgO in a LCAO calculation is shown below:

```
#This is the atom file containing all the information
Expand All @@ -12,13 +14,17 @@ ATOMIC_SPECIES
Mg 24.305 Mg_ONCV_PBE-1.0.upf # element name, atomic mass, pseudopotential file
O 15.999 O_ONCV_PBE-1.0.upf
NUMERICAL_ORBITAL
Mg_gga_8au_100Ry_4s2p1d.orb
O_gga_8au_100Ry_2s2p1d.orb
LATTICE_CONSTANT
8.04411131 # 3.01/sqrt(2.)/0.52918
1.8897259886 # 1.8897259886 Bohr = 1.0 Angstrom
LATTICE_VECTORS
1.00000000 0.00000000 0.00000000 # 1/0.52918 = 1.88971616
0.00000000 1.00000000 0.00000000
0.00000000 0.00000000 1.00000000
4.25648 0.00000 0.00000
0.00000 4.25648 0.00000
0.00000 0.00000 4.25648
ATOMIC_POSITIONS
Direct #Cartesian(Unit is LATTICE_CONSTANT)
Expand All @@ -38,30 +44,22 @@ O #Name of element
0.0 0.5 0.0 0 0 0 #x,y,z, move_x, move_y, move_z
```

Secondly, one needs to set the `INPUT` file, which sets all key parameters to direct ABACUS how to calculte and what to output:
Next, the `INPUT` file is required, which sets all key parameters to direct ABACUS how to calculte and what to output:
```
INPUT_PARAMETERS
#Parameters (System)
suffix MgO
ntype 2
nelec 0.0
pseudo_dir ./
calculation scf # this is the key parameter telling abacus to do a scf calculation
#Parameters (PW)
orbital_dir ./
ecutwfc 100 # Rydberg
scf_thr 0.01 # Rydberg
#Parameters (electronic opt)
basis_type pw # or lcao, lcao_in_pw
ks_solver cg # & david for pw; genelpa, hpseps & lapack (single cpu) for lcao
smearing_method fixed # or gauss, mp
smearing_sigma 0.01
mixing_type pulay # or kerker, plain, pulay-kerker
mixing_beta 0.7
scf_thr 1e-4 # Rydberg
basis_type lcao
calculation scf # this is the key parameter telling abacus to do a scf calculation
```
The pseudopotential files of `Mg_ONCV_PBE-1.0.upf` and `O_ONCV_PBE-1.0.upf` should be provided under the directory of `pseudo_dir`.

The next mandatory input file is called `KPT`, which sets the k-mesh. Below is an example:
The pseudopotential files of `Mg_ONCV_PBE-1.0.upf` and `O_ONCV_PBE-1.0.upf` should be provided under the directory of `pseudo_dir`, and the orbital files `Mg_gga_8au_100Ry_4s2p1d.orb` and `O_gga_8au_100Ry_2s2p1d.orb` under the directory of `orbital_dir`. The pseudopotential and orbital files can be downloaded from the [ABACUS website](http://abacus.ustc.edu.cn/pseudo/list.htm).

The final mandatory input file is called `KPT`, which sets the reciprocal space k-mesh. Below is an example:

```
K_POINTS
Expand All @@ -70,39 +68,38 @@ Gamma
4 4 4 0 0 0
```

Ok, now that all key input files have been set, we should be able to run the first quick example. The simplest way is to use the command line, e.g.:
After all the above input files have been set, one should be able to run the first quick example. The simplest way is to use the command line, e.g.:

```
mpirun -np 4 abacus
mpirun -np 2 abacus
```

The main output information appears in `OUT.MgO/running_scf.log`, which starts with
The main output information is stored in the file `OUT.MgO/running_scf.log`, which starts with

```
WELCOME TO ABACUS
'Atomic-orbital Based Ab-initio Computation at UStc'
Website: http://abacus.ustc.edu.cn/
WELCOME TO ABACUS
'Atomic-orbital Based Ab-initio Computation at UStc'
Website: http://abacus.ustc.edu.cn/
Version: Parallel, in development
Processor Number is 4
Start Time is Tue Sep 22 18:23:54 2022
Processor Number is 2
Start Time is Sat Sep 24 13:06:35 2022
------------------------------------------------------------------------------------
READING GENERAL INFORMATION
global_out_dir = OUT.MgO/
global_in_card = INPUT
pseudo_dir =
orbital_dir =
pseudo_type = auto
pseudo_dir =
orbital_dir =
DRANK = 1
DSIZE = 8
DSIZE = 2
DCOLOR = 1
GRANK = 1
GSIZE = 1
The esolver type has been set to : ksdft_lcao
Expand All @@ -120,46 +117,122 @@ The main output information appears in `OUT.MgO/running_scf.log`, which starts w
| in real and reciprocal space is also shown. |
| |
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
......
```

If ABAUCS finishes successfully, you will be able to obtain the total energy in `OUT.MgO/running_scf.log`:
If ABAUCS finishes successfully, the total energy will be output in `OUT.MgO/running_scf.log`:

```
--------------------------------------------
!FINAL_ETOT_IS -1908.456553781335 eV
!FINAL_ETOT_IS -7663.897267807250 eV
--------------------------------------------
```

Congratulations! ABACUS has come under you command from now on!
### A quick PW example

In order to run a SCF calculation with PW (Plane Wave) basis set, one has only to change the tag `basis_type` from `lcao` to `pw` in the `INPUT` file, and no longer needs to provide orbital files under `NUMERICAL_ORBITAL` in the `STRU` file.

The `INPUT` file follows as:
```
INPUT_PARAMETERS
suffix MgO
ntype 2
pseudo_dir ./
ecutwfc 100 # Rydberg
scf_thr 1e-4 # Rydberg
basis_type pw # changes the type of basis set
calculation scf # this is the key parameter telling abacus to do a scf calculation
```

And the `STRU` file will be:

```
#This is the atom file containing all the information
#about the lattice structure.
ATOMIC_SPECIES
Mg 24.305 Mg_ONCV_PBE-1.0.upf # element name, atomic mass, pseudopotential file
O 15.999 O_ONCV_PBE-1.0.upf
LATTICE_CONSTANT
1.8897259886 # 1.8897259886 Bohr = 1.0 Angstrom
LATTICE_VECTORS
4.25648 0.00000 0.00000
0.00000 4.25648 0.00000
0.00000 0.00000 4.25648
ATOMIC_POSITIONS
Direct #Cartesian(Unit is LATTICE_CONSTANT)
Mg #Name of element
0.0 #Magnetic for this element.
4 #Number of atoms
0.0 0.0 0.0 0 0 0 #x,y,z, move_x, move_y, move_z
0.0 0.5 0.5 0 0 0 #x,y,z, move_x, move_y, move_z
0.5 0.0 0.5 0 0 0 #x,y,z, move_x, move_y, move_z
0.5 0.5 0.0 0 0 0 #x,y,z, move_x, move_y, move_z
O #Name of element
0.0 #Magnetic for this element.
4 #Number of atoms
0.5 0.0 0.0 0 0 0 #x,y,z, move_x, move_y, move_z
0.5 0.5 0.5 0 0 0 #x,y,z, move_x, move_y, move_z
0.0 0.0 0.5 0 0 0 #x,y,z, move_x, move_y, move_z
0.0 0.5 0.0 0 0 0 #x,y,z, move_x, move_y, move_z
```

Use the same pseudopotential and `KPT` files as the above LCAO example. The final total energy will be output:

```
--------------------------------------------
!FINAL_ETOT_IS -7665.688319476949 eV
--------------------------------------------
```

## Running Geometry Optimization

Let's consider how to run geometry optimization in ABACUS. As you may have guessed, one have only to set `calculation` to `cell-relax`. But wait a bit, how should we set the convergence criteria for atomics force and cell stress? What's the maximum number of ionc steps in one optimization trail? Well, one contact `INPUT` reads like:
In order to run a full geometry optimization in ABACUS, the tag `calculation` in `INPUT` should be set to `cell-relax`. In addition, the convergence criteria for atomics force and cell stress can be set through the tags `force_thr_ev` and `stress_thr`, respectively. The maximum number of ionc steps is controlled by `relax_nmax`.

### A quick LCAO example

The `INPUT` is provided as follows:

```
INPUT_PARAMETERS
#Parameters (System)
suffix MgO
ntype 2
nelec 0.0
pseudo_dir ./
orbital_dir ./
ecutwfc 100 # Rydberg
scf_thr 1e-4 # Rydberg
basis_type lcao
calculation cell-relax # this is the key parameter telling abacus to do a optimization calculation
force_thr_ev 0.01 # the threshold of the force convergence, in unit of eV/Angstrom
stress_thr 1 # the threshold of the stress convergence, in unit of kBar
stress_thr 5 # the threshold of the stress convergence, in unit of kBar
relax_nmax 100 # the maximal number of ionic iteration steps
#Parameters (PW)
ecutwfc 100 # Rydberg
scf_thr 0.01 # Rydberg
out_stru 1
```
Use the same `KPT`, `STRU`, pseudopotential, and orbital files as in the above SCF-LCAO example. The final optimized structure can be found in `STRU_NOW.cif` and `OUT.MgO/running_cell-relax.log`.

### A quick PW example

#Parameters (electronic opt)
basis_type pw # or lcao, lcao_in_pw
ks_solver cg # & david for pw; genelpa, hpseps & lapack (single cpu) for lcao
smearing_method fixed # or gauss, mp
smearing_sigma 0.01
mixing_type pulay # or kerker, plain, pulay-kerker
mixing_beta 0.7
The `INPUT` is provided as follows:

```
INPUT_PARAMETERS
suffix MgO
ntype 2
nelec 0.0
pseudo_dir ./
ecutwfc 100 # Rydberg
scf_thr 1e-4 # Rydberg
basis_type pw
calculation cell-relax # this is the key parameter telling abacus to do a optimization calculation
force_thr_ev 0.01 # the threshold of the force convergence, in unit of eV/Angstrom
stress_thr 5 # the threshold of the stress convergence, in unit of kBar
relax_nmax 100 # the maximal number of ionic iteration steps
out_stru 1
```

Now we can use the same `KPT` and `STRU` file as above. Run this optimization example, the final optimized structure will appear under the directory `OUT.MgO` with the name of `STRU_NOW.cif`.
Use the same `KPT`, `STRU`, and pseudopotential files as in the above SCF-PW examples. The final optimized structure can be found in `STRU_NOW.cif` and `OUT.MgO/running_cell-relax.log`.

0 comments on commit b6d5b10

Please sign in to comment.