Skip to content

refactor(ao): replace Parallel_2D inheritance with composition - #8282

Merged
mohanchen merged 24 commits into
deepmodeling:developfrom
kirk0830:pr/03-remove-parallel2d-inheritance
Nov 4, 2026
Merged

mohanchen merged 24 commits into
deepmodeling:developfrom
kirk0830:pr/03-remove-parallel2d-inheritance

Conversation

@kirk0830

@kirk0830 kirk0830 commented Nov 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Replace Parallel_Orbitals's inheritance from Parallel_2D with composition: the
    block-cyclic distribution is a single owned member exposed through para_2d(), and the
    class no longer carries any copy of the distribution state.
  • Migrate the consumers that still read the inherited interface: module_ao, misc_prod
    (output_mulliken, gint_common, unk_overlap_lcao, to_w90_lcao_setup,
    write_proj_band_lcao, test_md_base, test_write_wfc_nao), test_side, and pyabacus.
  • Use an explicit block-cyclic layout in the serial paths and in the optional backends
    instead of relying on the inherited one.

This is one step of dissolving Parallel_Orbitals into self-contained values; see
docs/adr/0001-dissolve-parallel-orbitals.md for the target decomposition.

Notes for reviewers

  • This step is deliberately soft. operator const Parallel_2D&() is kept for now so the
    remaining const call sites (passing a Parallel_Orbitals where a const Parallel_2D& is
    expected) keep compiling. The declaration comment states the exact condition for deleting it,
    and no new call site may rely on it.
  • The merge commit resolves a conflict with Fix: correct My sign in noncollinear Mulliken magnetism #8250 by keeping upstream's extraction of
    collect_MW_nspin4 (which also corrects the noncollinear Mulliken M_y sign) instead of the
    pre-extraction inline loop this branch carried, then routes the helper's accessor calls
    through para_2d(). Taking the branch side here would have silently reverted the M_y fix.
  • No INPUT keyword, no output format, no numerical behavior changes, and no kernel sources are
    touched, so no documentation update is required.

Verification

Run in a detached worktree at the merged branch head; GNU 11.4.0, OMP_NUM_THREADS=1.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_MPI=ON -DBUILD_TESTING=ON \
      -DFFTW3_DIR=/opt/apps/fftw-3.3.10 \
      -DFETCHCONTENT_SOURCE_DIR_GOOGLETEST=<local googletest source>
cmake --build build --target abacus_basic_para -j 8
cmake --build build -j 8 -- -k
ctest --test-dir build -R "^MODULE_AO_parallel_orbitals|^MODULE_IO_mulliken" --output-on-failure
  • abacus_basic_para linked: [100%] Built target abacus_basic_para; identity
    ABACUS version v3.11.0-beta12.
  • Whole default target set (448 targets incl. all unit tests) with keep-going: 0 error:
    lines
    .
  • 100% tests passed, 0 tests failed out of 3 (MODULE_AO_parallel_orbitals_test,
    MODULE_AO_parallel_orbitals_test_para under MPI, MODULE_IO_mulliken_test).
  • Governance checker (--base upstream/develop --head HEAD): 6 warnings, 0 blocking.
    Global dependency budget is 7 added / 7 removed (net 0), i.e. migration-neutral; the added
    references are pre-existing reads moved between call sites.
  • Not run in this environment: the integration-test suite and any CUDA/HIP build (no GPU
    toolchain or build tree available here).

Two follow-ups are intentionally outside this PR: renaming para_2d() to a get_-free
accessor name once no caller needs the alias, and deleting Parallel_2D itself.

Purely additive: no call site changes, inheritance still in place.
para_2d() (const + non-const) returns *this while Parallel_Orbitals derives
from Parallel_2D, giving the two escape hatches a const getter cannot serve
(LR_Util::setup_2d_division mutation, test-side descriptor writes).
get_blacs_ctxt() completes the inherited getter family, which covers the
other seven public data members.
…bitals, migrate module_operator_lcao call sites
…d-inheritance

# Conflicts:
#	source/source_esolver/esolver_ks_lcao_tddft.cpp
#	source/source_hamilt/module_gint/gint_dvlocal.cpp
Resolve the single conflict in output_mulliken.cpp by keeping the upstream
extraction of collect_MW_nspin4 (deepmodeling#8250, which also corrects the noncollinear
M_y sign) instead of the pre-extraction inline loop carried on this branch,
then migrate the helper's accessor calls to the explicit para_2d() distribution
now that Parallel_Orbitals no longer inherits Parallel_2D.
…cessor

The noncollinear Mulliken test added by deepmodeling#8250 sets up a serial layout on a
Parallel_Orbitals and sizes its ComplexMatrix from the distribution's row and
column counts. `set_serial`, `nrow` and `ncol` belong to Parallel_2D, which
Parallel_Orbitals no longer inherits, so route both uses through para_2d().
Without this the test target does not compile on top of current develop.
Replace the PR#TBD placeholders with the actual condition for deleting para_2d()
and the implicit `operator const Parallel_2D&`, and record that the eventual
accessor name carries no get_ prefix, which is the convention this repository
follows. Comment text only.

@ABACUS-PR-BOT ABACUS-PR-BOT left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Static review of 388b4717321c: one optional-build compatibility defect and one nonblocking test suggestion. Findings are based on the full diff and affected source paths; no build or runtime tests were run.

@mohanchen mohanchen added the Refactor Refactor ABACUS codes label Nov 4, 2026
Route optional LCAO backends through the explicit Parallel_Orbitals distribution. This covers CUDA, DeePKS, LibRI/EXX, BSE, RDMFT, RPA, cuBLASMp, and the PEXSI test fixture without changing the composition seam.
@kirk0830

kirk0830 commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator Author

Updated head: 3d6c378d1 after merging upstream/develop at 1c2650796.

This commit completes the explicit para_2d() migration in the remaining optional consumers: CUDA hsolver, DeePKS, LibRI/EXX, BSE, RDMFT, RPA, cuBLASMp, and the PEXSI test fixture. The prior failures in the extra-components, CUDA, and integration builds are addressed at the same composition seam.

Verification with abacus-dev/1.0, OMP_NUM_THREADS=1:

  • cmake --build build-full2 -j 8 with MPI+LCAO+tests+LibXC+LibRI+CUDA: [100%], zero compiler errors.
  • Full CTest: 482/510 passed with no failures; the duplicate GPU macro-integration categories were stopped locally and are covered by the new PR CI run.
  • Staged governance check: 0 blocking findings (2 nonblocking warnings, including the migration-neutral GlobalV line split).

No AGENTS.md, ADR, or working-handoff files are part of the PR diff.

@kirk0830
kirk0830 enabled auto-merge (squash) November 4, 2026 03:00
@kirk0830
kirk0830 requested a review from AsTonyshment November 4, 2026 03:01
@kirk0830

kirk0830 commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator Author

All 18 checks are now green at 45327548d, including both extra-components builds, CUDA build/test, full integration/unit Test, and ASE. Squash auto-merge is enabled.

@AsTonyshment this is ready for the third-layer review when you have a moment.

@kirk0830
kirk0830 disabled auto-merge November 4, 2026 03:35

@AsTonyshment AsTonyshment left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally LGTM, very clean refactor :)

@mohanchen
mohanchen merged commit 757aa0e into deepmodeling:develop Nov 4, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Refactor Refactor ABACUS codes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants