✨ Add QCO density-matrix DD simulation

[simon1hofmann]

🤖 AI text below 🤖

Summary

Adds density-matrix execution as the final QCO DD functionality layer on top of #2079.

• Construct referenced density-matrix DDs from pure states with validated qubit bounds and correct complex conjugation.
• Simulate supported QCO programs as U ρ U†, including dynamic allocation, measurement, reset, classical control, and physically irrelevant global-phase cancellation.
• Deallocate entangled qubits and Qtensors through a physical partial trace while preserving wire mappings.
• Correct normalized partial trace and node renumbering when MatrixDDs omit identity levels.
• Sample pure and mixed density states, deferring terminal measurements while retaining per-shot execution for dynamic and callee-measurement cases.
• Expose make_density_matrix, simulate_density, and sample_density in Python with live-reference/package validation and a documented exact initial-register contract.
• Consume input matrix references consistently on success, failure, and zero-shot paths. Validate density inputs on every path, seed root-call tracking, translate invalid Python arguments to ValueError, and report invalid density probabilities through normal MLIR failures.

This final QCO DD layer follows #1915, #1973, and #2077–#2079.

Validation

• Focused QCO utility binary: 180/180 tests passed.
• DD package tests: 281/281 passed, including 11/11 trace-focused tests.
• Focused Python QCO DD tests: 15/15 passed against rebuilt bindings.
• Commit hooks and git diff --check passed.

GPT-5.6 via Codex materially assisted with implementation, testing, review, and stack restructuring under maintainer direction. Maintainer review remains required.

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.

[burgholzer]

I think it is almost save to say that we can close this for now. Density matrix simulation is not a priority for now and has actually been moved out of the DD package into DDSIM for v4. I believe it does not make too much sense to add it back now for the MLIR part of the code base.
If you agree @simon1hofmann, then let's close this and remove this PR from the existing PR stack.

[simon1hofmann]

I think it is almost save to say that we can close this for now. Density matrix simulation is not a priority for now and has actually been moved out of the DD package into DDSIM for v4. I believe it does not make too much sense to add it back now for the MLIR part of the code base. If you agree @simon1hofmann, then let's close this and remove this PR from the existing PR stack.

Just cross-checked with #2288, but seems like we do not really need it, will close this PR and restack #2288 onto #2079.