Merge branch 'develop' into develop

Author: Flying-dragon-boxing

.github/workflows/version_check.yml

@@ -0,0 +1,45 @@
+name: Version Check
+on:
+  release:
+    types: [published]
+
+jobs:
+  validate_version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch complete git history for version comparison
+
+      # Extract last two tags for version comparison
+      - name: Get version history
+        id: versions
+        run: |
+          # Get previous tag (skip current tag)
+          PREV_TAG=$(git describe --tags --abbrev=0 $(git rev-list --tags --skip=1 --max-count=1))
+          # Current tag being published (extracted from GITHUB_REF)
+          CURRENT_TAG=${GITHUB_REF#refs/tags/}
+          echo "prev_tag=${PREV_TAG}" >> $GITHUB_OUTPUT
+          echo "current_tag=${CURRENT_TAG}" >> $GITHUB_OUTPUT
+
+      # Validate version.h matches the release tag
+      - name: Assert version increment
+        run: |
+          CODE_VERSION=$(grep -oP '#define\s+VERSION\s+"\K\d+(\.\d+){2,3}' source/version.h)
+
+          if [[ -z "$CODE_VERSION" ]]; then
+            echo "::error::Failed to extract version from source/version.h"
+            exit 1
+          fi
+
+          # Verify that the version in version.h matches the tag
+          if [[ "${{ steps.versions.outputs.current_tag }}" != "v${CODE_VERSION}" ]]; then
+            echo "::error::Version mismatch: tag=${{ steps.versions.outputs.current_tag }} ≠ code=${CODE_VERSION}"
+            exit 1
+          fi
+
+          # Ensure the version has been incremented
+          if [[ "${{ steps.versions.outputs.prev_tag}}" == "${{ steps.versions.outputs.current_tag }}" ]]; then
+            echo "::error::Version unchanged: ${{ steps.versions.outputs.current_tag }}"
+            exit 1
+          fi

docs/advanced/elec_properties/density_matrix.md

@@ -1,8 +1,8 @@
 # Extracting Density Matrices
 
-ABACUS can output the density matrix by adding the keyword "[out_dm](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-dm)" in INPUT file:
+ABACUS can output the density matrix by adding the keyword "[out_dmk](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-dm)" in INPUT file:
 ```
-out_dm             1
+out_dmk    1
 ```
 After finishing the calculation, the information of the density matrix is stroed in files `OUT.${suffix}/SPIN${spin}_DM`, which looks like:
 ```
@@ -37,4 +37,4 @@ The following line is dimension of the density matrix, and the rest lines are th
 
 The examples can be found in [examples/density_matrix](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/density_matrix)
 
-- Note: now this function is valid only for LCAO gamma only calcualtion.
+- Note: now this function is valid only for LCAO gamma only calcualtion.

docs/advanced/elec_properties/hs_matrix.md

@@ -1,8 +1,8 @@
 # Extracting Hamiltonian and Overlap Matrices
 
-In ABACUS, we provide the option to write the Hamiltonian and Overlap matrices to files after SCF calculation.
+In ABACUS, we provide the option to write the Hamiltonian and Overlap matrices to files after SCF calculations.
 
-For periodic systems, there are two ways to represent the matrices, the first is to write the entire square matrices for each k point, namely $H(k)$ and $S(k)$; the second is the R space representation, $H(R)$ and $S(R)$, where R is the lattice vector. The two representations are connected by Fourier transform: 
+For periodic systems, there are two ways to construct the matrices, the first is to write the entire square matrices for each $k$ point in the Brillouin zone, namely $H(k)$ and $S(k)$; the second one is the real space representation, $H(R)$ and $S(R)$, where R is the Bravis lattice vector. The two representations are connected by Fourier transform:
 
 - $H(k)=\sum_R H(R)e^{-ikR}$
 
@@ -12,18 +12,9 @@ and
 
 ## out_mat_hs
 
-Users can set the keyword [out_mat_hs](../input_files/input-main.md#out_mat_hs) to true for outputting the upper triangular part of the Hamiltonian matrices and overlap matrices for each k point into files in the directory `OUT.${suffix}`. It is available for both gamma_only and multi-k calculations. 
+Users can set the keyword [out_mat_hs](../input_files/input-main.md#out_mat_hs) to true to print the upper triangular part of the Hamiltonian matrices and overlap matrices for each k point into files in the directory `OUT.${suffix}`. It is available for both gamma_only and multi-k calculations. 
 
-The files are named `data-$k-H` and `data-$k-S`, where `$k` is a composite index consisting of the k point index as well as the spin index. The corresponding sequence of the orbitals can be seen in [Basis Set](../pp_orb.md#basis-set).
-
-For nspin = 1 and nspin = 4 calculations, there will be only one spin component, so `$k` runs from 0 up to `$nkpoints-1`. For nspin = 2, `$k` runs from `2*$nkpoints-1`. In the latter case, the files are arranged into blocks of up and down spins. For example, if there are 3 k points, then we have the following correspondence:
-
-  - data-0-H : 1st k point, spin up
-  - data-1-H : 2nd k point, spin up
-  - data-2-H : 3rd k point, spin up
-  - data-3-H : 1st k point, spin down
-  - data-4-H : 2nd k point, spin down
-  - data-5-H : 3rd k point, spin down
+The $H(k)$ and $S(k)$ matrices are stored with numerical atomic orbitals as basis, and the corresponding sequence of the numerical atomic orbitals can be seen in [Basis Set](../pp_orb.md#basis-set).
 
 As for information on the k points, one may look for the `SETUP K-POINTS` section in the running log.
 
@@ -33,12 +24,10 @@ The rest of the file contains the upper triangular part of the specified matrice
 
 ## out_mat_hs2
 
-The output of R-space matrices is controlled by the keyword [out_mat_hs2](../input_files/input-main.md#out_mat_hs2). This functionality is not available for gamma_only calculations. To generate such matrices for gamma only calculations, users should turn off [gamma_only](../input_files/input-main.md#gamma_only), and explicitly specify that gamma point is the only k point in the KPT file.
+The output of $H(R)$ and $S(R)$ matrices is controlled by the keyword [out_mat_hs2](../input_files/input-main.md#out_mat_hs2). This functionality is not available for gamma_only calculations. To generate such matrices for gamma only calculations, users should turn off [gamma_only](../input_files/input-main.md#gamma_only), and explicitly specify that gamma point is the only k point in the KPT file.
 
 For single-point SCF calculations, if nspin = 1 or nspin = 4, two files `hrs1_nao.csr` and `sr_nao.csr` are generated, which contain the Hamiltonian matrix $H(R)$ and overlap matrix $S(R)$ respectively. For nspin = 2, three files `hrs1_nao.csr` and `hrs2_nao.csr` and `sr_nao.csr` are created, where the first two files correspodn to $H(R)$ for spin up and spin down, respectively.
 
-As for molecular dynamics calculations, the format is controlled by [out_interval](../input_files/input-main.md#out_interval) and [out_app_flag](../input_files/input-main.md#out_app_flag) in the same manner as the position matrix as detailed in [out_mat_r](../input_files/input-main.md#out_mat_r).
-
 Each file or each section of the appended file starts with three lines, the first gives the current ion/md step, the second gives the dimension of the matrix, and the last indicates how many different `R` are in the file.
 
 The rest of the files are arranged in blocks. Each block starts with a line giving the lattice vector `R` and the number of nonzero matrix elements, such as:
@@ -56,10 +45,12 @@ The CSR format stores a sparse m × n matrix M in row form using three (one-dime
   - The arrays V and COL_INDEX are of length NNZ, and contain the non-zero values and the column indices of those values respectively.
   - The array ROW_INDEX is of length m + 1 and encodes the index in V and COL_INDEX where the given row starts. This is equivalent to ROW_INDEX[j] encoding the total number of nonzeros above row j. The last element is NNZ , i.e., the fictitious index in V immediately after the last valid index NNZ - 1.
 
-## get_S
-We also offer the option of only calculating the overlap matrix without running SCF. For that purpose, in `INPUT` file we need to set the value keyword [calculation](../input_files/input-main.md#calculation) to be `get_S`.
+For calculations involving ionic movements, the output frequency of the matrix is controlled by [out_interval](../input_files/input-main.md#out_interval) and [out_app_flag](../input_files/input-main.md#out_app_flag). 
+
+## get_s
+We also offer the option of only calculating the overlap matrix without running SCF. For that purpose, in `INPUT` file we need to set the value keyword [calculation](../input_files/input-main.md#calculation) to be `get_s`.
 
-A file named `SR.csr` will be generated in the working directory, which contains the overlap matrix.
+A file named `sr_nao.csr` will be generated in the working directory, which contains the overlap matrix.
 
 > When `nspin` is set to 1 or 2, the dimension of the overlap matrix is nlocal $\times$ nlocal, where nlocal is the total number of numerical atomic orbitals. 
 These numerical atomic orbitals are ordered from outer to inner loop as atom, angular quantum number $l$, zeta (multiple radial orbitals corresponding to each $l$), and magnetic quantum number $m$. 
@@ -69,9 +60,9 @@ When `nspin` is set to 4, the dimension of the overlap matrix is (2 $\times$ nlo
 ## examples
 We provide [examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/matrix_hs) of outputting the matrices. There are four examples:
 
-- out_hs2_multik : writing H(R) and S(R) for multi-k calculation
-- out_hs_gammaonly : writing H(k) and S(k) for gamma-only calculation
-- out_hs_multik : writing H(k) and S(k) for multi-k calculation
-- out_s_multik : running get_S for multi-k calculation
+- out_hs_gammaonly: writing H(k) and S(k) for gamma-only calculation
+- out_hs_multik: writing H(k) and S(k) for multi-k calculation
+- out_hs2_multik: writing H(R) and S(R) for multi-k calculation
+- out_s_multik: running calculation=get_s to obtain overlap matrix for multi-k calculation
 
 Reference output files are provided in each directory.

docs/advanced/elec_properties/position_matrix.md

@@ -20,5 +20,5 @@ Each block here contains the matrix for the corresponding cell. There are three
 
 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_interval](../input_files/input-main.md#out_interval). For example, if we are running a 10-step MD with out_interval = 3, then `$x` will be 0, 3, 6, and 9.
 
-## 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`.
+## 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`.