Fix TDOS/PDOS energy grid misalignment, unify DOS output file naming, and improve plot-tools TDOS

docs/advanced/elec_properties/dos.md

@@ -68,7 +68,9 @@ Gamma
 8 8 8 0 0 0
 ```
 
-Run the program, and you will see a file named doss1g1_nao.txt in the output directory. The columns are: energy(eV), dos (number of states in each energy bin), dos_int (integrated DOS), dos_smear(1/eV) (Gaussian-smeared DOS), dos_smear_int (integrated smeared DOS). Plot the file with graphing software, and you'll get the DOS.
+Run the program, and you will see a file named doss1g1.txt in the output directory. The columns are: energy(eV), dos (number of states in each energy bin), dos_int (integrated DOS), dos_smear(1/eV) (Gaussian-smeared DOS), dos_smear_int (integrated smeared DOS). Plot the file with graphing software, and you'll get the DOS.
+
+The `dos` column is a raw per-bin histogram, while `dos_smear` is the physically meaningful density of states in 1/eV. The `abacus-plot` tool plots `dos_smear` by default; set `"smearing": false` in its config.json to plot the raw histogram instead, or apply your own smearing to the raw column with `abacus_plot.utils.gaussian_smearing`. For nspin=2, two files (doss1*/doss2*) are written, one per spin channel; the tool pairs them automatically whether you pass either file, a directory, or a list of both files. For nspin=4, a single spinor-summed file is written.
 
 ```
 #   energy(eV)           dos        dos_int  dos_smear(1/eV)  dos_smear_int
@@ -80,7 +82,7 @@ Run the program, and you will see a file named doss1g1_nao.txt in the output dir
 
 ## PDOS
 
-Along with the DOS files, we also produce the projected density of states (PDOS) in files named pdoss{spin}g{geom}_{basis}.txt (e.g., pdoss1g1_nao.txt).
+Along with the DOS files, we also produce the projected density of states (PDOS) in files named pdoss{spin}g{geom}.txt (e.g., pdoss1g1.txt).
 
 The PDOS file uses a plain-text format. Each row corresponds to one energy point and one atom. Columns: energy(eV), atom (1-based), species, then pdos values ordered as s(1), p(3), d(5), f(7), etc. Zeta components are summed, and values below 1e-6 are zeroed out.
 

docs/advanced/output_files/output-specification.md

@@ -86,7 +86,7 @@ All output file naming conventions can be found in the online documentation (wit
 | `elfs1g1.cube` | ELF, spin 1, geometry step 1 (nspin=2) |
 | `elftotg1.cube` | ELF, total, geometry step 1 (nspin=2) |
 | `eig_occ.txt` | Eigenvalues and occupations |
-| `doss1g1_nao.txt` | DOS, spin 1, geometry step 1, NAO basis |
+| `doss1g1.txt` | DOS, spin 1, geometry step 1 |
 | `wf_pw.dat` | Wavefunction, plane wave basis |
 | `sr.csr` | Overlap matrix in real space (no spin index) |
 
@@ -95,7 +95,7 @@ All output file naming conventions can be found in the online documentation (wit
 | File Name | Description |
 |-----------|-------------|
 | `running_scf.log` | SCF iteration log |
-| `dos.txt` | Density of states |
+| `doss1g1.txt` | Density of states |
 | `eig_occ.txt` | Eigenvalues and occupations |
 | `mulliken.txt` | Mulliken population analysis |
 | `band.txt` | Band structure |
@@ -308,7 +308,7 @@ void OutputMyData::write(const std::string& filename, int precision)
 | File | Location | Strengths |
 |------|----------|-----------|
 | `chgs1.cube` | `tests/03_NAO_multik/scf_out_chg_tau/OUT.autotest/` | Short name, spin index convention |
-| `dos.txt` | `tests/03_NAO_multik/scf_out_dos_spin2/OUT.autotest/` | Clear header with metadata |
+| `doss1g1.txt` | `tests/03_NAO_multik/scf_out_dos_spin2/OUT.autotest/` | Clear header with metadata |
 | `eig_occ.txt` | Same as above | Clear block structure for spin/k-point |
 | `mulliken.txt` | `tests/03_NAO_multik/scf_out_mul/OUT.autotest/` | Clear atom separators |
 

examples/13_dos/01_pw_Al/run.sh

@@ -18,7 +18,7 @@ if [[ ! -f scf.output ]] ||
    [[ ! -f nscf.output ]] ||
    [[ ! -f OUT.ABACUS/running_scf.log ]] ||
    [[ ! -f OUT.ABACUS/running_nscf.log ]] ||
-   [[ ! -f OUT.ABACUS/dos.txt ]] ||
+   [[ ! -f OUT.ABACUS/doss1g1.txt ]] ||
    [[ ! -f OUT.ABACUS/chg.cube ]] ||
    [[ ! ( "$(tail -1 OUT.ABACUS/running_scf.log)" == " Total  Time  :"* ) ]] ||
    [[ ! ( "$(tail -1 OUT.ABACUS/running_nscf.log)" == " Total  Time  :"* ) ]]

examples/13_dos/02_lcao_Si2/run.sh

@@ -18,7 +18,7 @@ if [[ ! -f scf.output ]] ||
    [[ ! -f nscf.output ]] ||
    [[ ! -f OUT.ABACUS/running_scf.log ]] ||
    [[ ! -f OUT.ABACUS/running_nscf.log ]] ||
-   [[ ! -f OUT.ABACUS/doss1g1_nao.txt ]] ||
+   [[ ! -f OUT.ABACUS/doss1g1.txt ]] ||
    [[ ! -f OUT.ABACUS/chg.cube ]] ||
    [[ ! ( "$(tail -1 OUT.ABACUS/running_scf.log)" == " Total  Time  :"* ) ]] ||
    [[ ! ( "$(tail -1 OUT.ABACUS/running_nscf.log)" == " Total  Time  :"* ) ]]

examples/13_dos/README

@@ -16,7 +16,7 @@ It requires two steps of calculation:
    - set 'out_dos' to '1'
    - set 'pw_diag_thr' to a suitable value when basis_type is 'pw'
 
-Finish! Then you can see the DOS file in OUT.ABACUS (dos.txt for PW basis, doss1g{geom}_nao.txt for LCAO basis). The columns are: energy(eV), dos(1/eV), dos_int (integrated DOS), dos_smear(1/eV), dos_smear_int (integrated smeared DOS). Plot it!
+Finish! Then you can see the DOS file in OUT.ABACUS (doss1g{geom}.txt for both PW and LCAO basis; for nspin=2 there are doss1*/doss2* files, one per spin channel). The columns are: energy(eV), dos (number of states in each energy bin), dos_int (integrated DOS), dos_smear(1/eV), dos_smear_int (integrated smeared DOS). Plot it!
 
 Note:
 1)If the "out_dos" is used, the DOS file will appear in the directory.

source/source_io/module_ctrl/ctrl_output_pw.cpp

@@ -116,7 +116,9 @@ void ModuleIO::ctrl_scf_pw(const int istep,
     {
         bool out_dos_tmp = false;
 
-        int istep_in = -1;
+        // always tag the DOS file with the geometry index, so that PW and
+        // LCAO share the same doss{spin}g{geom}.txt naming
+        int istep_in = istep;
 
         // default value of out_freq_ion is 0
         if (inp.out_freq_ion == 0)

source/source_io/module_dos/cal_dos.cpp

@@ -210,7 +210,9 @@ bool ModuleIO::cal_dos(const int& is,  // index for spin
         if (GlobalV::MY_RANK == 0)
         {
             dos.push_back(nstates);
-            ene.push_back(curr_energy);
+            // label the bin [e_old, curr_energy) with its left edge so that the
+            // TDOS grid (emin + n*de_ev) matches the PDOS grid point-by-point
+            ene.push_back(e_old);
             sum_elec.push_back(sum);
         }
     }

source/source_io/module_dos/cal_pdos_gamma.cpp

@@ -148,7 +148,7 @@ void ModuleIO::cal_pdos(
     if (GlobalV::MY_RANK == 0)
     {
         write_pdos_text(ucell, pdos.data(), nspin, nlocal, npoints,
-                        emin, dos_edelta_ev, global_out_dir, "nao", istep);
+                        emin, dos_edelta_ev, global_out_dir, istep);
         ModuleIO::write_orb_info(&ucell);
     }
 }

source/source_io/module_dos/cal_pdos_multik.cpp

@@ -188,7 +188,7 @@ void ModuleIO::cal_pdos(
     if (GlobalV::MY_RANK == 0)
     {
         write_pdos_text(ucell, pdos.data(), nspin, nlocal, npoints,
-                        emin, dos_edelta_ev, global_out_dir, "nao", istep);
+                        emin, dos_edelta_ev, global_out_dir, istep);
         ModuleIO::write_orb_info(&ucell);
     }
 }

source/source_io/module_dos/unittests/test_cal_dos.cpp

@@ -63,8 +63,8 @@ TEST_F(DosTest,Dos)
 		ifs.open(dosp.fa.c_str());
 		std::string str((std::istreambuf_iterator<char>(ifs)),std::istreambuf_iterator<char>());
 		EXPECT_THAT(str, testing::HasSubstr("4801 # number of points"));
-	EXPECT_THAT(str, testing::HasSubstr("   -4.995000     0.500000     0.500000"));
-	EXPECT_THAT(str, testing::HasSubstr("   18.000000     0.000000     8.000000"));
+	EXPECT_THAT(str, testing::HasSubstr("   -5.000000     0.500000     0.500000"));
+	EXPECT_THAT(str, testing::HasSubstr("   17.995000     0.000000     8.000000"));
 	ifs.close();
 	remove("doss1_pw.txt");
 #ifdef __MPI

source/source_io/module_dos/unittests/test_write_dos_pw.cpp

@@ -76,7 +76,7 @@ TEST_F(DosPWTest,Dos1)
 			dosp.wg,
 			*kv,
 			dosp.nbands,
-            -1, // istep_in
+            0, // istep_in
 			fermi_energy,
 			dosp.de_ev,
 			dos_scale,
@@ -100,13 +100,13 @@ TEST_F(DosPWTest,Dos1)
 	{
 #endif
 		std::ifstream ifs;
-		ifs.open("dos.txt");
+		ifs.open("doss1g1.txt");
 		std::string str((std::istreambuf_iterator<char>(ifs)),std::istreambuf_iterator<char>());
 		EXPECT_THAT(str, testing::HasSubstr("4801 # number of points"));
-		EXPECT_THAT(str, testing::HasSubstr("   -4.995000     0.500000     0.500000"));
-		EXPECT_THAT(str, testing::HasSubstr("   18.000000     0.000000     8.000000"));
+		EXPECT_THAT(str, testing::HasSubstr("   -5.000000     0.500000     0.500000"));
+		EXPECT_THAT(str, testing::HasSubstr("   17.995000     0.000000     8.000000"));
 		ifs.close();
-		remove("dos.txt");
+		remove("doss1g1.txt");
 #ifdef __MPI
 	}
 #endif
@@ -154,7 +154,7 @@ TEST_F(DosPWTest,Dos2)
 			dosp.wg,
 			*kv,
 			dosp.nbands,
-			-1, // istep_in
+			0, // istep_in
             fermi_energy,
 			dosp.de_ev,
 			dos_scale,
@@ -178,13 +178,13 @@ TEST_F(DosPWTest,Dos2)
 	{
 #endif
 		std::ifstream ifs;
-		ifs.open("dos.txt");
+		ifs.open("doss1g1.txt");
 		std::string str1((std::istreambuf_iterator<char>(ifs)),std::istreambuf_iterator<char>());
 		EXPECT_THAT(str1, testing::HasSubstr("2526 # number of points"));
-		EXPECT_THAT(str1, testing::HasSubstr("   -4.997500     0.500000     0.500000"));
-		EXPECT_THAT(str1, testing::HasSubstr("    7.567500     0.000000     8.000000"));
+		EXPECT_THAT(str1, testing::HasSubstr("   -5.002500     0.500000     0.500000"));
+		EXPECT_THAT(str1, testing::HasSubstr("    7.562500     0.000000     8.000000"));
 		ifs.close();
-		remove("dos.txt");
+		remove("doss1g1.txt");
 #ifdef __MPI
 	}
 #endif

source/source_io/module_dos/unittests/test_write_pdos_text.cpp

@@ -69,7 +69,7 @@ class WritePdosTextTest : public ::testing::Test
     }
 };
 
-// Spin-unpolarized: writes pdoss1_<basis>.txt with s and 3 p columns.
+// Spin-unpolarized: writes pdoss1.txt with s and 3 p columns.
 TEST_F(WritePdosTextTest, BasicOutput)
 {
     GlobalV::ofs_running.open("test_write_pdos_text.log");
@@ -80,7 +80,6 @@ TEST_F(WritePdosTextTest, BasicOutput)
     const double emin = -1.0;
     const double dos_edelta_ev = 0.5;
     const std::string out_dir = "./";
-    const std::string basis = "lcao";
     const int istep = -1;
 
     // pdos matrix: nlocal x npoints; value = orbital * 100 + point
@@ -94,9 +93,9 @@ TEST_F(WritePdosTextTest, BasicOutput)
     }
 
     ModuleIO::write_pdos_text(*ucell, &pdos, nspin, nlocal, npoints,
-                              emin, dos_edelta_ev, out_dir, basis, istep);
+                              emin, dos_edelta_ev, out_dir, istep);
 
-    const std::string str = read_file("./pdoss1_lcao.txt");
+    const std::string str = read_file("./pdoss1.txt");
 
     // header lines
     EXPECT_THAT(str, testing::HasSubstr("# npoints: 5"));
@@ -109,7 +108,7 @@ TEST_F(WritePdosTextTest, BasicOutput)
     // last data row: energy=1.0, n=4 -> s=4, p=104,204,304
     EXPECT_THAT(str, testing::HasSubstr("    1.000000    1    Si  4.000000  104.000000  204.000000  304.000000"));
 
-    remove("./pdoss1_lcao.txt");
+    remove("./pdoss1.txt");
     GlobalV::ofs_running.close();
     remove("test_write_pdos_text.log");
 }
@@ -128,12 +127,12 @@ TEST_F(WritePdosTextTest, IstepFileName)
     pdos.zero_out();
 
     ModuleIO::write_pdos_text(*ucell, &pdos, nspin, nlocal, npoints,
-                              emin, dos_edelta_ev, "./", "lcao", 2);
+                              emin, dos_edelta_ev, "./", 2);
 
-    const std::string str = read_file("./pdoss1g3_lcao.txt");
+    const std::string str = read_file("./pdoss1g3.txt");
     EXPECT_THAT(str, testing::HasSubstr("# istep: 3"));
 
-    remove("./pdoss1g3_lcao.txt");
+    remove("./pdoss1g3.txt");
     GlobalV::ofs_running.close();
     remove("test_write_pdos_text.log");
 }
@@ -164,17 +163,17 @@ TEST_F(WritePdosTextTest, SpinPolarized)
     }
 
     ModuleIO::write_pdos_text(*ucell, pdos_arr, nspin, nlocal, npoints,
-                              emin, dos_edelta_ev, "./", "lcao", -1);
+                              emin, dos_edelta_ev, "./", -1);
 
-    const std::string s1 = read_file("./pdoss1_lcao.txt");
-    const std::string s2 = read_file("./pdoss2_lcao.txt");
+    const std::string s1 = read_file("./pdoss1.txt");
+    const std::string s2 = read_file("./pdoss2.txt");
     // spin 1: s orbital w=0, n=0 -> 1000
     EXPECT_THAT(s1, testing::HasSubstr("1000.000000"));
     // spin 2: s orbital w=0, n=0 -> 2000
     EXPECT_THAT(s2, testing::HasSubstr("2000.000000"));
 
-    remove("./pdoss1_lcao.txt");
-    remove("./pdoss2_lcao.txt");
+    remove("./pdoss1.txt");
+    remove("./pdoss2.txt");
     GlobalV::ofs_running.close();
     remove("test_write_pdos_text.log");
 }

source/source_io/module_dos/write_dos_lcao.cpp

@@ -67,7 +67,7 @@ void write_dos_lcao(
             ss << "g" << istep+1;
         }
 
-        ss << "_nao.txt";
+        ss << ".txt";
 
         ModuleIO::cal_dos(is,
                 ss.str(),

source/source_io/module_dos/write_dos_pw.cpp

@@ -50,16 +50,13 @@ void ModuleIO::write_dos_pw(
     for (int is = 0; is < nspin0; ++is)
     {
         // DOS_ispin contains not smoothed dos
+        // unified naming with the LCAO DOS/PDOS output: doss{spin}g{geom}.txt
         std::stringstream ss;
-        ss << global_out_dir << "dos";
+        ss << global_out_dir << "doss" << is + 1;
 
-        if(nspin0==2)
+        if(istep_in>=0)
         {
-            ss << "s" << is + 1;
-        }
-        else
-        {
-            // do nothing;
+            ss << "g" << istep_in+1;
         }
 
         ss << ".txt";

source/source_io/module_dos/write_pdos_text.cpp

@@ -17,7 +17,6 @@ void ModuleIO::write_pdos_text(
         const double& emin,
         const double& dos_edelta_ev,
         const std::string& out_dir,
-        const std::string& basis,
         const int istep)
 {
     ModuleBase::TITLE("ModuleIO", "write_pdos_text");
@@ -33,7 +32,7 @@ void ModuleIO::write_pdos_text(
         {
             ss << "g" << istep + 1;
         }
-        ss << "_" << basis << ".txt";
+        ss << ".txt";
 
         std::ofstream ofs(ss.str().c_str());
 

source/source_io/module_dos/write_pdos_text.h

@@ -8,7 +8,7 @@ namespace ModuleIO
 {
 
 /// Write PDOS in plain text long-table format.
-/// File name: pdoss{spin}g{geom}_{basis}.txt
+/// File name: pdoss{spin}g{geom}.txt
 /// Columns: energy(eV)  atom  species  l  z  m  pdos(1/eV)
 /// For nspin=4, the two spinor components are summed.
 void write_pdos_text(
@@ -20,7 +20,6 @@ void write_pdos_text(
         const double& emin,
         const double& dos_edelta_ev,
         const std::string& out_dir,
-        const std::string& basis,
         const int istep);
 
 }

source/source_io/module_parameter/read_inp_out.cpp

@@ -341,7 +341,7 @@ Also controled by out_freq_ion and out_app_flag.
         item.description = R"(Whether to output the density of states (DOS) and projected density of states (PDOS). For more information, refer to the dos.md.
 * 0: no output
 * 1: output the density of states (DOS) and projected density of states (PDOS, LCAO only)
- * nspin=1 or 4: doss1g{geom}_{basis}.txt and pdoss1g{geom}_{basis}.txt, where geom is the geometry index when cell changes or ions move while basis is either pw or nao.
+ * nspin=1 or 4: doss1g{geom}.txt and pdoss1g{geom}.txt (PDOS is LCAO only), where geom is the geometry index when cell changes or ions move. PW and LCAO calculations use the same naming.
  * nspin=2: doss1/doss2 and pdoss1/pdoss2 files for two spin channels.
 Note: values 2 and 3 are no longer supported. Setting out_dos to 2 or 3 will raise an error.)";
         item.default_value = "0";

tests/performance/catch_properties.sh

@@ -89,10 +89,10 @@ fi
 
 #echo $total_charge
 if ! test -z "$has_dos"  && [  $has_dos -eq 1 ]; then
-	total_dos=`cat OUT.autotest/doss1g1_nao.txt | awk 'END {print}' | awk '{print $3}'`
+	total_dos=`cat OUT.autotest/doss1g1.txt | awk 'END {print}' | awk '{print $3}'`
 	echo "totaldosref $total_dos" >> $1
 fi
-#	smearing_dos=`sum_file OUT.autotest/doss1g1_nao.txt`
+#	smearing_dos=`sum_file OUT.autotest/doss1g1.txt`
 #	echo "totaldossmearing $smearing_dos" >> $1
 
 

tools/02_postprocessing/plot-tools/README.md

@@ -118,11 +118,12 @@ First, prepare a file named 'config.json' in json format:
 If you only want to plot total DOS, you can modify `pdosfile` to `tdosfile` and do not set `species` and `pdosfig`.
 | Property | Type | Note |
 | :------------: | :-------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
-| _tdosfile_ | `str` | Total DOS data file output from ABACUS |
-| _pdosfile_ | `str` | Directory or path prefix containing the text PDOS files `pdoss1_*` (and `pdoss2_*` for spin-polarized runs) output from ABACUS |
+| _tdosfile_ | `str` or `List[str]` | Total DOS data file(s) output from ABACUS. For `nspin=2`, pass one spin-channel file (`doss1*` or `doss2*`; the counterpart is paired automatically), a directory containing them, or a list of both files. For `nspin=4`, ABACUS writes a single spinor-summed file |
+| _pdosfile_ | `str` | Directory or path prefix containing the text PDOS files `pdoss1*` (and `pdoss2*` for spin-polarized runs), e.g. `pdoss1g1.txt`, output from ABACUS |
 | _efermi_ | `float` | Fermi level in eV |
 | _energy_range_ | `list` | Range of energy in eV |
 | _shift_ | `bool` | If set `'true'`, it will evaluate band gap. Default: `'false'` |
+| _smearing_ | `bool` | If `'true'` (default), plot the Gaussian-smeared DOS column (`dos_smear`, unit 1/eV); if `'false'`, plot the raw per-bin histogram column. The raw column is also accessible as `TDOS(...).dos` for custom smearing, e.g. with `abacus_plot.utils.gaussian_smearing`. This switch also selects the data used by the `shift=true` band-gap estimate; with the smeared column, Gaussian tails can narrow small apparent gaps, so the reported gap is a threshold-based estimate that depends on `dos_sigma` and `prec` |
 | _index_ | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[str, List[int]]]]` | Extract PDOS of each atom e.g. [index_0, index_1...] or {index*0:[l_0, l_1, ...], ...}, [index_0:{l_0:[m_0, m_1, ...], ...}, ...] |
 | \_atom_index* | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[str, List[int]]]]` | Extract PDOS of each atom with same atom*index e.g. [atom_index_0, atom_index_1...] or {atom_index_0:[l_0, l_1, ...], ...}, [atom_index_0:{l_0:[m_0, m_1, ...], ...}, ...] |
 | \_species* | `List[str]` or `Dict[str, List[int]]` or `Dict[str, Dict[str, List[int]]]]` | Extract PDOS of each atom with same species e.g. [elem_0, elem_1...] or {elem*0:[l_0, l_1, ...], ...}, [elem_0:{l_0:[m_0, m_1, ...], ...}, ...] |