🔥 Remove density matrix support from DD package

[burgholzer]

Description

This PR removes the density matrix functionality from the DD package in MQT Core.
It was only ever used in MQT DDSIM and was never really neatly integrated into the DD package; leaving room for improvement.
As a consequence, and in line with the upcoming v4 release, this PR removes the respective functionality and trims down the library.
In the process it applies C++20 concepts and ranges wherever appropriate to simplify the code.

Fixes #337
Resolves #826

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.

[codecov]

Codecov Report

❌ Patch coverage is 99.03846% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/dd/Edge.cpp	92.3%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Removals

  • Density-matrix support removed from the DD package.
  • Stochastic and deterministic noise operations removed.
  • Datastructures sublibrary and related simulator configurations removed.
  • Several noise-related tests and density-matrix-focused tests removed.

• Changes

  • Trace API and related compute/count outputs simplified (density counts removed).
  • State-generation wiring now uses an explicit strategy enum.
  • Various public APIs streamlined to matrix/vector-only usage.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

This PR removes density-matrix (dNode/dEdge) support and stochastic/deterministic noise functionality from the DD package, replaces many SFINAE-based templates with C++20 concepts (IsVector/IsMatrix), and updates related APIs, compute-tables, bindings, and tests to reflect a vector/matrix-only implementation.

Changes

Cohort / File(s)	Summary
Density matrix removal include/mqt-core/dd/Node.hpp, include/mqt-core/dd/Package.hpp, include/mqt-core/dd/Package_fwd.hpp, src/dd/Node.cpp, src/dd/Package.cpp, src/dd/Node.cpp	Removed dNode/density types, density memory/unique tables, density compute tables, density-related flags and helpers, and density fields in public structs.
Noise functionality removal include/mqt-core/dd/NoiseFunctionality.hpp, src/dd/NoiseFunctionality.cpp, include/mqt-core/dd/DensityNoiseTable.hpp, include/mqt-core/dd/StochasticNoiseOperationTable.hpp	Deleted stochastic and deterministic noise APIs, classes, caches, and their tests and helpers.
Concepts / SFINAE → requires include/mqt-core/dd/DDDefinitions.hpp, include/mqt-core/dd/Edge.hpp, include/mqt-core/dd/CachedEdge.hpp, include/mqt-core/dd/MemoryManager.hpp, src/dd/CachedEdge.cpp, src/dd/Edge.cpp	Introduced IsVector/IsMatrix concepts and replaced prior SFINAE/type-trait templates with requires constraints on many Edge/CachedEdge/MemoryManager methods; removed explicit dNode instantiations.
ComputeTable / hashing changes include/mqt-core/dd/ComputeTable.hpp, include/mqt-core/dd/ComputeTable.hpp	Removed useDensityMatrix parameter and density-special-case hashing/lookup logic from compute table APIs.
UniqueTable / equality & iteration include/mqt-core/dd/UniqueTable.hpp	Simplified node equality (removed dNode flag special-case) and updated reverse iteration to use ranges.
Package config / aliases / stats include/mqt-core/dd/DDpackageConfig.hpp, include/mqt-core/dd/Package_fwd.hpp, include/mqt-core/dd/statistics/PackageStatistics.hpp, src/dd/statistics/PackageStatistics.cpp	Removed density-related config members and preset configs; removed DensityMatrixDD alias; removed density entries from statistics and memory accounting.
API adjustments & helpers include/mqt-core/dd/ComputeTable.hpp, include/mqt-core/dd/Approximation.hpp, include/mqt-core/dd/Complex.hpp, include/mqt-core/dd/RealNumber.hpp, include/mqt-core/dd/StateGeneration.hpp	Added small includes, designated initializers, changed RealNumber::eps init, converted GenerationWireStrategy to scoped enum class, and adjusted minor signatures/attributes.
Bindings & OpType bindings/dd/register_matrix_dds.cpp, include/mqt-core/ir/operations/OpType.inc, .clang-tidy	Adjusted Python binding overloads for isIdentity and getValueByIndex; removed several noise-related OpType entries; enabled clang-tidy cppcoreguidelines check.
Tests test/dd/* (multiple files)	Removed noise/density tests, updated tests to new computeActiveCounts shape and GenerationWireStrategy usage, and applied const-correctness tweaks.
Docs / Changelog / Upgrading CHANGELOG.md, UPGRADING.md	Documented removal of density matrix support and datastructures sublibrary and linked PR references.

Sequence Diagram(s)

sequenceDiagram
    rect rgba(200,200,255,0.5)
    participant Caller
    end
    rect rgba(200,255,200,0.5)
    participant Package
    end
    rect rgba(255,200,200,0.5)
    participant ComputeTable
    end
    rect rgba(255,255,200,0.5)
    participant UniqueTable
    end

    Caller->>Package: trace(mEdge a, numQubits)
    Package->>ComputeTable: lookup(leftOperand, rightOperand)
    alt cache hit
        ComputeTable-->>Package: cached mCachedEdge
        Package->>UniqueTable: use cached result / finalize
        UniqueTable-->>Package: node/result
        Package-->>Caller: ComplexValue result
    else cache miss
        ComputeTable-->>Package: miss
        Package->>UniqueTable: compute trace recursively (trace(..., eliminate, level,...))
        UniqueTable-->>Package: computed mCachedEdge
        Package->>ComputeTable: insert(computed)
        Package-->>Caller: ComplexValue result
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Suggested reviewers

• ystade

Poem

🐰 I nudged the dNode out the door,

Noise tales end, the DD's less poor,
Concepts hop in, tidy and spry,
Vectors and matrices reach for the sky,
A clean new trail — thump, thump, goodbye!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.52% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: removing density matrix support from the DD package, which is the primary focus of this PR.
Description check	✅ Passed	The PR description covers the motivation (removal for v4 release, was only used in MQT DDSIM), links to related issues (#337, #826), and the author completed all checklist items including tests, documentation, changelog, and migration instructions.
Linked Issues check	✅ Passed	The PR fully addresses both linked issues: #337 is resolved by eliminating the generateDensityMatrix flag through C++20 concepts and trait-based dispatch; #826 is resolved by removing all density matrix functionality (dNode, dEdge, NoiseFunctionality) and simplifying the DD package.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to removing density matrix support and applying C++20 concepts for simplification. The PR includes documentation updates (CHANGELOG.md, UPGRADING.md), removal of noise functionality, and introduction of IsVector/IsMatrix concepts—all aligned with the stated objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

include/mqt-core/dd/DDDefinitions.hpp (1)

59-65: LGTM!

Using std::numbers::pi is cleaner and more maintainable than the hardcoded literal. Note that PI_2 and PI_4 still use literals—consider updating them to std::numbers::pi / 2 and std::numbers::pi / 4 for consistency if compile-time evaluation is acceptable.

src/dd/Edge.cpp (2)

53-67: Guard against out-of-range decision digits.
Line 65 uses <=, which permits tmp == size and can lead to out-of-bounds access in release builds if a bad digit slips in.

🛠️ Proposed fix

-    assert(tmp <= r.p->e.size());
-    r = r.p->e[tmp];
+    assert(tmp < r.p->e.size());
+    if (tmp >= r.p->e.size()) {
+      return 0.;
+    }
+    r = r.p->e[tmp];

---

439-453: Enforce numQubits > p->v in printMatrix.
Line 452 allows equality even though numQubits is a count, which can mask underspecified calls.

🛠️ Proposed fix

-  assert(isTerminal() || numQubits >= p->v);
+  assert(isTerminal() || numQubits > p->v);