Feature: Support native binary output for out_hsk

[goodchong]

Reminder

• I have read AGENTS.md and docs/developers_guide/agent_governance.md.
• I have linked an issue or explained why this PR does not need one.
• I have added adequate unit tests and/or case tests, or explained why not.
• I have listed the exact verification commands run and their results.
• I have described user-visible behavior changes, including INPUT parameter changes.
• I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other source/ changes.
• I have requested any needed governance exception below.

Linked Issue

No linked issue. This PR implements the requested native binary mode for the existing out_hsk INPUT parameter.

Unit Tests and/or Case Tests for my changes

• Commands run:
  • cmake -S . -B /tmp/abacus_out_hsk_build_mpi -DBUILD_TESTING=ON -DENABLE_LCAO=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=mpicxx
  • cmake --build /tmp/abacus_out_hsk_build_mpi --target MODULE_IO_write_hsk_binary_test MODULE_IO_read_item_serial -j2
  • cmake --build /tmp/abacus_out_hsk_build_mpi --target abacus_basic_para -j2
  • ctest --test-dir /tmp/abacus_out_hsk_build_mpi --output-on-failure -R 'MODULE_IO_(write_hsk_binary_test|read_item_serial)'
  • OMP_NUM_THREADS=1 bash ../integrate/Autotest.sh -a /tmp/abacus_out_hsk_build_mpi/abacus_basic_para -n 2 -o 1 -r '^scf_out_hsk_binary$'
  • OMP_NUM_THREADS=1 bash ../integrate/Autotest.sh -a /tmp/abacus_out_hsk_build_mpi/abacus_basic_para -n 2 -o 1 -r '^scf_out_hsk$'
  • /tmp/abacus_out_hsk_build_mpi/abacus_basic_para --version
  • /tmp/abacus_out_hsk_build_mpi/abacus_basic_para -h out_hsk
  • /tmp/abacus_out_hsk_build_mpi/abacus_basic_para --check-input from tests/03_NAO_multik/scf_out_hsk_binary
  • python3 -m py_compile tests/integrate/tools/compare_hsk_binary.py
  • bash -n tests/integrate/tools/catch_properties.sh
  • git diff --cached --check
  • python3 tools/03_code_analysis/agent_governance_check.py --staged
• Result summary:
  • The serial writer test, two-rank MPI writer test, and INPUT test all passed.
  • The new multi-k binary case and the existing text case each passed all four reference checks.
  • CLI help and --check-input accepted out_hsk 2; the executable reports ABACUS v3.11.0-beta7.
  • Syntax, whitespace, and governance checks passed with no findings.
• Checks not run, with reason:
  • The full repository test suite was not run; verification was focused on the affected INPUT, writer, MPI reduction, and integration paths.
  • One sandboxed MPI integration attempt could not start PMIx because socket creation was restricted. The same command was rerun outside the sandbox and passed.

What's changed?

• Enable out_hsk 2 and route it through the existing native .dat writer without changing text or reserved NPZ behavior.
• Write each record as a native int dimension followed by the row-major upper triangle, using double for Gamma-only matrices and consecutive real/imaginary double values for complex matrices.
• Make append mode truncate on the first ionic step and append complete records on later steps; non-append mode keeps the existing per-step filenames.
• Add focused Gamma, complex/MPI, append/overwrite unit tests and a multi-k integration case that decodes binary H(k)/S(k) and compares against the existing text references.
• Document filenames, record layout, append behavior, and native ABI/endianness limitations.

Governance Notes

• INPUT/docs changes: out_hsk 2 is now accepted; runtime help, docs/parameters.yaml, input-main.md, and hs_matrix.md are synchronized.
• Core module impact: limited to ModuleIO H(k)/S(k) output dispatch and serialization. No ESolver, HSolver, ElecState, Hamilt, Operator, or Psi ownership/algorithm behavior changes.
• Exceptions requested: None.

[mohanchen]

LGTM