DFT+U I/O: Rename onsite.dm to dm_onsite.txt and adjust file paths

This commit renames the DFT+U occupation matrix files and adjusts their read/write paths:

1. File name changes:
   - onsite.dm → dm_onsite.txt (output from DFT+U calculations)
   - initial_onsite.dm → dm_onsite_ini.txt (user-provided initial occupation matrix)

2. Path adjustments:
   - dm_onsite.txt: Both written and read from global_out_dir (OUT.prefix)
     - Previously read from global_readin_dir
     - This ensures the file is always in the output directory
   - dm_onsite_ini.txt: Read from global_readin_dir (set via read_file_dir parameter)
     - Previously read from global_out_dir
     - This allows users to place initial files in any directory

3. Code changes:
   - dftu_io.cpp: Updated output filename and error messages
   - dftu.cpp: Updated read paths for both files
   - dftu_lcao.h and module_operator_lcao/dftu_lcao.cpp: Updated comments

4. Documentation updates:
   - read_input_item_exx_dftu.cpp: Updated omc parameter description
   - parameters.yaml: Updated omc parameter description
   - input-main.md: Updated omc parameter description
   - band.md and dos.md: Updated file references
   - tests/17_DS_DFTU/README.md: Updated test documentation
   - tests/17_DS_DFTU/run_scf_nscf.sh: Updated copy logic for dm_onsite.txt

5. Backward compatibility:
   - The new format with labels Atom=, L=, ORBITAL=, spin= was already in the writer
   - This commit updates the reader to parse the new format
   - 1-based indices in output are converted to 0-based when reading

Files modified:
- source/source_lcao/module_dftu/dftu_io.cpp
- source/source_lcao/module_dftu/dftu.cpp
- source/source_lcao/dftu_lcao.h
- source/source_lcao/module_operator_lcao/dftu_lcao.cpp
- source/source_io/module_parameter/read_input_item_exx_dftu.cpp
- docs/parameters.yaml
- docs/advanced/input_files/input-main.md
- docs/advanced/elec_properties/band.md
- docs/advanced/elec_properties/dos.md
- tests/17_DS_DFTU/README.md
- tests/17_DS_DFTU/run_scf_nscf.sh

Author: abacus_fixer

docs/advanced/elec_properties/band.md

@@ -8,7 +8,7 @@ out_chg 1
 ```
 
 With this input parameter, the converged charge density will be output in the files such as `chgs1.cube`, `chgs2.cube`, etc.
-Then, one can use the same `STRU` file, pseudopotential files and atomic orbital files (and the local density matrix file onsite.dm if DFT+U is used) to do a non-self-consistent (NSCF) calculation. In this example, the potential is constructed from the ground-state charge density from the proceeding calculation. Now the INPUT file is like:
+Then, one can use the same `STRU` file, pseudopotential files and atomic orbital files (and the local density matrix file dm_onsite.txt if DFT+U is used) to do a non-self-consistent (NSCF) 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

docs/advanced/elec_properties/dos.md

@@ -10,7 +10,7 @@ out_chg              1
 ```
 
 this will produce the converged charge density, which is contained in the file SPIN1_CHG.cube.
-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:
+Then, use the same `STRU` file, pseudopotential file and atomic orbital file (and the local density matrix file dm_onsite.txt 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

docs/advanced/input_files/input-main.md

@@ -3736,10 +3736,10 @@
 - **Type**: Integer
 - **Description**: The parameter controls the form of occupation matrix control used.
   - 0: No occupation matrix control is performed, and the onsite density matrix will be calculated from wavefunctions in each SCF step.
-  - 1: The first SCF step will use an initial density matrix read from a file named initial_onsite.dm, but for later steps, the onsite density matrix will be updated.
-  - 2: The same onsite density matrix from initial_onsite.dm will be used throughout the entire calculation.
+  - 1: The first SCF step will use an initial density matrix read from a file named dm_onsite_ini.txt, but for later steps, the onsite density matrix will be updated.
+  - 2: The same onsite density matrix from dm_onsite_ini.txt will be used throughout the entire calculation.
 
-  > Note: The easiest way to create initial_onsite.dm is to run a DFT+U calculation, look for a file named onsite.dm in the OUT.prefix directory, and make replacements there. The format of the file is rather straight-forward.
+  > Note: The easiest way to create dm_onsite_ini.txt is to run a DFT+U calculation with out_chg=1, look for a file named dm_onsite.txt in the OUT.prefix directory, copy and rename it to dm_onsite_ini.txt. The file dm_onsite_ini.txt should be placed in the directory specified by read_file_dir. The format of the file is rather straight-forward.
 - **Default**: 0
 
 ### onsite_radius

docs/parameters.yaml

@@ -4387,10 +4387,10 @@ parameters:
     description: |
       The parameter controls the form of occupation matrix control used.
       * 0: No occupation matrix control is performed, and the onsite density matrix will be calculated from wavefunctions in each SCF step.
-      * 1: The first SCF step will use an initial density matrix read from a file named initial_onsite.dm, but for later steps, the onsite density matrix will be updated.
-      * 2: The same onsite density matrix from initial_onsite.dm will be used throughout the entire calculation.
+      * 1: The first SCF step will use an initial density matrix read from a file named dm_onsite_ini.txt, but for later steps, the onsite density matrix will be updated.
+      * 2: The same onsite density matrix from dm_onsite_ini.txt will be used throughout the entire calculation.
 
-      [NOTE] The easiest way to create initial_onsite.dm is to run a DFT+U calculation, look for a file named onsite.dm in the OUT.prefix directory, and make replacements there. The format of the file is rather straight-forward.
+      [NOTE] The easiest way to create dm_onsite_ini.txt is to run a DFT+U calculation with out_chg=1, look for a file named dm_onsite.txt in the OUT.prefix directory, copy and rename it to dm_onsite_ini.txt. The file dm_onsite_ini.txt should be placed in the directory specified by read_file_dir. The format of the file is rather straight-forward.
     default_value: "0"
     unit: ""
     availability: ""

source/source_io/module_parameter/read_input_item_exx_dftu.cpp

@@ -834,10 +834,10 @@ void ReadInput::item_dftu()
         item.type = "Integer";
         item.description = R"(The parameter controls the form of occupation matrix control used.
 * 0: No occupation matrix control is performed, and the onsite density matrix will be calculated from wavefunctions in each SCF step.
-* 1: The first SCF step will use an initial density matrix read from a file named initial_onsite.dm, but for later steps, the onsite density matrix will be updated.
-* 2: The same onsite density matrix from initial_onsite.dm will be used throughout the entire calculation.
+* 1: The first SCF step will use an initial density matrix read from a file named dm_onsite_ini.txt, but for later steps, the onsite density matrix will be updated.
+* 2: The same onsite density matrix from dm_onsite_ini.txt will be used throughout the entire calculation.
 
-[NOTE] The easiest way to create initial_onsite.dm is to run a DFT+U calculation, look for a file named onsite.dm in the OUT.prefix directory, and make replacements there. The format of the file is rather straight-forward.)";
+[NOTE] The easiest way to create dm_onsite_ini.txt is to run a DFT+U calculation with out_chg=1, look for a file named dm_onsite.txt in the OUT.prefix directory, copy and rename it to dm_onsite_ini.txt. The file dm_onsite_ini.txt should be placed in the directory specified by read_file_dir. The format of the file is rather straight-forward.)";
         item.default_value = "0";
         item.unit = "";
         item.availability = "";

source/source_lcao/dftu_lcao.h

@@ -43,14 +43,14 @@ void init_dftu_lcao(const int istep,
  * @param iter Current SCF iteration
  * @param conv_esolver Whether ESolver has converged
  * @param dft_plus_u DFT+U mode (0=disabled, 1=old, 2=new)
- * @param out_chg Whether to output onsite.dm
+ * @param out_chg Whether to output dm_onsite.txt
  * @param dftu DFT+U object
  * @param ucell Unit cell
  * @param dm_vec Density matrix vector
  * @param kv K-vectors
  * @param mixing_beta Mixing beta parameter
  * @param hamilt_lcao Hamiltonian LCAO object
- * @param global_out_dir Output directory for onsite.dm
+ * @param global_out_dir Output directory for dm_onsite.txt
  * @param nspin Number of spin channels (1, 2, or 4)
  * @param npol Number of polarizations
  */

source/source_lcao/module_dftu/dftu.cpp

@@ -237,7 +237,7 @@ void Plus_U::init(UnitCell& cell, // unitcell class
     if (omc != 0)
     {
         std::stringstream sst;
-        sst << "initial_onsite.dm";
+        sst << PARAM.globalv.global_readin_dir << "dm_onsite_ini.txt";
         this->read_occup_m(cell, sst.str(), PARAM.inp.init_chg, PARAM.inp.nspin, PARAM.globalv.npol);
 #ifdef __MPI
         this->local_occup_bcast(cell, PARAM.inp.nspin, PARAM.globalv.npol);
@@ -251,7 +251,7 @@ void Plus_U::init(UnitCell& cell, // unitcell class
         if (PARAM.inp.init_chg == "file")
         {
             std::stringstream sst;
-            sst << PARAM.globalv.global_readin_dir << "onsite.dm";
+            sst << PARAM.globalv.global_out_dir << "dm_onsite.txt";
             this->read_occup_m(cell, sst.str(), PARAM.inp.init_chg, PARAM.inp.nspin, PARAM.globalv.npol);
 #ifdef __MPI
             this->local_occup_bcast(cell, PARAM.inp.nspin, PARAM.globalv.npol);

source/source_lcao/module_dftu/dftu_io.cpp

@@ -59,14 +59,14 @@ void Plus_U::output(const UnitCell& ucell,
     GlobalV::ofs_running << " Local Occupation Matrices for each atom" << std::endl;
     this->write_occup_m(ucell, GlobalV::ofs_running, true, nspin, npol);
 
-    // Write onsite.dm
+    // Write dm_onsite.txt
     if (out_chg && GlobalV::MY_RANK == 0)
     {
         std::ofstream ofdftu;
-        ofdftu.open(global_out_dir + "onsite.dm");
+        ofdftu.open(global_out_dir + "dm_onsite.txt");
         if (!ofdftu)
         {
-            ModuleBase::WARNING_QUIT("Plus_U::output", "Can't create file onsite.dm");
+            ModuleBase::WARNING_QUIT("Plus_U::output", "Can't create file dm_onsite.txt");
         }
         this->write_occup_m(ucell, ofdftu, false, nspin, npol);
         ofdftu.close();
@@ -257,16 +257,16 @@ void Plus_U::read_occup_m(const UnitCell& ucell,
     {
         if (omc > 0)
         {
-            ModuleBase::WARNING_QUIT("Plus_U::read_occup_m", "Can not find the file initial_onsite.dm. Please check your initial_onsite.dm");
+            ModuleBase::WARNING_QUIT("Plus_U::read_occup_m", "Can not find the file dm_onsite_ini.txt. Please check your dm_onsite_ini.txt");
         }
         else
         {
             if (init_chg == "file")
             {
-                ModuleBase::WARNING_QUIT("Plus_U::read_occup_m", "Can not find the file onsite.dm. Please do scf calculation first");
+                ModuleBase::WARNING_QUIT("Plus_U::read_occup_m", "Can not find the file dm_onsite.txt. Please do scf calculation first");
             }
         }
-        ModuleBase::WARNING_QUIT("Plus_U::read_occup_m", "Can not open onsite.dm file");
+        ModuleBase::WARNING_QUIT("Plus_U::read_occup_m", "Can not open dm_onsite.txt file");
     }
 
     ifdftu.clear();

source/source_lcao/module_operator_lcao/dftu_lcao.cpp

@@ -190,7 +190,7 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::cal_nlm_all(const Parallel_Orbi
  *     * For nspin=1: occ is scaled by 0.5 (since only one spin channel computed)
  *   - Subsequent iterations: locale is computed fresh each iteration from updated DMR
  * 
- * Case 2: Locale IS initialized (is_locale_initialized, i.e., read from onsite.dm file)
+ * Case 2: Locale IS initialized (is_locale_initialized, i.e., read from dm_onsite.txt file)
  *   - First electronic iteration: uses pre-read locale directly without DMR calculation
  *     * Skips DMR-based occ calculation entirely
  *     * Reads locale from stored data via get_locale()
@@ -334,8 +334,8 @@ void hamilt::DFTU<hamilt::OperatorLCAO<TK, TR>>::contributeHR()
         // BRANCH 2: Locale IS initialized (use pre-read data)
         // ============================================================
         // This branch is taken when:
-        // - is_locale_initialized() == true (locale read from onsite.dm file)
-        // - OR omc != 0 (occupation matrix control with initial_onsite.dm)
+        // - is_locale_initialized() == true (locale read from dm_onsite.txt file)
+        // - OR omc != 0 (occupation matrix control with dm_onsite_ini.txt)
         // Typical scenario: first SCF iteration with file input, or restart calculation
         else
         {

tests/17_DS_DFTU/README.md

@@ -175,9 +175,9 @@ The following test cases are disabled in `CASES_CPU.txt` (commented out with `#`
 
 - 09 (PW DFT+U + noncollinear): Only supports **2-process MPI** execution, `result.ref` reference files provided
 - The following test cases set `kpar=2` in INPUT and require at least **2 MPI processes** to run: 11, 12, 14, 15, 16, 18, 19, 21, 37, 39, 41, 43, 45
-- 62 (LCAO_DFTU_NSCF_Band_XY): Single-thread and multi-thread results are inconsistent; investigation shows HR, HK, and SK are consistent across threads, but eigenvalues from genelpa differ; switching to scalapack_gvx produces consistent results across thread counts. Note: this test is named "NSCF" but actually runs with `calculation = scf` (`scf_nmax = 1`), using pre-shipped charge density and onsite.dm files as initial guess
+- 62 (LCAO_DFTU_NSCF_Band_XY): Single-thread and multi-thread results are inconsistent; investigation shows HR, HK, and SK are consistent across threads, but eigenvalues from genelpa differ; switching to scalapack_gvx produces consistent results across thread counts. Note: this test is named "NSCF" but actually runs with `calculation = scf` (`scf_nmax = 1`), using pre-shipped charge density and dm_onsite.txt files as initial guess
 - All NSCF tests (55, 60, 61, 62, 63, 64) have been **converted to SCF+NSCF workflow**:
-  - Pre-converged `autotest-CHARGE-DENSITY.restart` and `onsite.dm` files have been removed
+  - Pre-converged `autotest-CHARGE-DENSITY.restart` and `dm_onsite.txt` files have been removed
   - Each test directory contains a `scf/` subdirectory with SCF input files
   - Run with: `bash ../run_scf_nscf.sh <abacus_path> [mpi_np]`
   - These tests are **disabled in CI** (commented out in CASES_CPU.txt)