Skip to content

Commit

Permalink
Docs: add docs of band/berry-phase/dos/mulliken/potential/wfc (#1295)
Browse files Browse the repository at this point in the history
  • Loading branch information
@pxlxingliang
pxlxingliang committed Sep 23, 2022
1 parent 2101e0c commit 7044dc0
Show file tree
Hide file tree
Showing 26 changed files with 693 additions and 8 deletions.
77 changes: 76 additions & 1 deletion docs/advanced/elec_properties/Berry_phase.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,76 @@
# Berry Phase Calculation
# 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 PbTiO3, 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 : 1, calculate berry phase; 0, no calculate berry phase.
- 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 <b>P</b> is multivalued, which modulo a quantum eR=<sub>Vcell</sub>. Note: the values in parentheses are the components of the <b>P</b> along the c axis in the x, y, z Cartesian coordinates when set gdir = 3 in INPUT file.
56 changes: 55 additions & 1 deletion docs/advanced/elec_properties/Mulliken.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,55 @@
# Mulliken Charge Analysis
# 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’ to ‘1’ in the INPUT file. After calculation, there will be an output file named mulliken.txt in the output directory. In the file, there are contents like:

```
CALCULATE THE MULLIkEN ANALYSIS FOR EACH ATOM
8 (Total charge all spin 1)
8 (Total charge of the system)
Decomposed Mulliken populations
0 Si Up spin Down spin Sum Diff
multiple
s 0 0.51810998 0.51810998 1.03622 0
sum over m 0.51810998 0.51810998 1.03622 0
s 1 0.053661483 0.053661483 0.10732297 0
sum over m 0.053661483 0.053661483 0.10732297 0
sum over m+mul 0.57177146 0.57177146 1.1435429 0
px 0 0.43730519 0.43730519 0.87461038 0
py 0 0.43730519 0.43730519 0.87461038 0
pz 0 0.43730519 0.43730519 0.87461038 0
sum over m 1.3119156 1.3119156 2.6238311 0
px 1 0.0065031719 0.0065031719 0.013006344 0
py 1 0.0065031719 0.0065031719 0.013006344 0
pz 1 0.0065031719 0.0065031719 0.013006344 0
sum over m 0.019509516 0.019509516 0.039019031 0
sum over m+mul 1.3314251 1.3314251 2.6628502 0
d3z^2-r^2 0 0.011750855 0.011750855 0.023501711 0
dxy 0 0.024433913 0.024433913 0.048867826 0
dxz 0 0.024433913 0.024433913 0.048867826 0
dx^2-y^2 0 0.011750855 0.011750855 0.023501711 0
dyz 0 0.024433913 0.024433913 0.048867826 0
sum over m 0.096803451 0.096803451 0.1936069 0
sum over m+mul 0.096803451 0.096803451 0.1936069 0
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,
```
0 Si Up spin Down spin Sum Diff
...
Total Charge on atom Si 4.0241712
```

And the next block is for the second atom in system, and so on.
```
1 Si Up spin Down spin 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+mul’. Here ‘mul’
equals ‘multiple’ 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’.
92 changes: 91 additions & 1 deletion docs/advanced/elec_properties/band.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,91 @@
# Extracting Band Structure
# Extracting Band Structure

ABACUS can calculate the energy band structure, and the exampples 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. \
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)
122 changes: 121 additions & 1 deletion docs/advanced/elec_properties/dos.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,121 @@
# Calculating DOS and PDOS
# Calculating DOS and PDOS

## DOS

ABACUS can calculate the density of states (DOS) of the system, and the exampples can be found in [examples/dos](#https://github.com/deepmodeling/abacus-develop/tree/develop/examples/dos).\
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. \
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)
suffix Si2_diamond
ntype 1
nbands 8
calculation nscf
basis_type lcao
read_file_dir ./
#Parameters (Accuracy)
ecutwfc 60
symmetry 1
scf_nmax 50
scf_thr 1.0e-9
pw_diag_thr 1.0e-7
#Parameters (File)
init_chg file
out_dos 1
dos_sigma 0.07
#Parameters (Smearing)
smearing_method gaussian
smearing_sigma 0.02
```

Some parameters in the INPUT file are explained:
- calculation

choose which kind of calculation: scf calculation, nscf calculation, structure relaxation or Molecular Dynamics. Now we need to do one step of nscf calculation.
Attention: This is a main variable of ABACUS, and for its more information please see the [here](#https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#calculation).

- pw_diag_thr

threshold for the CG method which diagonalizes the Hamiltonian to get eigenvalues and eigen wave functions. If one wants to do nscf calculation, pw_diag_thr needs to be changed to a smaller account, typically smaller than 1.0e-3. Note that this parameter only apply to plane-wave calculations that employ the CG or Davidson method to diagonalize the Hamiltonian. For its more information please see the [here](#https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#pw_diag_thr).

For LCAO calculations, this parameter will be neglected !
- init_chg

the type of starting density. When doing scf calculation, this variable can be set ”atomic”. When doing nscf calculation, the charge density already exists(eg. in SPIN1_CHG), and the variable should be set as ”file”. It means the density will be read from the existing file SPIN1_CHG. For its more information please see the [here](#https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#init_chg).

- out_dos

output density of state(DOS). The unit of DOS is `(number of states)/(eV * unitcell)`. For its more information please see the [here](#https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#out_dos).

- dos_sigma

the gaussian smearing parameter(DOS), in unit of eV. For its more information please see the [here](#https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#dos_sigma).

- read_file_dir

the location of electron density file. For its more information please see the [here](#https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#read_file_dir).

To have an accurate DOS, one needs to have a denser k-point mesh. For example, the KPT file can be set as:
```
K_POINTS
0
Gamma
8 8 8 0 0 0
```
Run the program, and you will see a file named DOS1_smearing.dat in the output directory. The first two columns in the file are the energy and DOS, respectively, and the third column is the sum of DOS. Plot file DOS1_smearing.dat with graphing software, and you’ll get the DOS.
```
-5.49311 0.0518133 0.0518133
-5.48311 0.0641955 0.116009
-5.47311 0.0779299 0.193939
-5.46311 0.0926918 0.28663
-5.45311 0.108023 0.394653
-5.44311 0.123346 0.517999
...
```

## PDOS

Along with the DOS1_smearing.dat file, we also produce the projected density of states (PDOS) in a file called PDOS.

The PDOS file starts with number of atomic orbitals in the system, then a list of energy values, such as:
```
<pdos>
<nspin>1</nspin>
<norbitals>26</norbitals>
<energy_values units="eV">
-5.50311
-5.49311
-5.48311
-5.47311
...
```

The rest of the fileis 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>
```
which tells the atom and symmetry of the current atomic orbital, and followed by the PDOS values. The values can thus be plotted against the energies. The unit of PDOS is also `(number of states)/(eV * unitcell)`.

0 comments on commit 7044dc0

Please sign in to comment.