Feature: Support native binary output for out_hsr

[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 previously reserved out_hsr 2 format while preserving the existing out_hsr and legacy-alias contracts.

Unit Tests and/or Case Tests for my changes

• Commands run:
  • cmake --build /tmp/abacus_out_hsk_build_mpi --target abacus_basic_para -j1 -- -s
  • ctest --test-dir /tmp/abacus-module-hs-tests --output-on-failure -R 'MODULE_IO_(write_hs_r_compat_test|write_hsr_binary_test_parallel|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_hsr|scf_out_hsr_spin4|scf_out_hsr_binary_spin2)$'
  • /tmp/abacus_out_hsk_build_mpi/abacus_basic_para -h out_hsr
  • /tmp/abacus_out_hsk_build_mpi/abacus_basic_para --check-input from tests/03_NAO_multik/scf_out_hsr_binary_spin2
  • /tmp/abacus_out_hsk_build_mpi/abacus_basic_para --generate-parameters-yaml followed by python3 docs/generate_input_main.py and diff -q against both generated documents
  • python3 -m py_compile tests/integrate/tools/compare_hsr_binary.py
  • bash -n tests/integrate/tools/catch_properties.sh
  • python3 tools/03_code_analysis/agent_governance_check.py --staged --format text
  • git diff --cached --check
• Result summary:
  • Full ABACUS v3.11.0-beta8 build passed.
  • Focused CTest passed 3/3, including the two-rank MPI gather test.
  • Related 03_NAO_multik regression passed 17/17 across text H(R)/S(R), nspin=4, and the new binary nspin=2 case.
  • CLI input validation, generated-document consistency, Python/Shell syntax, and staged-diff checks passed.
  • The governance check exited successfully. Its only warnings cover the existing Input_Conv bridge from PARAM to TD_info; the changed expression enables format 2 and reduces literal global references from three to two (net_delta=-1).
• Checks not run, with reason:
  • The full repository-wide test suite was not run; focused unit/MPI tests and the related integration regression set cover the changed output path.

What's changed?

• Enable out_hsr 2 for native ABI-dependent CSR binary H(R)/S(R) output using .dat filenames.
• Serialize one complete record per ionic step, including sorted and empty R blocks, real or complex values, native column indices, and long long row pointers.
• Preserve MPI gather, gamma-only folding, nspin=1/2/4, append/per-step filenames, sparse threshold, text format 1, NPZ format 3, and legacy aliases.
• Add focused real/complex/empty-block/append/MPI tests plus a multi-k spin-polarized integration case and binary decoder.
• Document the binary record layout and regenerate parameters.yaml and input-main.md from the executable.

Governance Notes

• INPUT/docs changes: out_hsr 2 is now accepted and documented; an optional precision still warns that it applies only to text format 1. Generated INPUT documentation was rebuilt from the final executable.
• Core module impact: limited to source_io H(R)/S(R) serialization and its existing control path. Numerical Hamiltonian construction is unchanged. Input_Conv keeps RT-TDDFT matrix construction enabled for all supported out_hsr formats.
• Exceptions requested: None. The global dependency budget is non-increasing; the remaining PARAM use is the pre-existing Input_Conv compatibility bridge.

[mohanchen]

LGTM