Docs: add the docs and example for density matrix (#1316)

* Docs: add the docs and example for density matrix

* delete output

docs/advanced/elec_properties/density_matrix.md

@@ -1 +1,40 @@
-# Extracting Density Matrices
+# Extracting Density Matrices
+
+ABACUS can output the density matrix by adding the keyword "[out_dm](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-dm)" in INPUT file:
+```
+out_dm             1
+```
+After finishing the calculation, the information of the density matrix is stroed in files `OUT.${suffix}/SPIN${spin}_DM`, which looks like:
+```
+test
+ 5.39761
+ 0.5 0.5 0
+ 0.5 0 0.5
+ 0 0.5 0.5
+ Si
+ 2
+Direct
+ 0 0 0
+ 0.25 0.25 0.25
+
+ 1
+ 0.570336288801065 (fermi energy)
+  26 26
+
+ 3.904e-01 1.114e-02 2.050e-14 1.655e-13 1.517e-13 -7.492e-15 -1.729e-14 5.915e-15
+ -9.099e-15 2.744e-14 3.146e-14 6.631e-15 2.594e-15 3.904e-01 1.114e-02 -7.395e-15
+ ...
+ ```
+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 dimension of the density matrix, and the rest lines are the value of each matrix element.
+
+The examples can be found in [examples/density_matrix](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/density_matrix)
+
+- Note: now this function is valid only for LCAO gamma only calcualtion.

examples/density_matrix/README

@@ -0,0 +1,11 @@
+/*******************************************************************************/
+/
+/ These are the examples of ABACUS program.
+/
+/*******************************************************************************/
+
+These examples show how to output the density matrix of system.
+One only need to set the keyword 'out_dm' to '1' in the INPUT file.
+After the calculation, one can find file SPIN${spin}_DM in OUT.${suffix}
+
+Notice: now this function is valid only for LCAO basis with gamma only method.

examples/density_matrix/lcao_nspin1_Si2/INPUT

@@ -0,0 +1,17 @@
+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)
+gamma_only			1
+out_dm                         1

examples/density_matrix/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/density_matrix/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/density_matrix/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