Refactor DFT+U occupation matrix reader

[lanshuyue]

Reminder

• I have read AGENTS.md and docs/developers_guide/agent_governance.md.
• No linked issue: this is a focused readability/complexity refactor, with a legacy restart-format compatibility fix found by the new tests.
• Focused unit tests added for legacy collinear headers, legacy SOC, and compact SOC real spin-basis layout.
• Exact verification commands and results are listed below.
• User-visible behavior: legacy Atom=1 restart files emitted by the existing writer now load correctly; Atom= 1 remains supported. No INPUT parameter changes.
• Core impact and governance notes are listed below.

Unit Tests and/or Case Tests for my changes

• source /home/lanshuyue/intel/oneapi/setvars.sh && cmake --build build --target MODULE_PW_dftu_base_test -j4 — passed.
• OMP_NUM_THREADS=1 ctest --test-dir build --output-on-failure -R "^MODULE_PW_dftu_base_test$" — passed (1/1 CTest target; 18/18 Google Tests).
• git diff --check — passed.
• python3 tools/03_code_analysis/code_quality_score.py --format json source/source_pw/module_pwdft/dftu_base_io.cpp — read_occup_m and new helpers have no high-complexity finding (previously read_occup_m had complexity 40). The whole-file score remains 0 because unrelated existing file-level debt and other functions are out of scope.
• python3 tools/03_code_analysis/agent_governance_check.py --base upstream/develop --head HEAD --format text — no blocking findings; migration-neutral global-reference and documentation-review warnings explained below.
• Full ABACUS integration suite not run; this PR changes only the occupation-matrix file reader and has focused unit coverage.

What's changed?

• Separate atom-header parsing and the collinear/legacy-SOC/compact-SOC matrix paths into short file-local helpers; keep the public interface and both PW Pauli and LCAO real spin-basis mappings.
• Check stream extraction for structured numerical input in the touched paths.
• Accept the fused legacy atom token Atom=1 that the existing legacy writer produces, as well as Atom= 1.

Governance Notes

• INPUT/docs changes: none. No new INPUT option or public interface; the legacy reader compatibility fix is covered by tests, so no documentation update is needed.
• Core module impact: DFT+U occupation-matrix restart I/O only. PW and LCAO share this reader; both storage layouts are covered by tests. Existing rank-0 and logging GlobalV references were moved without increase (added=2, removed=2, net=0).
• Exceptions requested: none.

[ABACUS-PR-BOT]

Static review of 33675211e76d60821044d263a9a49c5f45258218 with independent verification: one malformed-input regression and two nonblocking follow-ups below. Governance and whitespace checks passed; builds/tests were not run. CI diagnostics were unavailable.

[ABACUS-PR-BOT]

[P2] Check SOC label reads before comparing the new buffer

With nspin=4, a file ending immediately after Fe Atom 1 L 2 enters skip_compact_soc_label() with this uninitialized buffer. On libstdc++, failed extraction at EOF leaves it untouched, so strcmp reads indeterminate storage before the checked matrix-read error; previously the outer parser had already filled word with L. Please use checked label reads (preferably std::string) and cover this truncated-header case.

[ABACUS-PR-BOT]

Non-blocking: This legacy path still stores a real spin-basis matrix regardless of soc_layout, while PW consumes contiguous Pauli blocks. That limitation predates this refactor, and the new legacy SOC test covers only the real LCAO layout. Please scope the legacy compatibility claim accordingly; a layout-aware conversion and PW test can follow up after merge.

[ABACUS-PR-BOT]

Non-blocking: The new read_required and fused-index rejection branches are not exercised by the added valid-file fixtures. Please add process-exit checks for truncated collinear/legacy SOC data and Atom=1x; this can follow up after the refactor.

[mohanchen]

Current refactor is not ready due to a few reasons. The file is still huge. Please resubmit PR when it is ready.