Merge branch 'develop' into develop

Author: dyzheng

.github/workflows/cuda.yml

@@ -73,6 +73,30 @@ jobs:
           cd tests/13_NAO_multik_GPU
           bash ../integrate/Autotest.sh -n 2 -f CASES_GPU.txt
 
+      - name: Test 02_NAO_Gamma on GPU
+        run: |
+          cd tests/02_NAO_Gamma
+          find . -name INPUT | while read f; do
+              if grep -qE '^[[:space:]]*device[[:space:]]+' "$f"; then
+                  sed -i -E 's/^[[:space:]]*device[[:space:]]+.*/device    gpu/' "$f"
+              else
+                  echo "device    gpu" >> "$f"
+              fi
+          done
+          bash ../integrate/Autotest.sh -n 2 -f CASES_GPU.txt
+
+      - name: Test 03_NAO_multik on GPU
+        run: |
+          cd tests/03_NAO_multik
+          find . -name INPUT | while read f; do
+              if grep -qE '^[[:space:]]*device[[:space:]]+' "$f"; then
+                  sed -i -E 's/^[[:space:]]*device[[:space:]]+.*/device    gpu/' "$f"
+              else
+                  echo "device    gpu" >> "$f"
+              fi
+          done
+          bash ../integrate/Autotest.sh -n 2 -f CASES_GPU.txt
+
       - name: Test 15_rtTDDFT_GPU
         run: |
           cd tests/15_rtTDDFT_GPU

AGENTS.md

@@ -8,7 +8,7 @@ rules. Read the complete governance document before making or reviewing changes:
 
 ## Required Baseline
 
-- Follow the seven ABACUS coding rules summarized from the project governance:
+- Follow the nine ABACUS coding rules summarized from the project governance:
   1. Do not increase cross-layer control through `GlobalV`, `GlobalC`, or
      `PARAM`; pass dependencies explicitly where practical. Migration-neutral
      moves must keep the PR-level global dependency budget non-increasing and
@@ -23,6 +23,9 @@ rules. Read the complete governance document before making or reviewing changes:
   6. Add focused tests for key features, bug fixes, INPUT behavior changes,
      heterogeneous kernels, and core-module refactors.
   7. Keep code compatible with the repository C++11 baseline.
+  8. Declare one variable per line; do not use comma-separated declarations.
+  9. Do not call MPI routines directly; use the internally-guarded wrappers
+     (e.g., `Parallel_Reduce::reduce_*`, `Parallel_Common::bcast_*`) instead.
 - Use LF line endings for text files. Only `.bat` and `.cmd` files may use CRLF.
 - Keep source file additions deterministic: update the relevant `CMakeLists.txt`
   or explain why the file is generated or included indirectly.
@@ -31,6 +34,10 @@ rules. Read the complete governance document before making or reviewing changes:
   is required.
 - Report the exact verification performed. Do not claim completion without
   fresh test or check output.
+- Prefer `std::vector` over raw `new`/`delete` for dynamic arrays; before
+  converting class members, confirm no external code consumes them as raw
+  pointers (e.g., `std::vector<bool>` has no `.data()`), and use
+  `std::fill`/`std::copy` instead of `ZEROS`/`COPYARRAY` on vector buffers.
 
 ## Repository Map
 
@@ -83,6 +90,15 @@ rules. Read the complete governance document before making or reviewing changes:
   test sufficiency, and exception approval require human review.
 - Exceptions must be recorded in the PR with reason, scope, risk, and a follow-up
   cleanup plan.
+- After a refactor, propose brief lessons worth recording in this file, then
+  ask the developer whether to write them in; be cautious and skip unclear
+  or unverified lessons.
+
+## Refactoring Patterns
+
+- Member -> free function: inventory `this->` reads; pass as params (const
+  for config, ref for mutable state); move only when body is `this`-free;
+  keep thin wrapper; compile each step.
 
 ## Local Commands
 

docs/advanced/elec_properties/wfc.md

@@ -4,15 +4,22 @@ ABACUS is able to output electron wave functions in both PW and LCAO basis calcu
 
 ## Wave Function in G-Space
 
-To output wave functions in G-space, add one of the following keywords to the `INPUT` file while performing SCF calculation:
-- **PW basis**: Set [`out_wfc_pw`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-pw) to `1`. Output file format: `wfs[spin]k[kpoint]_pw.txt`, where `[spin]` is the spin channel index, and `[kpoint]` the k-point index.
+For `basis_type=pw` and `esolver_type=ksdft`, [`out_wfc_pw`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-pw) controls the output of plane-wave Kohn-Sham coefficients:
 
-- **LCAO basis**: Set [`out_wfc_lcao`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-lcao) to `1`.  
-  - **Multi-k calculations**: Generates multiple files `wfs[spin]k[kpoint]_nao.txt`.
-  - **Gamma-only calculations**: `wfs[spin]_nao.txt` instead.
+* `0`: Do not write wave-function coefficients.
+* `1`: Write text files with the `.txt` suffix.
+* `2`: Write binary files with the `.dat` suffix.
+
+The files are stored in `OUT.${suffix}/`. Their pattern is `wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.txt` for `out_wfc_pw=1` and `wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.dat` for `out_wfc_pw=2`. The `s*` label is omitted for `nspin=1`, is `s1` or `s2` for `nspin=2`, and is `s4` for `nspin=4`. All PW files include the `k*` label, including Gamma-only calculations.
+
+With `out_freq_ion=0`, files are written only when the electronic calculation converges or reaches `scf_nmax`, and the names contain neither `g*` nor `e*`. During structural relaxation or molecular dynamics, each later ionic step overwrites the same files. With `out_freq_ion>0`, output is restricted to the ionic steps selected by `out_freq_ion` and occurs at multiples of `out_freq_elec`, at convergence, or at `scf_nmax`; both `g*` and `e*` are included in the file names. A static `calculation=scf` or `calculation=nscf` run also receives `g1e*` indices when `out_freq_ion>0`.
+
+The normal [`init_wfc=file`](../scf/initialization.md#wave-function) path reads only unindexed binary `wf*_pw.dat` files from `read_file_dir`. Generate directly reusable files with `out_wfc_pw=2` and normally `out_freq_ion=0`. Text `wf*_pw.txt` files and files containing `g*` or `e*` indices are not matched automatically.
+
+For `basis_type=lcao`, set [`out_wfc_lcao=1`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-lcao). Multi-k calculations generate `wfs{spin}k{k-point}_nao.txt`, while Gamma-only calculations generate `wfs{spin}_nao.txt`.
 
 ## Wave Function in Real Space
 
 One can also choose to output real-space wave functions with the keyword [`out_wfc_norm`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-norm) or [`out_wfc_re_im`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-re-im).
 
-Notice: When the [`basis_type`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#basis-type) is `lcao`, only `get_wf` [`calculation`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#calculation) is effective. An example is [examples/11_wfc/lcao_ienvelope_Si2](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/11_wfc/lcao_ienvelope_Si2).
+Notice: When the [`basis_type`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#basis-type) is `lcao`, only `get_wf` [`calculation`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#calculation) is effective. An example is [examples/11_wfc/lcao_ienvelope_Si2](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/11_wfc/lcao_ienvelope_Si2).

docs/advanced/input_files/input-main.md

@@ -731,18 +731,22 @@
 ### init_wfc
 
 - **Type**: String
-- **Description**: The type of the starting wave functions.
+- **Description**: The method used to initialize wavefunction coefficients. The available options and behavior depend on `basis_type`.
 
-  Available options are:
+  For `basis_type=pw`, the available options are:
+
+  - `atomic`: Use atomic pseudo wavefunctions from `PP_PSWFC`. If no `PP_PSWFC` states are available, all bands are initialized randomly. If the number of atomic states is smaller than `nbands`, the remaining bands are initialized randomly.
+  - `atomic+random`: If there are at least `nbands` atomic states, apply an approximately 5% multiplicative random perturbation to the atomic initialization. If there are fewer atomic states than `nbands`, use the atomic states and initialize the remaining bands randomly, as for `atomic`.
+  - `random`: Initialize all bands with random coefficients.
+  - `nao`: Use numerical atomic orbitals. If the number of NAO states is smaller than `nbands`, the remaining bands are initialized randomly.
+  - `nao+random`: Apply an approximately 5% multiplicative random perturbation to the NAO initialization; any bands not covered by NAO states are first initialized randomly.
+  - `file`: Read binary `wf*_pw.dat` files generated with `out_wfc_pw=2` from `read_file_dir`. The files must match the current k points, `nbands`, plane-wave layout, and lattice.
+
+  For `basis_type=lcao`, only `file` triggers reading existing wavefunctions. It reads text `wf*_nao.txt` files generated with `out_wfc_lcao=1` from `read_file_dir`; binary files generated with `out_wfc_lcao=2` are not supported. The files must use a compatible NAO basis, match the current k-point and spin setup, and contain enough bands. Normal `init_wfc=file` reading matches files written with the default `out_app_flag=true`, which have no geometry-step index. Files written under `WFC/` with a `g*` geometry-step index when `out_app_flag=false` are not matched automatically.
 
-  - atomic: from atomic pseudo wave functions. If they are not enough, other wave functions are initialized with random numbers.
-  - atomic+random: add small random numbers on atomic pseudo-wavefunctions
-  - file: from binary files wf*.dat, which are output by setting out_wfc_pw to 2.
-  - random: random numbers
-  - nao: from numerical atomic orbitals. If they are not enough, other wave functions are initialized with random numbers.
-  - nao+random: add small random numbers on numerical atomic orbitals
+  For `basis_type=lcao_in_pw`, `init_wfc` is automatically set to `nao`.
 
-  > Note: Only the file option is useful for the lcao basis set, which is mostly used when calculation is set to get_wf and get_pchg.
+  > Note: For `calculation=get_wf` or `calculation=get_pchg`, `init_wfc` is automatically set to `file`. If `basis_type=lcao_in_pw` is also used, the final value is `nao`.
 - **Default**: atomic
 
 ### init_chg
@@ -1937,19 +1941,22 @@
 ### out_wfc_pw
 
 - **Type**: Integer
-- **Availability**: *[`basis_type`](#basis_type)==pw or ([`basis_type`](#basis_type)==lcao and [`calculation`](#calculation)==get_wf)*
-- **Description**: Whether to output the electronic wavefunction coefficients into files and store them in the folder OUT.${suffix}. The files are named as wf{k}{k-point index}{s}{spin index}{g}{geometry index}{e}{electronic iteration index}{_pw} + {".txt"/".dat"}. Here, the s index refers to spin but the label will not show up for non-spin-polarized calculations, where s1 means spin up channel while s2 means spin down channel, and s4 refers to spinor wave functions that contains both spin channels with spin-orbital coupling or noncollinear calculations enabled. For scf or nscf calculations, g index will not appear, but the g index appears for geometry relaxation and molecular dynamics, where one can use the out_freq_ion command to control. To print out the electroinc wave functions every few SCF iterations, use the out_freq_elec command and the e index will appear in the file name.
-  - 0: no output
-  - 1: (txt format)
-   - non-gamma-only with nspin=1: wfk1_pw.txt, wfk2_pw.txt, ...;
-   - non-gamma-only with nspin=2: wfk1s1_pw.txt, wfk1s2_pw.txt, wfk2s1_pw.txt, wfk2s2_pw.txt, ...;
-   - non-gamma-only with nspin=4: wfk1s4_pw.txt, wfk2s4_pw.txt, ...;
-  - 2: (binary format)
-   - non-gamma-only with nspin=1: wfk1_pw.dat, wfk2_pw.dat, ...;
-   - non-gamma-only with nspin=2: wfk1s1_pw.dat, wfk1s2_pw.dat, wfk2s1_pw.dat, wfk2s2_pw.dat, ...;
-   - non-gamma-only with nspin=4: wfk1s4_pw.dat, wfk2s4_pw.dat, ...;
+- **Availability**: *[`basis_type`](#basis_type)==pw and [`esolver_type`](#esolver_type)==ksdft*
+- **Description**: Controls whether plane-wave Kohn-Sham wavefunction coefficients are written to `OUT.${suffix}/`.
+
+  Available values are:
+
+  - `0`: Do not write wavefunction coefficients.
+  - `1`: Write text files with the `.txt` suffix.
+  - `2`: Write binary files with the `.dat` suffix.
+
+  The file-name pattern is `wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.txt` for `out_wfc_pw=1` and `wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.dat` for `out_wfc_pw=2`. All PW output files include a `k*` label, including Gamma-only calculations. Without geometry-step or electronic-iteration indices, representative names are `wfk1_pw.txt` or `wfk1_pw.dat` for `nspin=1`, `wfk1s1_pw.txt` and `wfk1s2_pw.txt` or their `.dat` equivalents for `nspin=2`, and `wfk1s4_pw.txt` or `wfk1s4_pw.dat` for `nspin=4`.
+
+  With `out_freq_ion=0`, files are written only when the electronic calculation converges or reaches `scf_nmax`; no `g*` or `e*` index is added. During structural relaxation or molecular dynamics, later ionic steps overwrite the same unindexed files. With `out_freq_ion` > 0, output is restricted to the ionic steps selected by `out_freq_ion` and is written when the electronic iteration is a multiple of `out_freq_elec`, when the calculation converges, or when it reaches `scf_nmax`. Both `g*` and `e*` indices are then added, including for a static `calculation=scf` or `calculation=nscf` run.
+
+  For `init_wfc=file`, ABACUS automatically reads only unindexed binary `wf*_pw.dat` files from `read_file_dir`. Such directly reusable files are normally generated with `out_wfc_pw=2` and `out_freq_ion=0`. Text `wf*_pw.txt` files and files containing `g*` or `e*` indices are not matched automatically.
 
-  > Note: In the 3.10-LTS version, the file names are WAVEFUNC1.dat, WAVEFUNC2.dat, etc.
+  > Note: In the 3.10-LTS version, the binary files are named `WAVEFUNC1.dat`, `WAVEFUNC2.dat`, etc.
 - **Default**: 0
 
 ### out_wfc_lcao
@@ -2394,14 +2401,14 @@
 
 - **Type**: String
 - **Availability**: *[`basis_type`](#basis_type)==pw or ([`basis_type`](#basis_type)==lcao and [`calculation`](#calculation)==get_wf)*
-- **Description**: Selects electronic states for real-space wavefunction-modulus output using the selection syntax and complete-state normalization of `out_pchg`. For `nspin=1`, `s1` contains the wavefunction modulus. For `nspin=2`, `s1` and `s2` contain the spin-up and spin-down wavefunction moduli, respectively. For `nspin=4`, `s1` contains the total spinor modulus. Files are named `wfi[state]s[spin]k[kpoint].cube`.
+- **Description**: Selects electronic states for real-space wavefunction-modulus output using the selection syntax of `out_pchg`. Each wavefunction is normalized as a single-particle state and does not include SCF occupations or spin-degeneracy factors. For `nspin=1`, `s1` contains the wavefunction modulus. For `nspin=2`, `s1` and `s2` contain the spin-up and spin-down wavefunction moduli, respectively. For `nspin=4`, `s1` contains the total spinor modulus. Files are named `wfi[state]s[spin]k[kpoint].cube`.
 - **Default**: none
 
 ### out_wfc_re_im
 
 - **Type**: String
 - **Availability**: *[`basis_type`](#basis_type)==pw or ([`basis_type`](#basis_type)==lcao and [`calculation`](#calculation)==get_wf)*
-- **Description**: Selects electronic states for real-space wavefunction real- and imaginary-part output using the selection syntax and complete-state normalization of `out_pchg`. For `nspin=1`, `s1` contains the wavefunction. For `nspin=2`, `s1` and `s2` contain the spin-up and spin-down wavefunctions, respectively. For `nspin=4`, `s1` and `s2` contain the upper and lower spinor components, respectively. Files are named `wfi[state]s[spin]k[kpoint][re/im].cube`.
+- **Description**: Selects electronic states for real-space wavefunction real- and imaginary-part output using the selection syntax of `out_pchg`. Each wavefunction is normalized as a single-particle state and does not include SCF occupations or spin-degeneracy factors. For `nspin=1`, `s1` contains the wavefunction. For `nspin=2`, `s1` and `s2` contain the spin-up and spin-down wavefunctions, respectively. For `nspin=4`, `s1` and `s2` contain the upper and lower spinor components, respectively. Files are named `wfi[state]s[spin]k[kpoint][re/im].cube`.
 - **Default**: none
 
 ### if_separate_k