Feature: Support native binary output for out_hsk (deepmodeling#7778)

* feat: support native binary out_hsk output

* docs: synchronize generated out_hsk parameter docs

Author: goodchong

docs/advanced/elec_properties/hs_matrix.md

@@ -18,7 +18,7 @@ Use [out_hsk](../input_files/input-main.md#out_hsk) to print the upper triangula
 | --- | --- |
 | `0` | Disabled |
 | `1` | Text; an optional second value controls precision, for example `out_hsk 1 12` |
-| `2` | Reserved for future binary output; not implemented |
+| `2` | Native binary `.dat` output |
 | `3` | Reserved for H(k)/S(k) NPZ output; not implemented |
 
 The legacy keyword `out_mat_hs 1 [precision]` remains supported as an alias for `out_hsk 1 [precision]`. If both names are present, `out_hsk` takes precedence.
@@ -45,6 +45,18 @@ Each output block starts with a comment header containing the one-based ionic-st
 
 For multi-k calculations, the matrices are Hermitian and each matrix element is written as `(real,imag)`. For gamma-only calculations, the matrices are symmetric and the matrix elements are written as real numbers.
 
+### Native Binary Format
+
+For `out_hsk 2`, the filenames in the table above use `.dat` instead of `.txt`. Each matrix record is written without padding or a self-describing header:
+
+1. the matrix dimension as a native C++ `int`;
+2. the upper-triangular elements in row-major order, from `(0,0)` through `(0,N-1)`, then `(1,1)` through `(1,N-1)`, and so on;
+3. each gamma-only element as one native `double`, or each multi-k/spinor element as two consecutive native `double` values containing the real and imaginary parts.
+
+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`.
+
 ## out_hsr
 
 The output of $H(R)$ and $S(R)$ matrices is controlled by [out_hsr](../input_files/input-main.md#out_hsr). It is available for both gamma-only and multi-k LCAO calculations:

docs/advanced/input_files/input-main.md

@@ -2003,7 +2003,7 @@
 - **Description**: Output the upper triangular part of the Hamiltonian and overlap matrices in reciprocal space for each k-point into files in the directory OUT.${suffix}. The first integer selects the format:
   - 0: disabled;
   - 1: text output; the optional second integer controls precision and defaults to 8;
-  - 2: reserved for binary output, which is not implemented yet;
+  - 2: binary output in the native ABACUS .dat format;
   - 3: NPZ output, which is not implemented for H(k)/S(k).
 
   The output is also controlled by out_freq_ion and out_app_flag. For more information, refer to hs_matrix.md.
@@ -2014,6 +2014,8 @@
   - Multi-k, nspin = 1: hk1_nao.txt for the Hamiltonian matrix and sk1_nao.txt for the overlap matrix at the first k-point.
   - Multi-k, nspin = 2: hk1s1_nao.txt and hk1s2_nao.txt for the two spin channels of the Hamiltonian matrix, and sk1_nao.txt for the overlap matrix at the first k-point. Only one overlap matrix is written because it is identical for both spin channels.
   - Multi-k, nspin = 4: hk1s4_nao.txt for the spinor Hamiltonian matrix and sk1_nao.txt for the spinor overlap matrix at the first k-point.
+  For binary output, the same names use the .dat suffix. Each native binary record contains the matrix dimension as an int followed by the row-major upper triangle. Gamma-only elements are doubles; multi-k and spinor elements are pairs of doubles containing the real and imaginary parts. Native integer representation and byte order are used.
+  When out_app_flag is true, the first ionic step truncates the file and later steps append complete records.
   When out_app_flag is false, g followed by the one-based ionic-step index is inserted before _nao, for example hk1s1g1_nao.txt.
 
   > Note: In the 3.10-LTS version, the file names are data-0-H and data-0-S, etc.

docs/parameters.yaml

@@ -3112,7 +3112,7 @@ parameters:
       Output the upper triangular part of the Hamiltonian and overlap matrices in reciprocal space for each k-point into files in the directory OUT.${suffix}. The first integer selects the format:
       * 0: disabled;
       * 1: text output; the optional second integer controls precision and defaults to 8;
-      * 2: reserved for binary output, which is not implemented yet;
+      * 2: binary output in the native ABACUS .dat format;
       * 3: NPZ output, which is not implemented for H(k)/S(k).
 
       The output is also controlled by out_freq_ion and out_app_flag. For more information, refer to hs_matrix.md.
@@ -3122,6 +3122,8 @@ parameters:
       * Multi-k, nspin = 1: hk1_nao.txt for the Hamiltonian matrix and sk1_nao.txt for the overlap matrix at the first k-point.
       * Multi-k, nspin = 2: hk1s1_nao.txt and hk1s2_nao.txt for the two spin channels of the Hamiltonian matrix, and sk1_nao.txt for the overlap matrix at the first k-point. Only one overlap matrix is written because it is identical for both spin channels.
       * Multi-k, nspin = 4: hk1s4_nao.txt for the spinor Hamiltonian matrix and sk1_nao.txt for the spinor overlap matrix at the first k-point.
+      For binary output, the same names use the .dat suffix. Each native binary record contains the matrix dimension as an int followed by the row-major upper triangle. Gamma-only elements are doubles; multi-k and spinor elements are pairs of doubles containing the real and imaginary parts. Native integer representation and byte order are used.
+      When out_app_flag is true, the first ionic step truncates the file and later steps append complete records.
       When out_app_flag is false, g followed by the one-based ionic-step index is inserted before _nao, for example hk1s1g1_nao.txt.
 
       [NOTE] In the 3.10-LTS version, the file names are data-0-H and data-0-S, etc.

source/source_io/module_ctrl/ctrl_scf_lcao.cpp

@@ -199,7 +199,8 @@ void ModuleIO::ctrl_scf_lcao(UnitCell& ucell,
     //------------------------------------------------------------------
     // 4) Output H(k) and S(k) matrices for each k-point
     //------------------------------------------------------------------
-    if (inp.out_hsk[0] == 1)
+    const int hsk_out_type = inp.out_hsk[0];
+    if (hsk_out_type == 1 || hsk_out_type == 2)
     {
         const int precision = inp.out_hsk[1];
         ModuleIO::write_hsk(global_out_dir,
@@ -213,6 +214,7 @@ void ModuleIO::ctrl_scf_lcao(UnitCell& ucell,
                             gamma_only,
                             out_app_flag,
                             istep,
+                            hsk_out_type,
                             precision,
                             GlobalV::ofs_running);
     }

source/source_io/module_hs/write_HS.h

@@ -26,6 +26,7 @@ namespace ModuleIO
 				const bool gamma_only,
 				const bool out_app_flag,
 				const int istep,
+				const int out_type,
 				const int precision,
 				std::ofstream &ofs_running);	
 

source/source_io/module_hs/write_HS.hpp

@@ -21,6 +21,7 @@ void ModuleIO::write_hsk(
         const bool gamma_only,
         const bool out_app_flag,
         const int istep,
+        const int out_type,
         const int precision,
         std::ofstream &ofs_running)    
 {
@@ -40,25 +41,21 @@ void ModuleIO::write_hsk(
     for (int ik = 0; ik < nks; ++ik)
     {
         p_hamilt->updateHk(ik);
-        bool bit = false; // LiuXh, 2017-03-21
-        // if set bit = true, there would be error in soc-multi-core
-        // calculation, noted by zhengdy-soc
+        const bool binary = (out_type == 2);
 
         hamilt::MatrixBlock<T> h_mat;
         hamilt::MatrixBlock<T> s_mat;
 
         p_hamilt->matrix(h_mat, s_mat);
 
-        const int out_label=1; // 1: .txt, 2: .dat
-
         std::string h_fn = ModuleIO::filename_output(global_out_dir,
                 "hk","nao",ik,ik2iktot,nspin,nkstot,
-                out_label,out_app_flag,gamma_only,istep);
+                out_type,out_app_flag,gamma_only,istep);
 
         ModuleIO::save_mat(istep,
                 h_mat.p,
                 PARAM.globalv.nlocal,
-                bit,
+                binary,
                 precision,
                 1,
                 out_app_flag,
@@ -77,14 +74,14 @@ void ModuleIO::write_hsk(
 
         std::string s_fn = ModuleIO::filename_output(global_out_dir,
                 "sk","nao",ik,ik2iktot,nspin,nkstot,
-                out_label,out_app_flag,gamma_only,istep);
+                out_type,out_app_flag,gamma_only,istep);
 
         ofs_running << " The output filename is " << s_fn << std::endl;
 
         ModuleIO::save_mat(istep,
                 s_mat.p,
                 PARAM.globalv.nlocal,
-                bit,
+                binary,
                 precision,
                 1,
                 out_app_flag,
@@ -123,7 +120,8 @@ void ModuleIO::save_mat(const int istep,
 
         if (drank == 0)
         {
-            out_matrix = fopen(filename.c_str(), "wb");
+            const char* mode = (app && istep > 0) ? "ab" : "wb";
+            out_matrix = fopen(filename.c_str(), mode);
             if (out_matrix == nullptr)
             {
                 ModuleBase::WARNING_QUIT("ModuleIO::save_mat", "Cannot open matrix file: " + filename);
@@ -184,7 +182,8 @@ void ModuleIO::save_mat(const int istep,
         }
 // write .dat file without MPI
 #else
-        FILE* out_matrix = fopen(filename.c_str(), "wb");
+        const char* mode = (app && istep > 0) ? "ab" : "wb";
+        FILE* out_matrix = fopen(filename.c_str(), mode);
         if (out_matrix == nullptr)
         {
             ModuleBase::WARNING_QUIT("ModuleIO::save_mat", "Cannot open matrix file: " + filename);

source/source_io/module_parameter/read_input_item_output.cpp

@@ -534,7 +534,7 @@ Also controled by out_freq_ion and out_app_flag.
         item.description = R"(Output the upper triangular part of the Hamiltonian and overlap matrices in reciprocal space for each k-point into files in the directory OUT.${suffix}. The first integer selects the format:
 * 0: disabled;
 * 1: text output; the optional second integer controls precision and defaults to 8;
-* 2: reserved for binary output, which is not implemented yet;
+* 2: binary output in the native ABACUS .dat format;
 * 3: NPZ output, which is not implemented for H(k)/S(k).
 
 The output is also controlled by out_freq_ion and out_app_flag. For more information, refer to hs_matrix.md.
@@ -544,6 +544,8 @@ The output is also controlled by out_freq_ion and out_app_flag. For more informa
 * Multi-k, nspin = 1: hk1_nao.txt for the Hamiltonian matrix and sk1_nao.txt for the overlap matrix at the first k-point.
 * Multi-k, nspin = 2: hk1s1_nao.txt and hk1s2_nao.txt for the two spin channels of the Hamiltonian matrix, and sk1_nao.txt for the overlap matrix at the first k-point. Only one overlap matrix is written because it is identical for both spin channels.
 * Multi-k, nspin = 4: hk1s4_nao.txt for the spinor Hamiltonian matrix and sk1_nao.txt for the spinor overlap matrix at the first k-point.
+For binary output, the same names use the .dat suffix. Each native binary record contains the matrix dimension as an int followed by the row-major upper triangle. Gamma-only elements are doubles; multi-k and spinor elements are pairs of doubles containing the real and imaginary parts. Native integer representation and byte order are used.
+When out_app_flag is true, the first ionic step truncates the file and later steps append complete records.
 When out_app_flag is false, g followed by the one-based ionic-step index is inserted before _nao, for example hk1s1g1_nao.txt.
 
 [NOTE] In the 3.10-LTS version, the file names are data-0-H and data-0-S, etc.)";
@@ -576,10 +578,6 @@ When out_app_flag is false, g followed by the one-based ionic-step index is inse
             {
                 ModuleBase::WARNING_QUIT("ReadInput", "out_hsk format must be 0, 1, 2, or 3");
             }
-            if (format == 2)
-            {
-                ModuleBase::WARNING_QUIT("ReadInput", "out_hsk binary output is reserved but not implemented");
-            }
             if (format == 3)
             {
                 ModuleBase::WARNING_QUIT("ReadInput", "out_hsk NPZ output is not implemented");

source/source_io/test/CMakeLists.txt

@@ -53,6 +53,18 @@ AddTest(
   SOURCES binstream_test.cpp ../module_output/binstream.cpp
 )
 
+AddTest(
+  TARGET MODULE_IO_write_hsk_binary_test
+  LIBS parameter base device
+  SOURCES write_hsk_binary_test.cpp ../../source_basis/module_ao/parallel_orbitals.cpp
+)
+
+add_test(
+  NAME MODULE_IO_write_hsk_binary_test_parallel
+  COMMAND mpirun -np 2 ./MODULE_IO_write_hsk_binary_test
+  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+)
+
 AddTest(
   TARGET MODULE_IO_write_eig_occ_test
   LIBS parameter  base device symmetry