[kirk0830]

Key design: the atom basis function layout (ityp, iat, l, izeta, m) := mu is not necessary to be coupled with the block-cyclic distribution mechanism: one is about the matrix layout, the other is about how matrix is distributed

Summary

• Continue the longer Parallel_Orbitals dissolution plan by passing the block-cyclic basis and matrix layouts explicitly instead of relying on implicit inheritance or forwarding.
• Introduce BasisFlattenedIndexing and AtomBasisView as a single basis-indexing boundary shared by HContainer, LCAO operators, and their consumers.
• Migrate Hamiltonian, TDDFT, LR/BSE, density-matrix, HS I/O, solver, and MD test paths to use explicit para_2d() layouts.
• Remove the obsolete per-element LCAO offset-vector path.
• Fix issue Rename block_cyclic_distribution and normalize its BLACS constants #8299.

The PR-scoped diff is limited to this refactor. Upstream synchronization added no CSR-reader, workflow, documentation, or repository-local agent-memory changes to the PR.

Behavior

No INPUT, output-format, numerical, or public workflow behavior changes. Documentation updates are not required because this is an internal ownership and interface refactor; the affected contracts are documented inline.

Regression coverage

The first revision of this PR retained a duplicate inline nspin=4 Mulliken path that bypassed the already corrected collect_MW_nspin4 helper. Existing unit tests exercised only the helper, so they did not cover the production Output_Mulliken::collect_MW() path where the regression occurred. Integration and CUDA CI caught the resulting spin2/spin4 sign reversal.

The new OutputMullikenSpinTest.Nspin4ProductionPathPreservesMySign test calls Output_Mulliken::collect_MW() directly. It fails with the old implementation (My=-1 instead of +1) and passes after restoring the corrected helper path.

Verification

The final rename and interface-cleanup state was verified at adbb91943 with abacus-dev/1.0, GNU 11.4.0, and OMP_NUM_THREADS=1:

cmake --build build -j 8
ctest --test-dir build --output-on-failure \
  -R "MODULE_BASE_parallel_blkcyc|MODULE_LCAO_tddft_boundary_fix_test|MODULE_IO_mulliken_test|MODULE_IO_output_mat_sparse_test|MODULE_LR_state_ovlp|MODULE_LR_state_track|MODULE_LR_spectrum_mo_output_test"

cmake --build build-exx -j 8
ctest --test-dir build-exx --output-on-failure \
  -R "MODULE_BASE_parallel_blkcyc|MODULE_LCAO_tddft_boundary_fix_test|MODULE_IO_mulliken_test|MODULE_IO_output_mat_sparse_test|MODULE_LR_state_ovlp|MODULE_LR_state_track|MODULE_LR_spectrum_mo_output_test"

git diff --check upstream/develop..HEAD
python3 tools/03_code_analysis/agent_governance_check.py \
  --base upstream/develop --head HEAD --format text

• adbb91943: default CPU+MPI+LCAO+testing build [100%]; 9/9 focused tests passed, including MODULE_BASE_parallel_blkcyc and its four-rank MPI test.
• adbb91943: LibRI/LibXC build [100%]; the same 9/9 focused tests passed.
• 1fd814ea2: pre-rename production integration case scf_out_mul_spin4 passed with both 1 and 4 MPI ranks.
• adbb91943: governance check has no blockers and git diff --check is clean.
• CI at adbb91943 covers CUDA, Makefile/Intel builds, no-LCAO configurations, and the remaining toolchain matrices.

Auto-merge is intentionally disabled.

[ABACUS-PR-BOT]

The new governance regression expects an unimplemented checker rule and needs to be aligned with the checker. The other inline notes are non-blocking cleanup.

Static review at 1fd814e: git diff --check and the governance checker completed successfully (warnings only). Builds, numerical/runtime tests and CI diagnostics were not run.

[kirk0830]

@ABACUS-PR-BOT All problems have been solved, could you review again?

[AsTonyshment]

LGTM overall!

Just a heads-up: our current guidance on forward declarations is a bit contradictory. The ABACUS C++ guide recommends avoiding them, while agent_governance_check.py and even the review bot recommend the opposite.

This is also a debated topic in software engineering, with major projects taking different approaches. For example, Google generally discourages forward declarations, while LLVM encourages minimizing header inclusions and using forward declarations where appropriate. It's essentially a trade-off between maintainability (e.g., explicit dependencies and avoiding fragile declarations) and compile-time efficiency (e.g., reduced header coupling and unnecessary recompilation).

We're planning to put together an updated version of the ABACUS development guidelines to clear up inconsistencies like this. No need to change anything here over this, though :) I'm just pointing it out, and we can leave the discussion of whether forward declarations are preferable for another time.

[kirk0830]

@AsTonyshment Thanks for your review.
As for the forward declaration and header only, I can share part of my opinions here: personally, I use forward declaration with much care, and I think it should not be allowed in a wide range presently, because it may hide the real design problem, especially hide the coupling between modules. Even for now AI can help me code many, I still spend much time on answering questions from myself about:

1. What is this name indicates?
2. What it (a class/variable/struct/...) IS?

As for the compile time management, I am not sure about the preference of other developers, so I cannot give a clear suggestion.

C++ provides many language features allowing developers coding in many different ways, but maintainers should be cautious on this feature before the code is "dry" or atomic enough.

Cheers,
Yike

[ABACUS-PR-BOT]

Both verification filters omit the renamed layout tests; the inline note identifies the update.

Static incremental review at adbb919: full and incremental git diff --check passed. Builds, runtime tests, numerical probes and CI diagnostics were not run; the reported test counts remain author-reported.

[kirk0830]

@AsTonyshment update: to enhance the readability of the forward declaration I have to make at the intermediate stage of the big refactor, I append the inline comments to point to the place where the classes are really declared. In the next PR, the number of forward declaration used will be decreased significantly because of the introduction of Matrix2d container.

[mohanchen]

not only the file name, I would suggest when using parallel scheme, the input parameter name starts from Parallel_*

[kirk0830]

Thanks, but what about the naming of this scheme? Will Parallel_Block_Cyclic be a good choice? Or maybe there is also a rule now about confining the number of words to be not more than two, such as Parallel_Blkcyclic/Parallel_BlkCyclic/Parallel_Blkcyc/Parallel_BlkCyc ?