[burgholzer]

🤖 AI text below 🤖

Description

MQT DDSIM v3 is a pure Python package powered by MQT Core's native decision-diagram simulation engine. It accepts Qiskit, OpenQASM, compiled QIR programs, and LLVM text/bitcode with profile selection from module metadata.

• Expose one Qiskit sampling_simulator backend through direct SamplingSimulatorBackend() construction. Measurements are explicit; Core owns target validation, execution, and Qiskit result reconstruction.
• Directly re-export Core's sample, simulate, and build_functionality, removing DDSIM's separate submission and raw-buffer extraction helpers. Return uncollapsed statevectors and full unitaries through these functions. QIR Base/Adaptive text and bitcode support sampling and eligible state extraction without a separate format argument; executable QIR does not support full-unitary extraction.
• Directly re-export Core's native DDEstimator without dense extraction. Use backend.sampler() and backend.estimator() for Qiskit V2 sampling primitives; the sampled estimator supports dynamic preparation.
• Remove the superseded native library, hybrid/path/noise/approximation and specialized simulators, the provider, dedicated dense Qiskit backends, legacy primitive adapters, and CLI executables.
• Build with uv_build and verify installed wheels. NumPy comes through Core's Qiskit dependency; no duplicate requirement is needed.
• Provide executable MyST-NB guides with circuit drawings, histograms, state amplitudes, unitary plots, and exact/sampled expectation comparisons. The API guide links Core-owned functions and uses standard autodoc for the DDSIM backend. README requirements and development tooling follow MQT Bench; uv_build remains the chosen build backend. The changelog and upgrade guide explain breaking changes.

Requires Python 3.11+ and Qiskit >=2.5,<3. Development pins merged MQT Core 11b4d3965, including owned dense NumPy results, synchronous QIR simulation, and exact-estimator QCO reuse. The merged Core source tree is identical to the previously tested integration-stack tip. Before publishing MQT DDSIM 3, replace this source-build Git dependency with a suitable Core release and validate its installed wheels on the release-candidate CI matrix.

Local Linux ARM64 validation:

• 19 focused integration tests pass on installed wheels with Python 3.11/Qiskit 2.5.0 and Python 3.14/Qiskit 2.6.1; dependency consistency checks pass.
• Outside-checkout wheel smoke checks pass for device discovery, sampling, primitives, independently checked state/unitary results, and compiled QIR bitcode execution.
• Retained tests cover parameter/PUB ordering, register separation, partial/repeated measurements, feedback/reset, phase, non-unitary rejection, QIR text/bitcode, and compact 64-qubit sampling. Mutation probes detect reversed qubit order, lost phase, and permuted bindings.
• Reduced the suite from 130 tests by removing deleted-API checks and duplicated Core/Qiskit coverage. Format-level QIR fixtures and failure tests now live in Core; DDSIM retains compiled-program and payload end-to-end checks. The Core integration follow-ups remove 390 net lines.
• Repository lint, wheel/sdist builds, and check-sdist pass.
• All four notebooks execute with Sphinx warnings treated as errors. State/unitary and primitive pages were inspected in Chrome with clean console and successful asset requests.
• All new commit signatures verified. Final-head hosted CI and native macOS/Windows validation remain pending.

AI assistance: Codex implemented, reviewed, tested, and documented this migration under user authorization.

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.
• 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.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!