Fix part of 6608: Make IO output self-describing: running-log messages, cube data_desc, and ofs_running parameterization

[mohanchen]

fix part of #6608 fix #8096

Summary

This PR improves the readability and consistency of ABACUS IO output (running log and .cube files) and removes a class of default-argument debt (Rule 5) from the IO layer. The work is split into three themes that build on each other.

1. Running-log messages: label what is being written

The running log previously contained many bare Write data to file: ... lines that did not say what data was written. This PR adds descriptive labels and spin tags so each line is self-describing:

• Sparse matrix outputs (out_mat_h, out_mat_dh, out_mat_*) now report Write H matrix ..., Write dH matrix ..., etc., with per-spin/channel tags where applicable.
• Cube outputs now carry a data_desc string at every call site (charge density, partial charge, effective/electrostatic potential, kinetic energy density, electron localization function, local DOS, wave function norm/real/imag, exciton density). The spin tag is owned by the caller through make_data_desc (cube_io.h) instead of being inferred from is inside write_vdata_palgrid, so spin-summed (is = -1) and 1-based-index callers are labeled correctly. nspin=4 magnetic channels are labeled magnetization density m{x,y,z} (rho[1..3]) and effective magnetic field b{x,y,z} (the B_xc components of the potential) instead of bare "charge density" / "effective potential" for all four channels.
• Removed the pre-write Writing cube file <name> log lines in get_pchg_lcao.cpp / get_wf_lcao.cpp that duplicated the Write ... to file: line now emitted by write_vdata_palgrid.
• H(R) CSR header uses an explicit has_efermi flag instead of string-matching the label, and the running-log banner for Fermi energy is emitted through a single path. The CSR header example in docs/advanced/elec_properties/hs_matrix.md is updated for the , E_Fermi = <value> eV annotation.

Tests:

• test_hsr_writer.cpp gains a text-CSR case covering per-spin Fermi sourced from Efermi; fixed under single-rank __MPI (the Parallel_Orbitals source must call set_atomic_trace before gatherParallels, otherwise get_nnrow_atom throws on nat==0).
• Refreshed hrs*.csr.ref for scf_out_hsr_spin2 to carry the E_Fermi header.
• Fixed Fermi-energy assertions in hsr_writer and output_log unittests.

2. Cube filename normalization

.cube filenames are now lowercase, short, and consistent with the chg.cube / chgs1.cube / pot.cube / wfi1s1k1re.cube family. Indices start from 1 and carry a short suffix indicating their meaning (s = spin, k = k-point, g = geometry step, st = state, i = band index).

• SPIN1_CHG.cube → chgs1.cube (esolver_dm2rho).
• LDOS_<en>eV.cube → ldos_<en>ev.cube (cal_ldos; updated stm.py, catch_properties.sh, result.ref, README; git mv LDOS.cube.ref → ldos.cube.ref).
• Exciton_avg_<type>_state<n>_spin<s>.cube → exc_<type>_st<n+1>_s<s+1>.cube (exciton_plotter; indices now start from 1). The matching .dat slice filename is renamed the same way, and the conditional-slice .dat becomes exc_cond_<type>_slice_st<n+1>.dat so one run no longer mixes Exciton_cond_..._state<N> (0-based) with exc_..._st<N+1> names for the same state.
• chg_init.cpp reads tau from tau.cube / taus1.cube (instead of legacy SPIN1_TAU.cube / SPIN<n>_TAU.cube), aligning with the charge read path. The probe distinguishes nspin==1 vs nspin>1.
• Removed dead std::remove("./support/OLD2_SPIN1_CHG.cube") in test_chg_extra.cpp (no code path generates that file).
• Help text and docs that describe the historical 3.10-LTS filenames (SPIN1_CHG.cube etc.) are intentionally left in place.

3. Parameterize ofs_running through IO output chains (Rule 5)

The IO output layer used to read GlobalV::ofs_running directly in many leaf and mid-level functions. This PR threads std::ofstream& ofs_running explicitly through:

• write_vdata_palgrid (cube_io.h), write_bands / nscf_bands, save_dH_sparse / output_dHR / output_dSR / output_TR / output_SR / output_mat_sparse, cal_ldos_lcao / cal_ldos_pw / stm_mode_pw / ldos_mode_pw, write_elf, write_chg_init / write_pot_init, Get_pchg_pw / Get_wf_pw begin + write_cube helpers, Get_pchg_lcao / Get_wf_lcao begin, ctrl_iter_pw / ctrl_scf_pw / ctrl_runner_pw / ctrl_runner_lcao / ctrl_output_fp, plus their explicit template instantiations (CPU/GPU, double/complex).
• All esolver / non-IO boundary call sites pass GlobalV::ofs_running once at the boundary; the IO layer itself no longer reads the global.

Additionally, two historical default arguments are removed (Rule 5) and every caller now passes the value explicitly:

• cube_io.h: removed data_desc = "data"; all 22 call sites pass a descriptive string (see theme 1).
• write_bands.h: removed nspin0 = 1; 4 test call sites in write_bands_test.cpp now pass 1 explicitly.

Governance notes

• GlobalV dependency: net non-increasing at the PR level. The IO layer no longer reads GlobalV::ofs_running; reads are now concentrated at the esolver/control boundary (one std::ofstream& ofs_running = GlobalV::ofs_running; alias in ctrl_scf_lcao.cpp is a local alias, not a new global read).
• Rule 5: two default arguments removed; all call sites updated. write_cube's ndata_line = 6 remains as pre-existing debt (out of scope here).
• Header includes: 4 <fstream> additions in headers that now carry std::ofstream& parameters; each is required by the new signature.

Test plan

• make -j 30 passes.
• ctest --test-dir build -V -R "rho_io|write_bands|hsr_writer|dhs_sparse|output_mat_sparse|CHARGE_extra" — 8/8 pass (MODULE_CHARGE_extra, MODULE_IO_rho_io, MODULE_IO_write_bands, MODULE_IO_write_bands_parallel, MODULE_IO_hsr_writer_test, MODULE_IO_hsr_writer_test_parallel, MODULE_IO_dhs_sparse_writer_test, MODULE_IO_output_mat_sparse_test).
• python3 tools/03_code_analysis/code_quality_score.py on the 66 changed C++ files at head 2427fe3afe: average 73.5 (pass line 60), 52/66 pass. 14 files below 60 are pre-existing debt (tab_indentation, global_dependency, too_many_parameters) not introduced by this PR: ctrl_scf_lcao.cpp 0, esolver_ks_lcao.cpp 31, ctrl_output_pw.cpp 32, cal_ldos.cpp 33, dhs_sparse_writer.cpp 41, ctrl_output_fp.cpp 43, ctrl_runner_lcao.cpp 50, esolver_ks_pw.cpp 55, cal_ldos.h 55, exciton_plotter.cpp 56, test_chg_extra.cpp 57, esolver_fp.cpp 58, esolver_gets.cpp 58, pos_op_writer.cpp 59.
• CASES_CPU.txt / CASES_GPU.txt (03_NAO_multik): newly enable scf_out_hsr_spin2 — it was previously in neither CI list, and its hrs{1,2}_nao.csr.ref were refreshed in this PR for the E_Fermi header, so CI now covers the new format. Three commented-out placeholders (#scf_out_hsr_npz, #scf_out_hr_npz, #scf_out_dm_npz) are reserved for future npz cases and have no effect.
• catch_properties.sh strips the , E_Fermi = ... eV header annotation (printed with setprecision(6), ~1e-4 eV resolution) before the 1e-8 CSR token comparison, avoiding platform-dependent rounding failures on the header value; matrix tokens still compare at 1e-8.
• Full integrate/regression suite (tests/integrate) — to be run on the CI side; catch_properties.sh updated for the new ldos_<en>ev.cube filename.
• Manual dispatch run required for workflow_dispatch-only workflows (e.g. interface.yml).

[Critsium-xy]

Follow-up review on fa75532.

Verification: ran agent_governance_check.py --base 4c69130 --head fa75532 (0 errors, 46 warnings, GlobalV net delta -5) and code_quality_score.py on the 66 changed C++ files; static cross-check of every write_vdata_palgrid call site, every hrs*.csr.ref, and renamed-filename references across tests/, tools/ and docs/. Not compiled and no tests executed locally, so the make -j 30 / ctest results in the body are unverified here.