Expose DFTB modes, diagnostics, and ABI-aware integration

[karmachoi]

Summary

• expose concise and programmatic routes for ground-state DFTB, conventional TD-DFTB, SF-TDDFTB, and MRSF-TDDFTB while preserving the legacy job.dftb() MRSF default
• add grouped DFTB calculation, SCC, response, gradient, and operator settings to the OpenQP log
• capture native SCC/Davidson/Z-vector progress safely and place it in the normal OpenQP log
• support the exact historical stable ABI-1 63-argument contract alongside the ABI-2/3 74-argument contract
• negotiate optional native capabilities so old ABI-1/2/3 libraries never claim new trace, all-pair spectrum, or final SCC recovery features that they do not implement
• add minimal examples for all four DFTB calculation families and tighten input/state-label consistency

Why

The OpenQP input surface and logs were centered on MRSF-TDDFTB, making the other DFTB families difficult to select and interpret. The adapter also accepted only newer C layouts, while installed ABI-1 libraries remain useful for their supported feature set. Finally, ABI number alone cannot distinguish older ABI-3 binaries from new binaries that add optional diagnostics without changing the state-gradient call signature.

User impact

• users can select dftb, tddftb, sf-tddftb, or mrsf-tddftb directly
• logs show the resolved method, physical target/reference, loaded dylib, C ABI, capability set, SCC/response/operator options, iterations, residuals, and elapsed times
• stable ABI-1 libraries run basic ground, TD-DFTB, SF/MRSF, QM/MM, relaxed-charge, overlap, SOC, and export workflows through their historical layout
• ABI-1 rejects only later ABI-2 operator/preset controls that cannot be represented; unsupported new capabilities are reported as unavailable rather than silently promised
• incompatible explicit [dftb] type / [tdhf] type combinations fail before calculation

Compatibility

• one OpenQP installation can work with a loaded stable ABI-1, ABI-2, or ABI-3 openqp-dftb library
• missing openqp_dftb_capi_capabilities() means capability mask zero, including for older ABI-3 binaries
• unsafe pre-contract unversioned development layouts are rejected before calling because they lack the stable ABI-1 overlap/SOC marker exports
• native stdout/environment/file-descriptor state is restored after every captured call

Validation

• 211 focused Python tests pass, including exact ABI-1 63-slot and ABI-2/3 74-slot regressions, capability/cache handling, input validation, state labels, and logging
• real authoritative ABI-1 dylib built with Homebrew gfortran-15 + Apple Accelerate:
  • conventional TD-DFTB H2O energy passed through current OpenQP
  • ground gradient, embedded QM/MM gradient/charges, and TD-DFTB S1 energy were also validated
• current ABI-3/capability-7 dylib:
  • conventional H2O spectrum prints S0→S1/S2/S3, S1→S2/S3, and S2→S3
  • DTCAM-TB energy and analytic S1 gradient match the current origin/main baseline
  • pair-space Z-vector reports a physical fixed-point residual of 2.647596e-13
• git diff --check and Python byte-compilation pass

Related work

• companion native implementation: Open-Quantum-Platform/openqp-dftb#15
• packaging/version-only fix remains separate: Open-Quantum-Platform/openqp-dftb#14

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 346084274e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Link the openqp-docs companion PR

This adds user-facing [dftb] controls such as print_level/state_to_state_spectrum and new public DFTB routes, but the commit text only links native openqp-dftb work and no openqp-docs PR. AGENTS.md rule 4 requires user-facing keywords/workflows to be documented in openqp-docs and the PR description to link that companion docs PR, so users will not have manual coverage for these new controls until that docs link/update is added.

Useful? React with 👍 / 👎.