Merge branch 'develop' into parallel_neighlist

Author: 19hello

.coderabbit.yaml

@@ -0,0 +1,47 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: en-US
+
+reviews:
+  auto_review:
+    enabled: true
+    drafts: false
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  path_instructions:
+    - path: "source/**"
+      instructions: |
+        Apply the ABACUS agent governance rules before general style feedback.
+        Focus on newly introduced GlobalV/GlobalC/PARAM dependencies, default
+        parameters in headers, module placement, CMakeLists.txt linkage, C++11
+        compatibility, and focused tests for behavior changes.
+    - path: "source/source_io/module_parameter/**"
+      instructions: |
+        Treat INPUT parameter metadata, parsing, defaults, descriptions, and
+        availability changes as user-visible behavior. Require matching updates
+        to docs/parameters.yaml and docs/advanced/input_files/input-main.md, or
+        a clear no-update explanation in the PR.
+    - path: "docs/**"
+      instructions: |
+        Check that documentation changes match the implementation and do not
+        weaken the rule grading matrix without an explicit rationale.
+    - path: ".github/**"
+      instructions: |
+        Check workflow, PR-template, CodeRabbit, and Copilot instruction
+        changes for consistency with AGENTS.md and
+        docs/developers_guide/agent_governance.md.
+    - path: "tools/03_code_analysis/**"
+      instructions: |
+        Review governance checker changes for false positives, missing
+        diff-scoping, test coverage, and consistency with the GitHub Actions
+        summary output. Prefer deterministic checks for low-noise blockers and
+        leave semantic ownership decisions to AI and human review.
+
+knowledge_base:
+  code_guidelines:
+    enabled: true
+    filePatterns:
+      - "AGENTS.md"
+      - "docs/developers_guide/agent_governance.md"
+      - ".github/copilot-instructions.md"
+      - ".github/instructions/*.instructions.md"

.gitattributes

@@ -1,7 +1,8 @@
-# Shell scripts and the bash-parsed integration-test case lists must keep LF
-# endings so they run under bash, including MSYS2/Git-Bash on Windows where
-# core.autocrlf may rewrite them to CRLF (which breaks `#!/bin/bash` and adds
-# stray \r to parsed lines such as the case names in CASES_*.txt).
+# Text files use LF by default. Windows command scripts keep CRLF because
+# cmd.exe and installer tooling may depend on it.
+* text=auto eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
 *.sh text eol=lf
 CASES_*.txt text eol=lf
 

.github/copilot-instructions.md

@@ -0,0 +1,23 @@
+# ABACUS Copilot Instructions
+
+Before generating code or reviewing pull requests in this repository, follow
+the ABACUS development baseline in:
+
+- `AGENTS.md`
+- `docs/developers_guide/agent_governance.md`
+
+Treat `AGENTS.md` as the short entry point and
+`docs/developers_guide/agent_governance.md` as the complete rule source. Review
+the pull request diff before general style feedback, and separate blocking
+diff-scoped issues from historical or advisory observations.
+
+Use the ABACUS review finding format for actionable findings:
+
+```markdown
+Rule: <rule name>
+Severity: error | warning | info
+Location: <file:line>
+Reason: <specific trigger>
+Suggested action: <concrete next step>
+Exception: allowed | not allowed | human approval required
+```

.github/instructions/abacus-governance.instructions.md

@@ -0,0 +1,33 @@
+---
+applyTo: "**"
+---
+
+# ABACUS Governance Review Instructions
+
+Apply these instructions when reviewing or changing ABACUS code:
+
+- Use `AGENTS.md` and `docs/developers_guide/agent_governance.md` as the
+  authoritative project baseline.
+- Keep review scope diff-oriented: new files, diff-added lines, new includes,
+  newly introduced symbols, and changed text files for line-ending checks.
+- Do not treat untouched historical debt as a default blocker. Mention it only
+  when it affects the changed area, and label it as advisory.
+- Flag newly introduced `GlobalV`, `GlobalC`, or `PARAM` cross-layer control.
+  Prefer explicit dependencies or narrow local interfaces.
+- Flag new default arguments in existing header interfaces. Prefer explicit
+  call-site updates, overloads, or a clearer configuration object.
+- Review header include growth and `.hpp` propagation carefully. These are
+  usually warnings unless the PR records a narrow reason.
+- Require LF line endings for text files. `.bat` and `.cmd` files are the CRLF
+  exceptions.
+- For INPUT parameter behavior changes, require synchronized updates to
+  `docs/parameters.yaml` and `docs/advanced/input_files/input-main.md`, or a
+  clear no-update explanation in the PR.
+- Check that new source files are linked through the relevant `CMakeLists.txt`
+  unless the PR explains generated or indirect inclusion.
+- Keep default C++ changes compatible with the repository C++11 baseline.
+- Ask for focused tests or explicit test rationale for feature changes, bug
+  fixes, INPUT behavior changes, heterogeneous kernels, and core-module
+  refactors.
+- Treat CI governance findings as deterministic evidence and semantic review
+  findings as advisory until maintainers approve them.

.github/pull_request_template.md

@@ -1,17 +1,51 @@
 ### Reminder
-- [ ] Have you linked an issue with this pull request?
-- [ ] Have you added adequate unit tests and/or case tests for your pull request?
-- [ ] Have you noticed possible changes of behavior below or in the linked issue?
-- [ ] Have you explained the changes of codes in core modules of ESolver, HSolver, ElecState, Hamilt, Operator or Psi? (ignore if not applicable)
+- [ ] I have read `AGENTS.md` and `docs/developers_guide/agent_governance.md`.
+- [ ] I have linked an issue or explained why this PR does not need one.
+- [ ] I have added adequate unit tests and/or case tests, or explained why not.
+- [ ] I have listed the exact verification commands run and their results.
+- [ ] I have described user-visible behavior changes, including INPUT parameter changes.
+- [ ] I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other `source/` changes.
+- [ ] I have requested any needed governance exception below.
 
 ### Linked Issue
 Fix #...
 
 ### Unit Tests and/or Case Tests for my changes
 - A unit test is added for each new feature or bug fix.
 
+### Exact Verification Performed
+- Commands run:
+- Result summary:
+- Checks not run, with reason:
+
 ### What's changed?
 - Example: My changes might affect the performance of the application under certain conditions, and I have tested the impact on various scenarios...
 
-### Any changes of core modules? (ignore if not applicable)
-- Example: I have added a new virtual function in the esolver base class in order to ...
+### Governance Checklist
+- Global dependencies: no new `GlobalV`, `GlobalC`, or `PARAM` cross-layer control, or exception requested below.
+- Default parameters: no new default arguments added to existing interfaces, or exception requested below.
+- Headers: no unnecessary header dependencies or `.hpp` propagation, or rationale provided below.
+- Line endings: text files use LF; only `.bat` and `.cmd` use CRLF.
+- Build linkage: new source files are listed in the relevant `CMakeLists.txt`, or rationale provided below.
+- Documentation: behavior/interface changes include documentation updates, or no documentation update is required because ...
+- CodeRabbit: if automatic review has not started and the repository has CodeRabbit installed, request `@coderabbitai review`.
+
+### INPUT Parameter Changes
+- Parameters added/removed/changed:
+- `docs/parameters.yaml` updated: yes/no/not applicable
+- `docs/advanced/input_files/input-main.md` updated: yes/no/not applicable
+- If not updated, explain why no INPUT documentation update is required:
+
+### Core Module Impact
+- Affected core modules:
+- Risk summary:
+- Compatibility or performance impact:
+
+### Governance Exception
+- Rule:
+- Reason:
+- Scope:
+- User or maintenance risk:
+- Why the normal rule cannot be followed now:
+- Follow-up cleanup plan:
+- Requested approver:

.github/workflows/agent_governance.yml

@@ -0,0 +1,55 @@
+name: Agent Governance
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  governance:
+    name: Governance checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run ABACUS governance checker
+        id: governance
+        run: |
+          set +e
+          base_sha="${{ github.event.pull_request.base.sha }}"
+          head_sha="${{ github.event.pull_request.head.sha }}"
+          merge_base="$(git merge-base "$base_sha" "$head_sha")"
+          merge_base_status=$?
+          if [ "$merge_base_status" -ne 0 ]; then
+            {
+              echo "## Agent Governance Check"
+              echo
+              echo "Failed to compute the pull request merge base."
+            } > agent_governance_summary.md
+            exit "$merge_base_status"
+          fi
+          python3 tools/03_code_analysis/agent_governance_check.py \
+            --base "$merge_base" \
+            --head "$head_sha" \
+            --event-path "$GITHUB_EVENT_PATH" \
+            --format markdown | tee agent_governance_summary.md
+          status=${PIPESTATUS[0]}
+          if [ ! -s agent_governance_summary.md ]; then
+            {
+              echo "## Agent Governance Check"
+              echo
+              echo "Checker failed before producing a summary."
+            } > agent_governance_summary.md
+          fi
+          exit "$status"
+
+      - name: Publish governance summary
+        if: always()
+        run: |
+          cat agent_governance_summary.md >> "$GITHUB_STEP_SUMMARY"

.github/workflows/ase_plugin_test.yml

@@ -3,6 +3,10 @@ name: Atomic Simulation Environment (ASE) Plugin Test
 on:
   pull_request:
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   test:
     name: abacuslite
@@ -33,15 +37,24 @@ jobs:
           cd interfaces/ASE_interface
           pip install .
 
+      - name: Install external tools from toolchain
+        run: |
+          sudo apt update && sudo apt install -y xz-utils ninja-build
+          cd toolchain
+          ./install_abacus_toolchain_new.sh --with-dftd4=install --dry-run -j8
+          ./scripts/stage4/install_stage4.sh
+          cd ..
+
       - name: Configure & Build ABACUS (GNU)
         run: |
           git config --global --add safe.directory `pwd`
           export LD_LIBRARY_PATH=${GKLIB_ROOT}/lib:${METIS32_ROOT}/lib:${PARMETIS32_ROOT}/lib:${SUPERLU32_DIST_ROOT}/lib:${PEXSI32_ROOT}/lib:${LD_LIBRARY_PATH}
           export PKG_CONFIG_PATH=${GKLIB_ROOT}/lib/pkgconfig:${METIS32_ROOT}/lib/pkgconfig:${PARMETIS32_ROOT}/lib/pkgconfig:${SUPERLU32_DIST_ROOT}/lib/pkgconfig:${PEXSI32_ROOT}/lib/pkgconfig:${PKG_CONFIG_PATH}
           export CPATH=${GKLIB_ROOT}/include:${METIS32_ROOT}/include:${PARMETIS32_ROOT}/include:${SUPERLU32_DIST_ROOT}/include:${PEXSI32_ROOT}/include:${CPATH}
           export CMAKE_PREFIX_PATH=${PEXSI32_ROOT}:${SUPERLU_DIST32_ROOT}:${PARMETIS32_ROOT}:${METIS32_ROOT}:${GKLIB_ROOT}:${CMAKE_PREFIX_PATH}
+          source toolchain/install/setup
           rm -rf build
-          cmake -B build
+          cmake -B build -G Ninja
           cmake --build build -j2
       
       - name: Install and Soft Link ABACUS

.github/workflows/build_test_cmake.yml

@@ -3,6 +3,10 @@ on:
   push:
   pull_request:
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -13,30 +17,38 @@ jobs:
             build_args: ""
             name: "Build with GNU toolchain"
           - tag: intel
+            external_toolchain_args: "--with-intel"
             build_args: ""
             name: "Build with Intel toolchain"
 
           - tag: gnu
-            build_args: "-DENABLE_LIBXC=1 -DENABLE_MLALGO=1 -DENABLE_LIBRI=1"
+            external_toolchain_args: ""
+            build_args: "-DENABLE_LIBXC=ON -DENABLE_MLALGO=ON -DENABLE_LIBRI=ON"
             name: "Build extra components with GNU toolchain"
           - tag: intel
-            build_args: "-DENABLE_LIBXC=1 -DENABLE_PEXSI=1 -DENABLE_MLALGO=1 -DENABLE_LIBRI=1"
+            external_toolchain_args: "--with-intel"
+            build_args: "-DENABLE_LIBXC=ON -DENABLE_PEXSI=ON -DENABLE_MLALGO=ON -DENABLE_LIBRI=ON"
             name: "Build extra components with Intel toolchain"
 
           - tag: cuda
-            build_args: "-DUSE_CUDA=1"
+            external_toolchain_args: ""
+            build_args: "-DUSE_CUDA=ON"
             name: "Build with CUDA support"
           - tag: gnu
-            build_args: "-DENABLE_LCAO=0"
+            external_toolchain_args: ""
+            build_args: "-DENABLE_LCAO=OFF"
             name: "Build without LCAO"
           - tag: gnu
-            build_args: "-DUSE_ELPA=0 "
+            external_toolchain_args: ""
+            build_args: "-DUSE_ELPA=OFF "
             name: "Build without ELPA"
           - tag: gnu
-            build_args: "-DENABLE_MPI=0"
+            external_toolchain_args: ""
+            build_args: "-DENABLE_MPI=OFF"
             name: "Build without MPI"
           - tag: gnu
-            build_args: "-DENABLE_MPI=0 -DENABLE_LCAO=0"
+            external_toolchain_args: ""
+            build_args: "-DENABLE_MPI=OFF -DENABLE_LCAO=OFF"
             name: "Build without LCAO and MPI"
 
     name: ${{ matrix.name }}
@@ -47,13 +59,22 @@ jobs:
         with:
           submodules: recursive
 
+      - name: Install external tools from toolchain
+        run: |
+          sudo apt update && sudo apt install -y gfortran ninja-build xz-utils
+          cd toolchain
+          ./install_abacus_toolchain_new.sh --with-dftd4=install --dry-run ${{matrix.external_toolchain_args}}
+          ./scripts/stage4/install_stage4.sh
+          cd ..
+
       - name: Build
         run: |
           git config --global --add safe.directory `pwd`
           export LD_LIBRARY_PATH=${GKLIB_ROOT}/lib:${METIS32_ROOT}/lib:${PARMETIS32_ROOT}/lib:${SUPERLU32_DIST_ROOT}/lib:${PEXSI32_ROOT}/lib:${LD_LIBRARY_PATH}
           export PKG_CONFIG_PATH=${GKLIB_ROOT}/lib/pkgconfig:${METIS32_ROOT}/lib/pkgconfig:${PARMETIS32_ROOT}/lib/pkgconfig:${SUPERLU32_DIST_ROOT}/lib/pkgconfig:${PEXSI32_ROOT}/lib/pkgconfig:${PKG_CONFIG_PATH}
           export CPATH=${GKLIB_ROOT}/include:${METIS32_ROOT}/include:${PARMETIS32_ROOT}/include:${SUPERLU32_DIST_ROOT}/include:${PEXSI32_ROOT}/include:${CPATH}
           export CMAKE_PREFIX_PATH=${PEXSI32_ROOT}:${SUPERLU_DIST32_ROOT}:${PARMETIS32_ROOT}:${METIS32_ROOT}:${GKLIB_ROOT}:${CMAKE_PREFIX_PATH}
+          source toolchain/install/setup
           rm -rf build
-          cmake -B build ${{ matrix.build_args }}
-          cmake --build build -j2
+          cmake -B build -G Ninja ${{ matrix.build_args }}
+          cmake --build build -j $(nproc)

.github/workflows/build_test_makefile.yml

@@ -3,6 +3,10 @@ on:
   push:
   pull_request:
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   test:
     runs-on: ubuntu-latest