♻️ Delegate exact circuit execution to MQT Core

[simon1hofmann]

🤖 AI text below 🤖

Description

Consolidate duplicated DD circuit execution as part of
munich-quantum-toolkit/core#2103:

• delegate the exact, uncustomized CircuitSimulator path to MQT Core's shared
  execution kernel;
• retain DDSIM's hook-based path for derived and approximation-enabled
  simulators;
• preserve ordered measurement semantics and correct DD-root ownership across
  repeated and failed simulations; and
• provide mqt.ddsim.sample and mqt.ddsim.simulate_statevector as the new home
  of MQT Core's former high-level helpers.

The deterministic-noise simulator now also releases replaced density roots
between runs. Documentation, migration guidance, and regression tests cover
static and dynamic circuits, repeated measurements and jobs, RNG continuation,
specialized simulator hooks, failure recovery, and the Python helpers.

Part of munich-quantum-toolkit/core#2103

Dependencies and merge order

This PR is stacked on #977 and therefore targets
codex/core-v4-circuit-optimizer. It also depends on
munich-quantum-toolkit/core#2273, which introduces the result-bearing
dd::sample API.

The Core version requirement and lock file intentionally remain unchanged while
Core v4 is unreleased. Keep this PR as a draft until Core v4 is available, #977
is resolved, the dependency metadata is updated, and the complete test suite
passes against the released dependency.

Validation

• 9/9 focused C++ circuit-execution regression tests
• 10/10 Python helper tests against the rebuilt DDSIM extension
• full uvx nox -s lint
• git diff --check

The complete default suite and CI require the future Core v4 dependency pin.

AI assistance

Codex materially assisted with implementation, validation, review, and this pull
request description. A human must review and understand the changes before
marking this pull request ready.

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. Full validation awaits the released Core v4 dependency.
• 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 (v20.1.8) reports: 1 concern(s)

• src/CircuitSimulator.cpp:49:7: error: [clang-diagnostic-error]

  no matching function for call to 'sample'

     49 |       dd::sample(*qc, dd::makeZeroState(qc->getNqubits(), *dd), *dd, shots, mt);
        |       ^~~~~~~~~~
  /home/runner/work/ddsim/ddsim/build/_deps/mqt-core-src/include/mqt-core/dd/Simulation.hpp:94:36: note: candidate function not viable: no known conversion from 'std::mt19937_64' (aka 'mersenne_twister_engine<unsigned long, 64, 312, 156, 31, 13043109905998158313ULL, 29, 6148914691236517205ULL, 17, 8202884508482404352ULL, 37, 18444473444759240704ULL, 43, 6364136223846793005ULL>') to 'std::size_t' (aka 'unsigned long') for 5th argument
     94 | std::map<std::string, std::size_t> sample(const qc::QuantumComputation& qc,
        |                                    ^
     95 |                                           const VectorDD& in, Package& dd,
     96 |                                           std::size_t shots,
     97 |                                           std::size_t seed = 0U);
        |                                           ~~~~~~~~~~~~~~~~~~~~~
  /home/runner/work/ddsim/ddsim/build/_deps/mqt-core-src/include/mqt-core/dd/Simulation.hpp:76:36: note: candidate function not viable: requires at most 3 arguments, but 5 were provided
     76 | std::map<std::string, std::size_t> sample(const qc::QuantumComputation& qc,
        |                                    ^      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     77 |                                           std::size_t shots = 1024U,
        |                                           ~~~~~~~~~~~~~~~~~~~~~~~~~~
     78 |                                           std::size_t seed = 0U);
        |                                           ~~~~~~~~~~~~~~~~~~~~~

Have any feedback or feature suggestions? Share it here.