feat(qcmanybody): support fragment-scoped external potentials

[Awallace3]

Intent

Support fragment-scoped external potentials as a distinct external_potential classification in QCManyBody, without conflating them with embedding charges. They should share unavailable-interaction behavior while preserving the exact historical print_nbody_energy output contract: every pre-existing row must remain byte-for-byte identical, including trailing whitespace, except that literal nan tokens for unavailable interaction energies become N/A at the exact same character offsets. Ordinary interaction-only and supersystem formatting must not move. Omit invalid interaction-energy properties while retaining valid n-body contributions, expose ManyBodyCore.analyze(external_potential=...), and cover the public output and analyze behavior. The user chose to defer a changelog entry. The corresponding Psi4 integration is psi4/psi4#3501; keep the QCManyBody PR communication brief and include that link.

What Changed

• Add external_potential support to ManyBodyCore.analyze as a classification distinct from embedding charges.
• Report unavailable interaction energies as aligned N/A values and omit invalid interaction properties while retaining valid n-body contributions and legacy formatting.
• Add regression coverage for analysis and output behavior. Related Psi4 integration: Scope external potentials by fragment in many-body calculations psi4/psi4#3501

Risk Assessment

✅ Low: The change is well-bounded, preserves legacy output formatting, cleanly propagates the distinct external-potential classification, and retains valid contribution properties while suppressing invalid interaction properties.

Testing

After the system Python lacked pytest, an isolated uv environment ran the focused formatter and public analyze tests successfully; differential checks confirmed legacy rows remain byte-identical and unavailable values replace only nan with N/A at the same offsets, while an end-to-end artifact demonstrates retained n-body contributions, omitted interaction properties, and the rendered N/A columns. Generated environment files were removed afterward.

Evidence: External-potential public API output

Public API exercise
===================
ManyBodyCore.analyze(component_results, external_potential=True)

Returned result property keys:
- cp_corrected_2_body_contribution_to_energy
- cp_corrected_3_body_contribution_to_energy
- cp_corrected_total_energy
- cp_corrected_total_energy_through_1_body
- cp_corrected_total_energy_through_2_body
- cp_corrected_total_energy_through_3_body

Printed energy summary:

   ==> N-Body: Counterpoise Corrected (CP) energies <==

              MC n-Body  Total Energy            Interaction Energy                          N-body Contribution to Interaction Energy
                         [Eh]                    [Eh]                  [kcal/mol]            [Eh]                  [kcal/mol]
              §A  1     -224.890393543755        N/A                   N/A                   0.000000000000        0.000000000000
              §A  2     -224.892193699423        N/A                   N/A                  -0.001800155668       -1.129614735753
     FULL/RTN §A  3     -224.894920257921        N/A                   N/A                  -0.002726558497       -1.710941287990

   MC Legend: §A: "e_scf"


Observed contract:
- valid n-body contribution properties are present
- interaction-energy properties are absent
- unavailable interaction columns display N/A, never nan

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• python -m pytest ... and python3 -m pytest ... — unavailable system test tooling; resolved using the project-local uv environment.
• uv run --extra tests pytest -q qcmanybody/tests/test_utils.py::test_print_nbody_energy_external_potential_without_total_energy qcmanybody/tests/test_utils.py::test_print_nbody_energy_preserves_legacy_spacing qcmanybody/tests/test_core_singlelevel.py::test_external_potential_reporting
• Executed a differential formatter check across 16 ordinary, embedding, external-potential, interaction-only, total-energy, and supersystem scenarios against base commit 1c56881dee567403337cd6da4521ce9639e95d74.
• Executed ManyBodyCore.analyze(component_results, external_potential=True) with water-trimer component data and captured its returned properties and printed energy summary.

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[Awallace3]

Corresponding Psi4 integration: psi4/psi4#3501

[Copilot]

🟢 Approval recommended

The reviewed changes have no unresolved approval-blocking issues.

Pull request overview

Adds fragment-scoped external-potential reporting for the linked Psi4 integration.

Changes:

• Exposes external_potential through ManyBodyCore.analyze.
• Omits unavailable interaction properties while retaining valid contributions.
• Preserves legacy formatting and renders unavailable values as N/A.
• Adds regression coverage.

File summaries

File	Description
qcmanybody/utils.py	Filters invalid properties and formats unavailable interactions.
qcmanybody/tests/test_utils.py	Tests formatting and spacing contracts.
qcmanybody/tests/test_core_singlelevel.py	Tests public analysis behavior.
qcmanybody/core.py	Propagates the external-potential classification.
pyproject.toml	Corrects test discovery paths.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.