Docs: add the docs and examples of charge density (#1308)

docs/advanced/elec_properties/charge.md

@@ -1 +1,39 @@
-# Extracting Charge Density
+# Extracting Charge Density
+
+ABACUS can output the charge density by adding the keyword [out_chg](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-chg) in INPUT file:
+```
+out_chg             1
+```
+After finishing the calculation, the information of the charge density is stroed in files `OUT.${suffix}/SPIN${spin}_CHG`. At the same time, the files with the same name and with the suffix '.cube' wilL be outputed, and can be used to do visualization. \
+The SPIN${spin}_CHG file looks like:
+```
+test
+ 3.17506
+ 1 0 0
+ 0 1 0
+ 0 0 1
+ Fe1 Fe2
+ 1 1
+Direct
+ 0 0 0
+ 0.5 0.5 0.5
+
+  2
+  0.915564 (fermi energy)
+  27 27 27
+
+ 6.63608279258e-01 8.42291750502e-01 1.16305511314e+00 1.18317627770e+00 8.03596207480e-01 3.76685921988e-01 1.43138520280e-01 5.93331483316e-02
+ 3.22553088343e-02 2.07904703287e-02 1.50998149986e-02 1.26952816838e-02 1.15435826326e-02 1.08144612206e-02 1.08144612206e-02 1.15435826326e-02
+ ...
+ ```
+The first 5 lines are the informations of lattice, in order: \
+ lattice name (if keyword [latname](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#latname) is not specified in INPUT, this will be "test"), \
+ lattice constance with unit in angstrom, \
+ lattice vector a, \
+ lattice vector b, \
+ lattice vector c. \
+The following lines are about the elements and coordinates, in order: all elements, the atom number of each elements, the type of coordinate, the coordinates.\
+After a blank line, the output is the values of NSPIN and fermi energy.\
+The following line is the number of grid along x/y/z, and the rest lines are the value of charge density at each grid.
+
+The examples can be found in [examples/charge_density](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/charge_density)

examples/charge_density/README

@@ -0,0 +1,10 @@
+/*******************************************************************************/
+/
+/ These are the examples of ABACUS program.
+/
+/*******************************************************************************/
+
+These examples show how to output the charge density of system.
+One only need to set the keyword 'out_chg' to '1' in the INPUT file.
+After the calculation, one can find file SPIN${spin}_CHG in OUT.${suffix}
+

examples/charge_density/lcao_nspin1_Si2/INPUT

@@ -0,0 +1,16 @@
+INPUT_PARAMETERS
+#Parameters     (General)
+pseudo_dir                      ../../../tests/PP_ORB
+orbital_dir                     ../../../tests/PP_ORB
+calculation                     scf
+ntype                           1       
+nbands                          8
+#Parameters (Methos)
+basis_type                      lcao
+symmetry                        0       
+#Parameters (Accuracy)
+ecutwfc                         50
+scf_thr                         1.0e-7  // about iteration
+scf_nmax			100
+#Parameters (File)
+out_chg                         1

examples/charge_density/lcao_nspin1_Si2/KPT

@@ -0,0 +1,4 @@
+K_POINTS
+0
+Gamma
+4 4 4 0 0 0

examples/charge_density/lcao_nspin1_Si2/STRU

@@ -0,0 +1,22 @@
+ATOMIC_SPECIES
+Si 1.000 Si.pz-vbc.UPF
+
+NUMERICAL_ORBITAL
+./Si_lda_8.0au_50Ry_2s2p1d
+
+LATTICE_CONSTANT
+10.2  // add lattice constant
+
+LATTICE_VECTORS
+0.5 0.5 0.0
+0.5 0.0 0.5
+0.0 0.5 0.5
+
+ATOMIC_POSITIONS
+Cartesian //Cartesian or Direct coordinate.
+
+Si	// Element type	
+0.0	// magnetism
+2	// number of atoms
+0.00 0.00 0.00 0 0 0
+0.25 0.25 0.25 1 1 1

examples/charge_density/lcao_nspin1_Si2/run.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+ABACUS_PATH=$(awk -F "=" '$1=="ABACUS_PATH"{print $2}' ../../SETENV)
+ABACUS_NPROCS=$(awk -F "=" '$1=="ABACUS_NPROCS"{print $2}' ../../SETENV)
+ABACUS_THREADS=$(awk -F "=" '$1=="ABACUS_THREADS"{print $2}' ../../SETENV)
+
+OMP_THREADS_NUM=${ABACUS_THREADS} mpirun -np ${ABACUS_NPROCS} ${ABACUS_PATH} | tee output

examples/charge_density/pw_nspin1_Al/INPUT

@@ -0,0 +1,15 @@
+INPUT_PARAMETERS
+#Parameters     (General)
+pseudo_dir                      ../../../tests/PP_ORB
+calculation                     scf
+ntype                           1       
+symmetry                        0
+#Parameters (Methos)
+basis_type                      pw
+ecutwfc                         50
+scf_thr                         1.0e-8  // about iteration
+scf_nmax			100
+smearing_method         	gauss
+smearing_sigma          	0.01
+#Parameters (File)
+out_chg                         1

examples/charge_density/pw_nspin1_Al/KPT

@@ -0,0 +1,4 @@
+K_POINTS
+0
+Gamma
+4 4 4 0 0 0

examples/charge_density/pw_nspin1_Al/STRU

@@ -0,0 +1,21 @@
+#Al BCC
+ATOMIC_SPECIES
+Al 26.982 Al.PD04.PBE.UPF
+
+LATTICE_CONSTANT
+1.889716
+
+LATTICE_VECTORS
+    3.22050     0.00000     0.00000
+    0.00000     3.22050     0.00000
+    0.00000     0.00000     3.22050
+
+ATOMIC_POSITIONS
+Direct
+
+Al
+0.0
+2
+  0.0000000   0.0000000   0.0000000 1 1 1
+  0.5000000   0.5000000   0.5000000 1 1 1
+

examples/charge_density/pw_nspin1_Al/run.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+ABACUS_PATH=$(awk -F "=" '$1=="ABACUS_PATH"{print $2}' ../../SETENV)
+ABACUS_NPROCS=$(awk -F "=" '$1=="ABACUS_NPROCS"{print $2}' ../../SETENV)
+ABACUS_THREADS=$(awk -F "=" '$1=="ABACUS_THREADS"{print $2}' ../../SETENV)
+
+OMP_THREADS_NUM=${ABACUS_THREADS} mpirun -np ${ABACUS_NPROCS} ${ABACUS_PATH} | tee output

examples/charge_density/pw_nspin2_Fe/INPUT

@@ -0,0 +1,21 @@
+INPUT_PARAMETERS
+pseudo_dir      ../../../tests/PP_ORB
+ntype           2
+symmetry      1
+
+calculation   scf
+nspin         2
+ecutwfc       50
+scf_thr       1.0e-8
+scf_nmax      50
+out_chg       1
+
+basis_type    pw
+ks_solver     cg
+
+smearing_method    gaussian
+smearing_sigma       0.07
+
+mixing_type    pulay 
+mixing_beta    0.5
+

examples/charge_density/pw_nspin2_Fe/KPT

@@ -0,0 +1,4 @@
+K_POINTS
+0
+Gamma
+4 4 4  0 0 0

examples/charge_density/pw_nspin2_Fe/STRU

@@ -0,0 +1,25 @@
+ATOMIC_SPECIES
+Fe1 1.000 Fe_ONCV_PBE-1.0.upf
+Fe2 1.000 Fe_ONCV_PBE-1.0.upf
+
+LATTICE_CONSTANT
+6
+
+LATTICE_VECTORS
+1.00 0.00 0.00
+0.00 1.00 0.00
+0.00 0.00 1.00
+ATOMIC_POSITIONS
+Direct
+
+Fe1
+1.0
+1
+0.00 0.00 0.00 1 1 1 
+
+
+Fe2
+-1.0
+1
+0.50 0.50 0.50 1 1 1
+

examples/charge_density/pw_nspin2_Fe/run.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+ABACUS_PATH=$(awk -F "=" '$1=="ABACUS_PATH"{print $2}' ../../SETENV)
+ABACUS_NPROCS=$(awk -F "=" '$1=="ABACUS_NPROCS"{print $2}' ../../SETENV)
+ABACUS_THREADS=$(awk -F "=" '$1=="ABACUS_THREADS"{print $2}' ../../SETENV)
+
+OMP_THREADS_NUM=${ABACUS_THREADS} mpirun -np ${ABACUS_NPROCS} ${ABACUS_PATH} | tee output

examples/charge_density/runall.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+for ii in *
+do
+	if [ -d $ii ];then
+		cd ${ii}
+		echo "RUN: ${ii}"
+		bash run.sh
+		cd ..
+	fi
+done