Feature: rework out_app_flag as a three-mode output controller with unified output directories, append semantics, and provenance headers

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/density_matrix.md

@@ -6,11 +6,11 @@ out_dmk    1
 ```
 After finishing the calculation, the density matrix is written into `OUT.${suffix}/`.
 
-For current develop versions:
-- gamma-only (`gamma_only = 1`): `dmg1_nao.txt` (`nspin=1/4`) or `dms1g1_nao.txt` and `dms2g1_nao.txt` (`nspin=2`)
-- multi-k (`gamma_only = 0`): `dmk1g1_nao.txt`, `dmk2g1_nao.txt`, ... (`nspin=1/4`) or `dmk1s1g1_nao.txt`, `dmk1s2g1_nao.txt`, ... (`nspin=2`)
+For current develop versions, the default filenames (with `out_app_flag = 0` or `1`) are:
+- gamma-only (`gamma_only = 1`): `dm_nao.txt` (`nspin=1/4`) or `dms1_nao.txt` and `dms2_nao.txt` (`nspin=2`)
+- multi-k (`gamma_only = 0`): `dmk1_nao.txt`, `dmk2_nao.txt`, ... (`nspin=1/4`) or `dmk1s1_nao.txt`, `dmk1s2_nao.txt`, ... (`nspin=2`)
 
-Here `g{istep}` denotes the geometry/step index in the output filename.
+With `out_app_flag = 2`, a one-based geometry-step suffix `g{istep}` is inserted before `_nao` (for example `dmk1g1_nao.txt`). With `out_app_flag = 0` the fixed file is truncated and overwritten at every write, and with `out_app_flag = 1` records are appended to the fixed file.
 
 For 3.10-LTS, the corresponding keyword is `out_dm`, and file names follow the legacy style such as `SPIN1_DM` and `SPIN2_DM`.
 

docs/advanced/elec_properties/dos.md

@@ -68,7 +68,7 @@ Gamma
 8 8 8 0 0 0
 ```
 
-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.
+Run the program, and you will see a file named doss1.txt in the output directory (with `out_app_flag = 2` the name carries a one-based `g{step}` index, e.g., `doss1g1.txt`). 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.
 
@@ -82,7 +82,7 @@ The `dos` column is a raw per-bin histogram, while `dos_smear` is the physically
 
 ## PDOS
 
-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).
+Along with the DOS files, we also produce the projected density of states (PDOS) in files named pdoss{spin}.txt; with `out_app_flag = 2` a one-based `g{geom}` index is inserted, 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/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`.
+Only when `out_app_flag` is 2 is `g${step}` 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`. With `out_app_flag = 0` the fixed file is truncated and overwritten at every write, and with `out_app_flag = 1` it accumulates one record per written step.
 
 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 `out_app_flag` is 0, the fixed file is truncated and overwritten at every write. Only when `out_app_flag` is 2 does each ionic step have a separate filename containing `g${step}` before `_nao`.
 
 ## out_hsr
 
@@ -95,19 +95,26 @@ 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 2, 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:
+Each ionic step is a complete record with no padding; its header is self-identifying through a magic value and a format version:
 
-1. Native `int`: zero-based ionic step, matrix dimension, number of R blocks.
+1. Versioned header: five native `int` values, namely the magic `0x48535242` (`HSRB`), the format version (`2`), the one-based ionic step, the matrix dimension, and the number of R blocks. The magic and version are absent from the unversioned layout described in the migration note below.
 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. When `out_app_flag` is 0, the fixed file is truncated and overwritten at every write. Only when `out_app_flag` is 2 is every ionic step written to its own file.
+
+> **Format version and migration note.** The native binary record is now versioned. Version `2` starts with the magic `0x48535242` and the version itself, and stores a one-based ionic step. Earlier files are unversioned and start directly with the ionic step, so the first `int` of an unversioned file is a small step index (`0` or `1`) rather than the magic, which makes the two layouts distinguishable.
+> - **v3.11.0-beta9 and v3.11.0-beta10** wrote unversioned records with a **zero-based** ionic step (the first ionic step is stored as `0`).
+> - **Development builds between that change and this versioning scheme** wrote unversioned records with a **one-based** ionic step, so an unversioned file cannot be interpreted from its content alone; the writer version is required.
+> - **Version `2` and later** write the magic, the format version, and a **one-based** ionic step.
+>
+> The matrix data itself is unchanged; only the header and the step convention differ. Readers should reject a record whose first `int` is not the expected magic instead of guessing the layout, and must consult the format version before interpreting the remaining fields. Reading an unversioned beta file as version `2`, or a version `2` file as unversioned, shifts the reported ionic-step index and misaligns every following field.
 
 ### 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). With out_app_flag = 2, each written ionic step has its own file named `rrg${step}_nao.txt`, where `${step}` is the one-based ionic-step index; with out_app_flag = 0 or 1 the fixed name `rr_nao.txt` is reused (mode 0 truncates and overwrites it at every write, mode 1 appends one record per written step). The single-shot output of `calculation = get_s` is always 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`.