♻️ Consolidate DD circuit execution

[simon1hofmann]

🤖 AI text below 🤖

Description

Consolidate decision-diagram circuit execution in MQT Core while keeping DDSIM
as the owner of the public simulator abstraction:

• add a package-aware dd::sample primitive that returns counts, retained
  state, and execution count while continuing a caller-owned random-number
  generator;
• use one execution implementation for unitary operations, virtual swaps,
  measurements, resets, classical control, permutations, garbage, and global
  phase;
• preserve the retained Core QDMI device without adding a Core dependency on
  DDSIM;
• move the high-level Python sample and simulate_statevector helpers to
  DDSIM;
• make virtual-operation helpers internal and document the public API
  migrations; and
• add coverage for static and dynamic circuits, repeated execution, seeding,
  measurement assignments, layouts, output permutations, ownership, and
  failures.

Fixes #2103

Downstream migrations

• DDSIM: ♻️ Delegate exact circuit execution to MQT Core ddsim#978
• ProblemSolver: 🚚 Move DD sampling to MQT DDSIM problemsolver#529

DDSIM remains stacked on its existing Core-v4 migration. ProblemSolver retains
its Core 3.x import on Python 3.10 and uses DDSIM on Python 3.11 and newer.
QCEC and SyReC keep their existing Core-only C++ integrations.

Validation

• Core DD suite: 292 tests passed
• Core QDMI DD device: 51 tests passed
• Core stub generation passed
• focused Core Python tests passed on Python 3.11 through 3.14
• full Core lint session passed
• DDSIM integration against this Core branch: 9 C++ and 10 Python tests passed
• ProblemSolver source formatting and lint checks passed
• changed documentation passed Markdown and source-level checks
• full local Sphinx generation was blocked by pre-existing generated-namespace
  and stale-library environment failures; CI remains pending

AI assistance

Codex materially assisted with the cross-repository design, implementation,
tests, validation, independent review, migration work, and this pull request
description. A human must review and understand the changes before merge.

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks. Local validation passes; CI is pending.
• I have reviewed my own code changes.

If PR contains AI-assisted content:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[github-actions]

Cpp-Linter Report ⚠️

Some files did not pass the configured checks!

clang-tidy (v22.1.8) reports: 2 concern(s)

• test/dd/test_dd_functionality.cpp:30:1: warning: [misc-include-cleaner]

  included header complex is not used directly

     30 | #include <complex>
        | ^~~~~~~~~~~~~~~~~~
     31 | #include <cstddef>

• test/dd/test_dd_functionality.cpp:579:20: warning: [misc-include-cleaner]

  no header providing "std::abs" is directly included

     32 |   EXPECT_NEAR(std::abs(amplitudes.at(2U)), 1., 1e-12);
        |                    ^

Have any feedback or feature suggestions? Share it here.

[codecov]

Codecov Report

❌ Patch coverage is 97.59036% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/dd/Simulation.cpp	97.4%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[burgholzer]

Hm. I am honestly a bit skeptical about the changes here.
It is quite convenient to have a full circuit/unitary simulator available in the core package. So that it can easily be used.
However, we currently maintain three different simulation drivers

• built on MQT::CoreIR in the DD module
• the QIR runtime
• the MLIR simulator

I am not 100% what the desired end-goal is, but I agree that the current one is maybe a little much.
If we could tweak to understand terminal measurements so that sampling would be efficient, the most efficient long-term solution would likely be to compile everything to QIR before simulation and using the DDSIM QDMI device as the sole execution engine.

Just some thoughts though. Probable needs to be consolidated a bit more.

[simon1hofmann]

Hm. I am honestly a bit skeptical about the changes here. It is quite convenient to have a full circuit/unitary simulator available in the core package. So that it can easily be used. However, we currently maintain three different simulation drivers

• built on MQT::CoreIR in the DD module
• the QIR runtime
• the MLIR simulator

I am not 100% what the desired end-goal is, but I agree that the current one is maybe a little much. If we could tweak to understand terminal measurements so that sampling would be efficient, the most efficient long-term solution would likely be to compile everything to QIR before simulation and using the DDSIM QDMI device as the sole execution engine.

Just some thoughts though. Probable needs to be consolidated a bit more.

That makes the most sense long term, but I thought that would be too big of a change for this PR.

Should we keep the shared Core kernel and DDSIM delegation, restore Core’s high-level sample and simulate_statevector convenience wrappers and create an issue for QIR/QDMI-only execution?

Could also do that directly here, but would a bit more work.

[burgholzer]

That makes the most sense long term, but I thought that would be too big of a change for this PR.

Should we keep the shared Core kernel and DDSIM delegation, restore Core’s high-level sample and simulate_statevector convenience wrappers and create an issue for QIR/QDMI-only execution?

Could also do that directly here, but would a bit more work.

Hm. Tough question. I feel like the general simulate and sample APIs in MQT Core could be quite useful also mid-term. They could, later, even delegate to the MLIR-based or the QIR-based simulator. In my opinion, this largely depends on how much we want to push for entirely replacing qc::QuantumComputation throughout the MQT (particularly DDSIM, QCEC, maybe QMAP).
I am having a hard time at the moment formulating out a clear plan for this. May need some more brainstorming.
I think the key thing for me is: we want to maintain an easy way to do classical simulation in MQT Core. qc::QuantumComputation is not a priority. So maybe this is entirely covered by the DDSIM QDMI device and we just need to provide convenient enough interfaces for people to use it as a replacement for mqt.core.dd.
Sorry for not being able to come up with a clearer picture here.

[simon1hofmann]

That makes the most sense long term, but I thought that would be too big of a change for this PR.
Should we keep the shared Core kernel and DDSIM delegation, restore Core’s high-level sample and simulate_statevector convenience wrappers and create an issue for QIR/QDMI-only execution?
Could also do that directly here, but would a bit more work.

Hm. Tough question. I feel like the general simulate and sample APIs in MQT Core could be quite useful also mid-term. They could, later, even delegate to the MLIR-based or the QIR-based simulator. In my opinion, this largely depends on how much we want to push for entirely replacing qc::QuantumComputation throughout the MQT (particularly DDSIM, QCEC, maybe QMAP). I am having a hard time at the moment formulating out a clear plan for this. May need some more brainstorming. I think the key thing for me is: we want to maintain an easy way to do classical simulation in MQT Core. qc::QuantumComputation is not a priority. So maybe this is entirely covered by the DDSIM QDMI device and we just need to provide convenient enough interfaces for people to use it as a replacement for mqt.core.dd. Sorry for not being able to come up with a clearer picture here.

Then let's keep this open for now until we further consolidate the MLIR DD PRs and the other open stacks. Happy to discuss this further next week to come up with a better plan.