Add SCC convergence diagnostics and benchmark

[QG-phy]

Summary

• expose SCC iteration counts and charge-residual history on SKSCC
• add reset-state regression coverage for the new diagnostics
• add a standalone Carbon BCC k-point, spacing, mixer, and smearing convergence benchmark
• document the SCC numerical validation plan and current k-point observations
• ignore local CodeGraph indexes and include the Si tutorial SK model artifact

Validation

• uv run pytest -q dptb/tests/test_dftb_scc.py -k reset_clears_state
• uv run python examples/dftb_scc/carbon_bcc_scc_convergence/run.py --scan spacing --spacings 0.20 0.10 0.05 --dry-run

Summary by CodeRabbit

• New Features

  • Added a Carbon BCC self-consistent energy-convergence example with k-point, mixer, smearing, and reciprocal-spacing scans.
  • Added optional diagnostic output including energies, charges, convergence status, iteration counts, residuals, and timing.
  • Added a silicon tight-binding model configuration with overlap support and GPU execution settings.

• Bug Fixes

  • SCC calculations now reliably reset and report iteration diagnostics and charge-residual history.

• Documentation

  • Added usage guides, validation criteria, convergence guidance, and example structure documentation.

[github-actions]

This advisory review plan was generated from changed file names using trusted base-branch code.
此审查计划由受信任的 base 分支代码根据变更文件名生成，仅作为维护者辅助。

DeePTB PR Review Plan / DeePTB PR 审查计划

Risk / 风险等级: Medium (中) · Changed files / 变更文件: 9

Why / 风险来源

• Tests changed. / 测试 有变更。
• Examples and configs changed. / 示例和配置有变更。
• Documentation changed. / 文档有变更。
• Some files are unclassified by current risk_map.md. / 部分文件尚未被当前风险地图覆盖。

Recommended Review / 建议审查重点

• Run the Maintainer Review Prompt. / 运行维护者审查 prompt。
• Run the Test Gap Review Prompt. / 运行测试缺口审查 prompt。
• Confirm the changed behavior matches the PR scope. / 确认变更行为和 PR 范围一致。

Detailed risk areas

• Tests (Medium): dptb/tests/test_dftb_scc.py
• Examples and configs (Low): examples/dftb_scc/README.md, examples/dftb_scc/carbon_bcc_scc_convergence/POSCAR, examples/dftb_scc/carbon_bcc_scc_convergence/README.md, examples/dftb_scc/carbon_bcc_scc_convergence/run.py, examples/silicon/tutorial_v2.2/sktb.json
• Documentation (Low): docs/maintenance/scc_numerics_test_plan.md
• Maintenance governance (Low): docs/maintenance/scc_numerics_test_plan.md
• Unclassified by current risk_map.md: .gitignore, dptb/nn/dftb/dftb_scc.py

Human review focus

• Tests: marker choice, regression coverage, skipped environments, and assertions
• Examples and configs: valid JSON, command consistency, and config/schema compatibility
• Documentation: stale commands, stale paths, config consistency, and Sphinx warnings
• Maintenance governance: review guidance consistency and low-noise maintainer workflow

Local commands and hold conditions

Suggested local commands:

• python scripts/ci/check_repository_hygiene.py
• uv run python -m sphinx -b html docs docs/_build/pr-review-plan-html
• uv run pytest ./dptb/tests -m smoke
• uv run pytest ./dptb/tests -m regression

Hold conditions:

• CI failed and the failure is not explained.
• The PR scope is unclear or mixes unrelated changes.
• AI review found a plausible correctness issue that was not fixed or explicitly waived.

Advisory only. / 仅作为审查辅助。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b02c060d-339d-4050-b505-14499f141a9b

📥 Commits

Reviewing files that changed from the base of the PR and between 1dcc7f6 and 75586bf.

📒 Files selected for processing (9)

• .gitignore
• docs/maintenance/scc_numerics_test_plan.md
• dptb/nn/dftb/dftb_scc.py
• dptb/tests/test_dftb_scc.py
• examples/dftb_scc/README.md
• examples/dftb_scc/carbon_bcc_scc_convergence/POSCAR
• examples/dftb_scc/carbon_bcc_scc_convergence/README.md
• examples/dftb_scc/carbon_bcc_scc_convergence/run.py
• examples/silicon/tutorial_v2.2/sktb.json

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The PR adds SCC iteration diagnostics, a Carbon BCC convergence scanner and documentation, a primitive-cell example structure, a Silicon tight-binding configuration, and a .codegraph/ ignore rule.

Changes

SCC convergence workflow

Layer / File(s)	Summary
SCC diagnostic state and validation dptb/nn/dftb/dftb_scc.py, dptb/tests/test_dftb_scc.py	SKSCC records iteration counts and charge residuals, clears them on reset, and tests the recorded state.
Carbon BCC convergence scanner examples/dftb_scc/carbon_bcc_scc_convergence/*, examples/dftb_scc/README.md	The example validates scan inputs, resolves meshes, runs SCC calculations, collects diagnostics, compares energies, and emits table or JSON output.
Numerical validation plan docs/maintenance/scc_numerics_test_plan.md	The plan defines convergence, occupation, Fermi-level, symmetry, SCC, performance, tetrahedron, acceptance, and non-goal criteria.

Silicon model configuration

Layer / File(s)	Summary
Silicon tight-binding model examples/silicon/tutorial_v2.2/sktb.json	The tutorial configuration defines model options and fitted silicon onsite, hopping, and overlap coefficients.

Repository ignore rule

Layer / File(s)	Summary
Codegraph ignore rule .gitignore	The .gitignore file adds the .codegraph/ rule.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 75586

The PR adds SCC convergence diagnostics and benchmark tooling with no actionable merge-blocking correctness, runtime, or deployment risk; it is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant run_case
  participant SKSCC
  participant Output
  CLI->>run_case: scan configuration
  run_case->>SKSCC: run SCC calculation
  SKSCC-->>run_case: energy and residual diagnostics
  run_case->>run_case: compare energy with denser mesh
  run_case-->>Output: table or JSON results

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description gives a useful summary and validation commands but omits most required template sections, including impact, compatibility, AI assistance, and merge decision.	Complete the required template sections and document affected areas, compatibility answers, AI review status, risks, limitations, and merge recommendation.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main SCC diagnostics and convergence benchmark changes.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}