Add unified H/S matrix output options and gamma-only H(R)/S(R) output

[goodchong]

Summary

This PR contains five focused changes:

1. Correct the H(k)/S(k) filename documentation while keeping the complete mapping for gamma-only and multi-k calculations with nspin = 1, 2, and 4, including spin-independent overlap files and ionic-step suffixes.
2. Remove the temporary standalone filename unit test and standalone integration case while retaining coverage in the existing matrix-output tests.
3. Add gamma-only folded H(R)/S(R) output. The internal HContainer is written directly as one R = (0, 0, 0) block, with an explicit folded-representation comment in text CSR output.
4. Add the primary out_hsk and out_hsr format controls. Values are 0 for disabled, 1 for text, 2 for reserved binary output, and 3 for NPZ (out_hsr only). out_mat_hs, out_mat_hs2, and out_hsr_npz remain compatible aliases; explicit new options take precedence regardless of INPUT order.
5. Address review feedback by renaming spin-independent S(R) output to sr_nao, adopting one-based NAO names for H/S NPZ files, correcting get_s, and documenting H(k)/S(k) as reciprocal-space matrices and H(R)/S(R) as real-space matrices indexed by the Bravais lattice vector R.

The INPUT help, parameters.yaml, generated input-main.md, H/S matrix guide, migration guide, TB2J/DeepH interface documentation, examples, reference files, and integration checks are synchronized with the output contract below.

Matrix output filenames

H(k)/S(k) text output:

• Gamma-only, nspin = 1: hk_nao.txt, sk_nao.txt
• Gamma-only, nspin = 2: hks1_nao.txt, hks2_nao.txt, sk_nao.txt
• Multi-k, nspin = 1: hk${k}_nao.txt, sk${k}_nao.txt
• Multi-k, nspin = 2: hk${k}s1_nao.txt, hk${k}s2_nao.txt, sk${k}_nao.txt
• Multi-k, nspin = 4: hk${k}s4_nao.txt, sk${k}_nao.txt

Here ${k} is the one-based k-point index. When out_app_flag is false, g${step} is inserted before _nao, where ${step} is the one-based ionic-step index.

H(R)/S(R) text CSR output:

• nspin = 1: hrs1_nao.csr, sr_nao.csr
• nspin = 2: hrs1_nao.csr, hrs2_nao.csr, sr_nao.csr
• Multi-k nspin = 4: hrs1_nao.csr, sr_nao.csr
• With non-append ionic-step output, S(R) is written as srg${step}_nao.csr; append/regular output uses sr_nao.csr
• calculation get_s writes OUT.${suffix}/sr_nao.csr

H(R)/S(R) NPZ output:

• H(R): hrs1_nao.npz; nspin = 2 additionally writes hrs2_nao.npz
• S(R): sr_nao.npz
• These names apply to out_hsr 3, legacy out_hsr_npz 1, and independent H-only out_hr_npz 1
• Legacy output_HR0.npz, output_HR1.npz, and output_SR.npz copies are not generated

Behavior

• Multi-k H(R)/S(R) output retains the stored R-resolved HContainer blocks.
• Gamma-only text and NPZ output write the folded internal HContainer, so only R = (0, 0, 0) is present.
• Folded output cannot recover the original R-resolved contributions or interpolate arbitrary k points. Terms added only while constructing H(k) are not guaranteed to be included.
• Gamma-only nspin = 4 remains unsupported. Existing gamma-only restrictions for out_hr_npz, out_mat_r, out_mat_t, and DM(R) NPZ remain unchanged.

Tests

• C++11 targets built successfully in both normal and ENABLE_CNPY=ON build trees:
  • cmake --build build_repro_hs2 --target abacus_basic_para MODULE_IO_read_item_serial MODULE_IO_read_input_serial MODULE_IO_input_help_test MODULE_IO_write_hs_r_compat_test -j2
  • cmake --build build_repro_hs2_cnpy --target abacus_basic_para MODULE_IO_read_item_serial MODULE_IO_read_input_serial MODULE_IO_input_help_test MODULE_IO_write_hs_r_compat_test -j2
• The four requested unit tests passed in both build trees:
  • ctest --test-dir build_repro_hs2 --output-on-failure -R '^(MODULE_IO_read_item_serial|MODULE_IO_read_input_serial|MODULE_IO_input_help_test|MODULE_IO_write_hs_r_compat_test)$'
  • ctest --test-dir build_repro_hs2_cnpy --output-on-failure -R '^(MODULE_IO_read_item_serial|MODULE_IO_read_input_serial|MODULE_IO_input_help_test|MODULE_IO_write_hs_r_compat_test)$'
• OMP_NUM_THREADS=1 ../integrate/Autotest.sh -a /home/goodchong/abacus-develop/build_repro_hs2/abacus_basic_para -n 2 -o 1 -r '^scf_out_hk_spin2$' passed 11 checks.
• OMP_NUM_THREADS=1 ../integrate/Autotest.sh -a /home/goodchong/abacus-develop/build_repro_hs2/abacus_basic_para -n 2 -o 1 -r '^(scf_out_hsr|scf_out_hsr_spin4|nscf_out_hsr_tr_rr|get_s)$' passed 16 checks.
• OMP_NUM_THREADS=1 ../integrate/Autotest.sh -a /home/goodchong/abacus-develop/build_repro_hs2_cnpy/abacus_basic_para -n 2 -o 1 -f CASES_CNPY.txt -r '^(scf_out_hsr_npz|scf_out_hr_npz)$' passed 7 checks. After deleting previous generated NPZ files, the new NAO names were present and the legacy NPZ names were absent.
• A temporary Gamma-only spin-2 CNPY run with out_hsr 3 produced non-empty hrs1_nao.npz, hrs2_nao.npz, and sr_nao.npz. Each file contained three matrix keys, all ending in _0_0_0.
• build_repro_hs2/abacus_basic_para --generate-parameters-yaml > /tmp/abacus-parameters-review.yaml, python3 docs/generate_input_main.py /tmp/abacus-parameters-review.yaml --output /tmp/abacus-input-main-review.md, and cmp against both checked-in generated files passed.
• python3 tools/03_code_analysis/agent_governance_check.py --base 39c688ea76d417d2b471189a3c3b99e9fb4f855b --head HEAD --format text completed with four migration-neutral warnings and an overall global-dependency delta of -2.
• git diff --check 39c688ea76d417d2b471189a3c3b99e9fb4f855b HEAD passed.

[goodchong]

The motivation for modifying the input parameters is that users find it difficult to understand them based on their names alone:

out_mat_hs represents H(k)/S(k);
out_mat_hs2 represents H(R)/S(R);
out_hr_npz and out_hsr_npz are yet another set of formats.

[mohanchen]

LGTM