Perf: buffer shared text CSR output and avoid AtomPair copies

[qhuwa]

Reminder

• I have read AGENTS.md and docs/developers_guide/agent_governance.md.
• I have explained why this PR does not need a linked issue.
• I have added focused unit tests.
• I have listed verification commands and results.
• I have described user-visible behavior and INPUT impact.
• I have explained core-module impact.
• No governance exception is needed.

Linked Issue

No linked issue: this is a small, independently scoped optimization of the shared text CSR writer, identified while profiling an ABACUS 3.11-based H0 exporter. No exporter-specific code or numerical changes are included.

What's changed?

• Replace intermediate std::endl calls in SparseMatrix::printToCSR with newline characters. Preserve the final flush, so a completed payload is still visible when the function returns and flush failures still set stream state / throw when enabled.
• Access each AtomPair through const auto& in Output_HContainer::write_single_R. The loop only reads the selected R block; copying the pair also copies its R metadata and potentially all owned matrix blocks.
• Add real/complex regression tests for exact text at precisions 2/8/16, line wrapping, threshold equality, empty matrices, repeated writes, flush count/failure, and container storage/R-index preservation including subsequent gamma folding.

The intended user-visible difference is lower text-output overhead. Bytes, ordering, thresholds, precision, headers, and append conventions are unchanged. Intermediate line-by-line visibility becomes buffered; the final per-payload flush is retained. This does not change stream options such as unitbuf.

Scope: HContainer-backed text H/S, DM, matrix derivatives, asynchronous overlap, Hamiltonian terms, and some DeePKS outputs share these writers. Independent legacy map-based sparse writers and binary serializers are not optimized by this PR. No full-SCF speedup is claimed.

The 3.11 writer was moved to source_base/module_out upstream; this PR uses the current develop layout.

Unit Tests and/or Case Tests for my changes

Built with GCC 10.5, CMake 3.26.4, oneMKL 2024.2, Intel MPI 2021.13, and existing GTest 1.11.0; Release, BUILD_TESTING=ON, ENABLE_MPI=ON, optional Libxc/ELPA/LibRI disabled. OMP_NUM_THREADS=1, MKL_NUM_THREADS=1.

Commands run (test_build denotes the configured MPI build, 8 build CPUs):

cmake --build "$test_build" --parallel "$SLURM_CPUS_PER_TASK" --target \
    MODULE_BASE_sparse_matrix MODULE_BASE_csr_reader \
    MODULE_LCAO_hcontainer_output_test MODULE_LCAO_output_hcontainer_consistency_test
ctest --test-dir "$test_build" --output-on-failure -V \
    -R '^(MODULE_BASE_(sparse_matrix|csr_reader)|MODULE_LCAO_(hcontainer_output_test|output_hcontainer_consistency_test))$'
cmake --build "$test_build" --parallel "$SLURM_CPUS_PER_TASK" --target MODULE_IO_write_hs_r_compat_test
ctest --test-dir "$test_build" --output-on-failure -V \
    -R '^MODULE_IO_(write_hs_r_compat_test|write_hsr_binary_test_parallel)$'
git diff --check
python tools/03_code_analysis/agent_governance_check.py --staged

Results: all 6 CTest entries passed. 41 distinct GoogleTests passed (the two-rank binary gather case skips in the one-process entry and passes on both ranks in its dedicated MPI entry). Existing compatibility tests cover CSR structure headers/readback/append, DM/spin output, legacy sparse and derivative output, and binary real/complex/order/append/MPI behavior. New tests verify exactly one explicit sync per CSR payload.

Initial local setup attempts failed before tests: compute-node CMake was absent, the MPI-disabled build did not register these targets, and the prebuilt GTest needed its matching libstdc++. These were resolved using existing shared tools/libraries; no project build configuration or dependency was changed.

Not run: full SCF, GPU, or DeePKS end-to-end workflows, and a whole-program performance benchmark. Their numerical/operator paths are untouched; DeePKS applicability was inspected at its shared-writer call sites. The dedicated two-rank integration test exercises binary H/S gathering, not text gathering.

Governance Notes

• INPUT/docs changes: none. No parameters, defaults, output format, or interfaces change; no documentation update required.
• Core module impact: only text serialization and read-only AtomPair access in source_base/HContainer. No ESolver, HSolver, ElecState, operator arithmetic, MPI routines, global dependencies, or ownership interfaces change.
• Exceptions requested: none.

[mohanchen]

LGTM