Reorganize the tools folder (deepmodeling#7470)

* Refactor: Restructure tools/ directory for clarity and fix include analysis script

This commit consolidates three previous commits (#1, #2, deepmodeling#3) into a single
comprehensive refactor of the tools/ directory, addressing both
organizational structure and a path-related bug in the code analysis script.

1. tools/ directory reorganization
   - Group all numerical atomic orbital (NAO) generation tools under
     01_NAO_generation/, including:
       * SIAB/ (Simulated Annealing method in C++)
       * pytorch/ and pytorch_dpsi/ (PyTorch gradient methods)
       * pytorch_gradient_source/ (original PyTorch implementation)
       * lcao_bash/ and abfs_bash/ (bash-based orbital generators)
       * qo/ (quasiatomic orbital generation)
       * Generate_Orbital_AllInOne.sh (main entry script)
       * examples/ (example input files)
   - Move all post-processing and visualization tools under
     02_postprocessing/:
       * rt-tddft-tools/, stm/, average_pot/, selective_dynamics/, plot-tools/
   - Place source code analysis tools under 03_code_analysis/
   - Rename windows/ to 04_windows_installation/ for consistency
   - Use numerical prefixes (01_, 02_, 03_, 04_) to define a clear order
   - Use git mv to preserve file history throughout the refactor

2. New tools/README.md
   - Add a comprehensive README with directory tree, quick start guide
     and tool descriptions

3. Fix generate_include_analysis.py path bug
   - The script computed repo_root using os.path.dirname(script_dir),
     assuming the script lived in tools/. After moving to
     tools/03_code_analysis/, this resolved to tools/ instead of the
     repository root, causing os.walk to find no source files.
   - Update to os.path.dirname(os.path.dirname(script_dir)) to correctly
     resolve the repository root from the new script location.

Combined previous commits:
  6e3b7954c add code analysis python file
  546d7cd76 update tools
  92094b81d update

* Fix: Update path references in docs and source code after tools/ directory restructuring

After the tools/ directory reorganization, several path references in documentation
and source code were still pointing to the old directory structure. This commit
updates all hardcoded paths to match the new organization:

1. docs/advanced/windows_installer.md
   - tools/windows/ → tools/04_windows_installation/ (3 occurrences)

2. docs/advanced/input_files/input-main.md
   - tools/average_pot/aveElecStatPot.py → tools/02_postprocessing/average_pot/aveElecStatPot.py

3. docs/parameters.yaml
   - tools/average_pot/aveElecStatPot.py → tools/02_postprocessing/average_pot/aveElecStatPot.py

4. source/source_io/module_qo/to_qo_kernel.cpp
   - /tools/qo/postprocess.py → /tools/01_NAO_generation/qo/postprocess.py

5. source/source_basis/module_nao/atomic_radials.cpp
   - Update SIAB/PyTorchGradient paths to 01_NAO_generation/pytorch and 01_NAO_generation/SIAB

6. source/source_io/module_parameter/read_input_item_output.cpp
   - tools/average_pot/aveElecStatPot.py → tools/02_postprocessing/average_pot/aveElecStatPot.py

* add a threshold in 17_DS_DFTU/01_LCAO_SPIN_S2_Z

---------

Co-authored-by: abacus_fixer <mohanchen@pku.eud.cn>
Co-authored-by: Xiaoyang Zhang <tsfxwbbzxy@163.com>

Author: 3 people

docs/advanced/input_files/input-main.md

@@ -2867,7 +2867,7 @@ parameters:
        * nspin = 1: pots1.cube;
        * nspin = 2: pots1.cube and pots2.cube;
        * nspin = 4: pots1.cube, pots2.cube, pots3.cube, and pots4.cube
-      * 2: Output the electrostatic potential on real space grids into OUT.{suffix}/pot_es.cube. The Python script named tools/average_pot/aveElecStatPot.py can be used to calculate the average electrostatic potential along the z-axis and outputs it into ElecStaticPot_AVE. Please note that the total local potential refers to the local component of the self-consistent potential, excluding the non-local pseudopotential. The distinction between the local potential and the electrostatic potential is as follows: local potential = electrostatic potential + XC potential.
+      * 2: Output the electrostatic potential on real space grids into OUT.{suffix}/pot_es.cube. The Python script named tools/02_postprocessing/average_pot/aveElecStatPot.py can be used to calculate the average electrostatic potential along the z-axis and outputs it into ElecStaticPot_AVE. Please note that the total local potential refers to the local component of the self-consistent potential, excluding the non-local pseudopotential. The distinction between the local potential and the electrostatic potential is as follows: local potential = electrostatic potential + XC potential.
       * 3: Apart from 1, also output the total local potential of the initial charge density. The files are named as:
        * nspin = 1: pots1_ini.cube;
        * nspin = 2: pots1_ini.cube and pots2_ini.cube;

docs/advanced/windows_installer.md

@@ -114,8 +114,8 @@ void AtomicRadials::read_abacus_orb(std::ifstream& ifs, std::ofstream* ptr_log,
      * Read the orbital file.
      *
      * For orbital file format, see
-     * (new) abacus-develop/tools/SIAB/PyTorchGradient/source/IO/print_orbital.py
-     * (old) abacus-develop/tools/SIAB/SimulatedAnnealing/source/src_spillage/Plot_Psi.cpp
+     * (new) abacus-develop/tools/01_NAO_generation/pytorch/IO/print_orbital.py
+     * (old) abacus-develop/tools/01_NAO_generation/SIAB/src_spillage/Plot_Psi.cpp
      *                                                                                  */
     int ngrid = 0; // number of grid points
     double dr = 0; // grid spacing
@@ -284,8 +284,8 @@ void AtomicRadials::read_abacus_orb(std::ifstream& ifs, std::ofstream* ptr_log,
 //      * Read the orbital file.
 //      *
 //      * For orbital file format, see
-//      * (new) abacus-develop/tools/SIAB/PyTorchGradient/source/IO/print_orbital.py
-//      * (old) abacus-develop/tools/SIAB/SimulatedAnnealing/source/src_spillage/Plot_Psi.cpp
+//      * (new) abacus-develop/tools/01_NAO_generation/pytorch/IO/print_orbital.py
+//      * (old) abacus-develop/tools/01_NAO_generation/SIAB/src_spillage/Plot_Psi.cpp
 //      *                                                                                  */
 //     int ngrid = 0; // number of grid points
 //     double dr = 0; // grid spacing

docs/parameters.yaml

@@ -129,7 +129,7 @@ In molecular dynamics simulations, the output frequency is controlled by out_fre
  * nspin = 1: pots1.cube;
  * nspin = 2: pots1.cube and pots2.cube;
  * nspin = 4: pots1.cube, pots2.cube, pots3.cube, and pots4.cube
-* 2: Output the electrostatic potential on real space grids into OUT.{suffix}/pot_es.cube. The Python script named tools/average_pot/aveElecStatPot.py can be used to calculate the average electrostatic potential along the z-axis and outputs it into ElecStaticPot_AVE. Please note that the total local potential refers to the local component of the self-consistent potential, excluding the non-local pseudopotential. The distinction between the local potential and the electrostatic potential is as follows: local potential = electrostatic potential + XC potential.
+* 2: Output the electrostatic potential on real space grids into OUT.{suffix}/pot_es.cube. The Python script named tools/02_postprocessing/average_pot/aveElecStatPot.py can be used to calculate the average electrostatic potential along the z-axis and outputs it into ElecStaticPot_AVE. Please note that the total local potential refers to the local component of the self-consistent potential, excluding the non-local pseudopotential. The distinction between the local potential and the electrostatic potential is as follows: local potential = electrostatic potential + XC potential.
 * 3: Apart from 1, also output the total local potential of the initial charge density. The files are named as:
  * out_freq_ion = 0:
    * nspin = 1: `pot_ini.cube`;

source/source_basis/module_nao/atomic_radials.cpp

@@ -414,7 +414,7 @@ void toQO::calculate()
             std::string filename = out_dir_ + "/QO_ovlpR_" + std::to_string(iR) + ".dat";
             std::remove(filename.c_str());
         }
-        printf("toQO::calculate: calculation of S(k) done, run /tools/qo/postprocess.py to do representation "
+        printf("toQO::calculate: calculation of S(k) done, run /tools/01_NAO_generation/qo/postprocess.py to do representation "
                "transform.\n");
     }
 }

source/source_io/module_parameter/read_input_item_output.cpp

@@ -0,0 +1 @@
+threshold 0.0000003