Unify output directory structure with out_app_flag=2

AGENTS.md

@@ -79,6 +79,9 @@ rules. Read the complete governance document before making or reviewing changes:
       guards and `#ifdef`/`#ifndef` usages of existing macros are exempt.
   21. Do not initialize member variables from `PARAM` in `.h`/`.hpp`
       files; pass the value through the constructor or a setter instead.
+  22. Print ionic-step indices one-based (starting from 1) in user-facing
+      output files, matching the `g{N}` filename suffix convention; do not
+      write zero-based step counters such as `STEP: 0` into output files.
 - 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.

docs/advanced/elec_properties/Mulliken.md

@@ -1,62 +1,67 @@
 # Mulliken Charge Analysis
 
 From version 2.1.0, ABACUS has the function of Mulliken population analysis. The example can be found in [examples/mulliken](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/14_mulliken). \
-To use this function, set [out_mul](../input_files/input-main.md#out_mul) to `1` in the INPUT file. After calculation, there will be an output file named `mulliken.txt` in the output directory. In MD calculations, the output interval is controlled by the keyword [out_freq_ion](../input_files/input-main.md#out_freq_ion). In the file, there are contents like (`nspin 1`):
+To use this function, set [out_mul](../input_files/input-main.md#out_mul) to `1` in the INPUT file. After calculation, there will be an output file named `mulliken.txt` in the output directory. In MD calculations, the output interval is controlled by the keyword [out_freq_ion](../input_files/input-main.md#out_freq_ion). In the file, there are contents like (`nspin 1`, H<sub>2</sub>):
 
 ```
-STEP: 0
-CALCULATE THE MULLIkEN ANALYSIS FOR EACH ATOM
- Total charge of spin 1:	8
- Total charge:	8
-Decomposed Mulliken populations
-0                 Zeta of Si                        Spin 1
-s                        0                       1.2553358
-  sum over m                                     1.2553358
-s                        1                    -0.030782972
-  sum over m                                  -0.030782972
-  sum over m+zeta                                1.2245529
-pz                        0                      0.85945806
-px                        0                      0.85945806
-py                        0                      0.85945806
-  sum over m                                     2.5783742
-pz                        1                    0.0065801228
-px                        1                    0.0065801228
-py                        1                    0.0065801228
-  sum over m                                   0.019740368
-  sum over m+zeta                                2.5981145
-dz^2                        0                       0.0189287
-dxz                        0                     0.046491729
-dyz                        0                     0.046491729
-dx^2-y^2                        0                       0.0189287
-dxy                        0                     0.046491729
-  sum over m                                    0.17733259
-  sum over m+zeta                               0.17733259
-Total Charge on atom:  Si                   4
+ --- Ionic Step 1 ---
+ Total charge 2
+ Decomposed Mulliken population analysis for each atom
+ l and m from Ylm, z stands for zeta orbital
+
+ ------------------
+ Atom 1 is H
+ ------------------
+          zeta     spin1
+           s 1    0.9980
+           s 2   -0.0052
+        sum mz    0.9928
+
+          pz 1    0.0072
+          px 1    0.0000
+          py 1    0.0000
+         sum m    0.0072
+        sum mz    0.0072
+
+       sum lmz    1.0000
+
+ total charge    on atom 1     1.0000
  ...
 ```
 
-The file gives Mulliken charge in turn according to the order of atoms in the system. For example, the following block is for the first atom in system (`nspin 2`),
+The ionic step index starts from 1. The file gives Mulliken charge in turn according to the order of atoms in the system. For example, the following block is for the first atom in system (`nspin 2`),
 
 ```
-0            Zeta of Si               Spin 1              Spin 2                Sum                Diff
+ ------------------
+ Atom 1 is Fe1
+ ------------------
+          zeta     spin1     spin2       sum      diff
+           s 1    0.9437    0.8381    1.7818    0.1056
 ...
-Total Charge on atom:  Si                   4
-Total Magnetism on atom:  Si      -1.2739809e-14
+        sum lmz    ...
 ```
 
 And the next block is for the second atom in system, and so on.
 
 ```
-1            Zeta of Si               Spin 1              Spin 2                Sum                Diff
+ ------------------
+ Atom 2 is Fe2
+ ------------------
+          zeta     spin1     spin2       sum      diff
 ...
 ```
 
 For each atom, the file gives detailed Mulliken population analysis at different levels,
 
--   magnetic quantum number level: such as lines beigin with ‘s,px,py,pz,...’
--   azimuthal quantum number level: such as lines begin with ‘sum over m’.
--   principal quantum number level: such as lines begin with ‘sum over m+zeta’. Here ‘zeta’
-    equals ‘zeta’ in the file, which means how many radial atomic orbitals there are for a given orbital angular momentum.
--   atomic level: such as lines begin with ‘Total Charge on atom’.
+-   magnetic quantum number level: such as lines begin with 's, px, py, pz, ...'. The columns
+    are the radial index (`zeta`, one-based) followed by the spin channels.
+-   azimuthal quantum number level: such as lines begin with 'sum m', the sum over the
+    magnetic quantum number m for one radial orbital.
+-   principal quantum number level: such as lines begin with 'sum mz', the sum over both the
+    magnetic quantum number m and the radial index zeta for a given orbital angular momentum.
+    Here 'z' equals 'zeta' in the file, which means how many radial atomic orbitals there are
+    for a given orbital angular momentum.
+-   atomic level: such as lines begin with 'sum lmz' for the atom total and
+    'total charge on atom' for the charge assigned to the atom.
 
-More orbital information can be found in 'Orbital' file output with 'mulliken.txt' when `out_mul 1`
+More orbital information can be found in 'nao.txt' file output with 'mulliken.txt' when `out_mul 1`

docs/advanced/elec_properties/hs_matrix.md

@@ -39,7 +39,7 @@ The output filenames depend on the k-point algorithm and `nspin`:
 
 Here `${k}` is the one-based k-point index. For `nspin = 2`, the overlap matrix is spin-independent, so only one overlap file is written for each physical k point. The gamma-only algorithm does not support `nspin = 4`; use the multi-k algorithm with an explicit Gamma-only `KPT` file for a noncollinear calculation at Gamma.
 
-When `out_app_flag` is false, `g${step}` is inserted before `_nao`, where `${step}` is the one-based ionic-step index. For example, the first spin channel at the first k point and first ionic step is written to `hk1s1g1_nao.txt`.
+When `out_app_flag` is not 1, `g${step}` is inserted before `_nao`, where `${step}` is the one-based ionic-step index. For example, the first spin channel at the first k point and first ionic step is written to `hk1s1g1_nao.txt`.
 
 Each output block starts with a comment header containing the one-based ionic-step index, filename, `gamma only` flag, and matrix dimensions. It is followed by `Row 1`, `Row 2`, and so on. Each row contains the matrix elements from the diagonal through the upper triangle.
 
@@ -57,7 +57,7 @@ For `out_hsk 2`, the filenames in the table above use `.dat` instead of `.txt`.
 
 The file therefore contains `sizeof(int) + N(N+1)/2 * sizeof(double)` bytes for a gamma-only record and `sizeof(int) + N(N+1) * sizeof(double)` bytes for a multi-k or spinor record. The format uses the host integer representation and byte order and is intended for readers using a compatible ABI.
 
-When `out_app_flag` is true, the first ionic step truncates the shared file and every later step appends another complete record. When it is false, each ionic step has a separate filename containing `g${step}` before `_nao`.
+When `out_app_flag` is 1, the first ionic step truncates the shared file and every later step appends another complete record. When it is not 1, each ionic step has a separate filename containing `g${step}` before `_nao`.
 
 ## out_hsr
 
@@ -95,19 +95,19 @@ In gamma-only mode, every generated file reports one Bravais lattice vector and
 
 ### Native Binary CSR Format
 
-Set `out_hsr 2` to write the same H(R) and S(R) matrix sets with a `.dat` suffix. For example, an `nspin = 2` calculation writes `hrs1_nao.dat`, `hrs2_nao.dat`, and `sr_nao.dat`. When `out_app_flag` is false, the one-based ionic step is included before `_nao`, for example `hrs1g1_nao.dat` and `srg1_nao.dat`.
+Set `out_hsr 2` to write the same H(R) and S(R) matrix sets with a `.dat` suffix. For example, an `nspin = 2` calculation writes `hrs1_nao.dat`, `hrs2_nao.dat`, and `sr_nao.dat`. When `out_app_flag` is not 1, the one-based ionic step is included before `_nao`, for example `hrs1g1_nao.dat` and `srg1_nao.dat`.
 
 Each ionic step is a complete record with no padding or self-describing header:
 
-1. Native `int`: zero-based ionic step, matrix dimension, number of R blocks.
+1. Native `int`: one-based ionic step, matrix dimension, number of R blocks.
 2. For every R block in lexicographic `(Rx, Ry, Rz)` order, four native `int` values: `Rx`, `Ry`, `Rz`, and `nnz`.
 3. `nnz` matrix values in CSR order. Real matrices use one native `double`; complex matrices use consecutive real and imaginary `double` values.
 4. `nnz` native `int` column indices.
 5. `dimension + 1` native `long long` row pointers.
 
 All R blocks stored by the internal HContainer are present, including blocks with zero nonzero values. The sparse threshold is `1e-10`, matching text CSR output. The format uses the host integer representation and byte order and therefore requires a compatible ABI. It does not contain unit-cell, spin, or matrix-label metadata; those are determined by the calculation input and filename.
 
-When `out_app_flag` is true, the first ionic step truncates the shared file and later ionic steps append complete records. Otherwise every ionic step is written to its own file.
+When `out_app_flag` is 1, the first ionic step truncates the shared file and later ionic steps append complete records. Otherwise every ionic step is written to its own file.
 
 ### NPZ Format
 

docs/advanced/elec_properties/position_matrix.md

@@ -18,7 +18,7 @@ Each file or each section of the appended file starts with "STEP: " followed by
 
 Each block here contains the matrix for the corresponding cell. There are three columns in each block, giving the matrix elements in x, y, z directions, respectively. There are altogether nbasis * nbasis lines in each block, which emulates the matrix elements.
 
-In molecular dynamics (MD) calculations, if [out_app_flag](../input_files/input-main.md#out_app_flag) is set to true, then `data-rR-tr` is written in an append manner. Otherwise, output files will be put in a separate directory, `matrix`, and named as `$x`_data-rR-tr, where `$x` is the number of MD step. In addition, the output frequency is controlled by [out_freq_ion](../input_files/input-main.md#out_freq_ion). For example, if we are running a 10-step MD with out_freq_ion = 3, then `$x` will be 0, 3, 6, and 9.
+In molecular dynamics (MD) calculations, the output frequency is controlled by [out_freq_ion](../input_files/input-main.md#out_freq_ion). Each ionic step is written to its own file named `rrg${step}_nao.txt`, where `${step}` is the one-based ionic-step index, while the single-shot output of `calculation = get_s` is named `rr_nao.txt`. The files are stored in `OUT.${suffix}` when [out_app_flag](../input_files/input-main.md#out_app_flag) is 0 or 1, and in its `MAT/` subdirectory when out_app_flag is 2. For example, if we are running a 10-step MD with out_freq_ion = 3 and out_app_flag = 2, the files are `MAT/rrg1_nao.txt`, `MAT/rrg4_nao.txt`, `MAT/rrg7_nao.txt`, and `MAT/rrg10_nao.txt`.
 
 ## get_s
 We also offer the option of only calculating the position matrix without running SCF. For that purpose, in `INPUT` file we need to set the keyword [calculation](../input_files/input-main.md#calculation) to `get_s`, and [out_mat_r](../input_files/input-main.md#out_mat_r) to `true`.

docs/advanced/elec_properties/wfc.md

@@ -18,7 +18,7 @@ The [`init_wfc file binary`](../scf/initialization.md#wavefunction) path reads o
 
 For `basis_type=lcao`, [`out_wfc_lcao`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-lcao) controls the output of numerical-atomic-orbital coefficients: `1` writes text files with the `.txt` suffix and `2` writes binary files with the `.dat` suffix. Multi-k calculations generate `wfs{spin}k{k-point}_nao.txt` or `.dat`, while Gamma-only calculations generate `wfs{spin}_nao.txt` or `.dat`.
 
-To reuse LCAO coefficients, point `read_file_dir` to the coefficient files and set `init_wfc file txt` for text input or `init_wfc file binary` for binary input. The selected extension is required; there is no automatic format fallback. Only independent files without geometry-step indices are supported, not files accumulated with `out_app_flag`.
+To reuse LCAO coefficients, point `read_file_dir` to the coefficient files and set `init_wfc file txt` for text input or `init_wfc file binary` for binary input. The selected extension is required; there is no automatic format fallback. Only independent files without geometry-step indices are supported, not files accumulated with `out_app_flag=1`.
 
 ## Wave Function in Real Space
 

docs/advanced/output_files/output-specification.md

@@ -55,6 +55,12 @@ All output file naming conventions can be found in the online documentation (wit
 - All index numbers start from 1 (not 0)
 - For Gamma-only algorithm in LCAO, no `k` index is included
 - Overlap matrix `s` does not distinguish spin, so only one matrix is output
+- `out_app_flag = 1` omits the `g#` suffix for cube files (chg/tau/pot/elf): the
+  first written ionic step truncates the fixed-name file and every later
+  written step appends one complete cube frame whose first comment line is
+  `Ionic_Step {#}` (one-based). `out_app_flag = 0` writes one suffixed file per
+  step, and `out_app_flag = 2` writes those suffixed files into the `CHG/`,
+  `POT/` and `ELF/` subdirectories
 - For initial charge density output (`out_chg = 2`):
   - `out_freq_ion = 0`: `chg_ini.cube` (nspin=1) or `chgs{#}_ini.cube` (nspin=2/4) - output at every step (overwrite same file)
   - `out_freq_ion > 0`: `chgg{#}_ini.cube` (nspin=1) or `chgs{#}g{#}_ini.cube` (nspin=2/4) - output every out_freq_ion steps
@@ -98,7 +104,7 @@ All output file naming conventions can be found in the online documentation (wit
 | `doss1g1.txt` | Density of states |
 | `eig_occ.txt` | Eigenvalues and occupations |
 | `mulliken.txt` | Mulliken population analysis |
-| `band.txt` | Band structure |
+| `band.txt` | Band structure (nspin=1/4); `bands1.txt`/`bands2.txt` when nspin=2 |
 | `chgs1.cube`, `chgs2.cube` | Charge density (spin 1, spin 2) |
 | `chg.cube` | Total charge density |
 | Initial charge density (out_chg=2) | |
@@ -121,6 +127,21 @@ All output file naming conventions can be found in the online documentation (wit
 | `elfs{#}g{#}.cube` | ELF, spin {#}, geometry step {#} (nspin=2) |
 | `elftotg{#}.cube` | ELF, total, geometry step {#} (nspin=2) |
 
+**Band structure files (`out_band`):** each ionic step of `band.txt`,
+`bands1.txt` and `bands2.txt` is preceded by a provenance comment block, so the
+k-point blocks appended by a relax/md run stay distinguishable:
+
+```
+# ABACUS version: v3.11.0-beta11
+# Written at 2026-10-20 15:40:45
+# IONIC STEP 1 (spin up)
+   1 0.00000000 -5.36802595 6.70427084 ...
+```
+
+`# IONIC STEP` is one-based and carries the collinear spin-channel label only
+when `nspin = 2`. Consumers that parse the numeric columns must skip lines
+starting with `#`.
+
 ## 3. File Format Standards
 
 ### 3.1 Header Section with Comments

docs/advanced/scf/initialization.md

@@ -26,7 +26,7 @@ For `basis_type=pw`, the available options are:
 * `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 binary`: Read binary `wf*_pw.dat` files generated with [`out_wfc_pw=2`](../elec_properties/wfc.md) from `read_file_dir`. The files must match the current k points, `nbands`, plane-wave layout, and lattice. The `txt` format is not supported for PW wavefunctions.
 
-For `basis_type=lcao`, use `init_wfc file txt` to read text `wf*_nao.txt` files generated with [`out_wfc_lcao=1`](../elec_properties/wfc.md), or `init_wfc file binary` to read binary `wf*_nao.dat` files generated with `out_wfc_lcao=2`, from `read_file_dir`. LCAO wavefunctions initialize the density matrix and real-space charge density. The selected format is required; ABACUS does not automatically detect or fall back to the other format. The files must use a compatible NAO basis, match the current k-point and spin setup, and contain enough bands. Only independent files without geometry-step indices are supported, not files accumulated with `out_app_flag`.
+For `basis_type=lcao`, use `init_wfc file txt` to read text `wf*_nao.txt` files generated with [`out_wfc_lcao=1`](../elec_properties/wfc.md), or `init_wfc file binary` to read binary `wf*_nao.dat` files generated with `out_wfc_lcao=2`, from `read_file_dir`. LCAO wavefunctions initialize the density matrix and real-space charge density. The selected format is required; ABACUS does not automatically detect or fall back to the other format. The files must use a compatible NAO basis, match the current k-point and spin setup, and contain enough bands. Only independent files without geometry-step indices are supported, not files accumulated with `out_app_flag=1`.
 
 For `basis_type=lcao_in_pw`, `init_wfc` is automatically set to `nao`.
 

examples/17_relax/04_relax_with_output_lcao/INPUT

@@ -34,11 +34,12 @@ out_dmr              1
 out_dos              1
 out_band             1
 out_stru             1
-out_app_flag         0
 
 out_mat_l 1
 out_mat_r 1
 out_mat_t 1 
 #out_mat_dh 1
 
 out_freq_ion         2
+
+out_app_flag         2

examples/18_md/02_lcao_output/INPUT

@@ -36,3 +36,5 @@ md_tchain              1
 
 dft_functional       hse
 restart_save           1
+
+out_app_flag          0

interfaces/Multiwfn_interface/molden.py

@@ -533,6 +533,10 @@ def read_abacus_lowf(flowf, pat=r'^(WFC_NAO_(K\d+|GAMMA\d+)(_ION\d+)?|wf((k\d+)?
     with open(flowf, 'r') as file:
         lines = file.readlines()
 
+    # ignore provenance comment lines (version/timestamp/ionic step) that
+    # ABACUS writes before the data block
+    lines = [line for line in lines if not line.lstrip().startswith('#')]
+
     if lines[0].endswith('(index of k points)\n'):
         # discard the first two lines
         lines = lines[2:]