♻️ Remove CircuitOptimizer

[simon1hofmann]

🤖 AI text below 🤖

Description

Remove the standalone qc::CircuitOptimizer API and MQT::CoreCircuitOptimizer library:

• move circuit flattening and final-measurement removal to QuantumComputation member methods in MQT::CoreIR;
• move single-qubit gate fusion to its two production owners, QCEC and QMAP;
• remove the optimizer header, CMake target, sources, tests, installed export, and wheel dependency;
• move the retained behavioral tests into CoreIR and add empty-circuit member-contract coverage; and
• document every migration in the changelog and upgrade guide.

This implements the ownership split proposed in review while avoiding a separately distributed library for three functions.

Fixes #2088

Downstream drafts and release sequence

The downstream projects remain pinned to Core 3.9.x, so these PRs stay in draft until Core v4 is released. After the release, each project can update its Core pin, revalidate, and merge its migration:

• QCEC: munich-quantum-toolkit/qcec#1042
• QMAP: munich-quantum-toolkit/qmap#1125, stacked on #1111
• QuSAT: munich-quantum-toolkit/qusat#514
• DDSIM: munich-quantum-toolkit/ddsim#977
• Debugger: munich-quantum-toolkit/debugger#438, stacked on #436

Validation

• warning-clean static release build with WARNINGS_AS_ERRORS=ON
• fresh warning-clean shared package build (272/272 targets)
• 298/298 CoreIR tests
• 51/51 DDSIM QDMI-device tests
• static and shared installs contain the member declarations and no optimizer header, library, or exported CMake target
• minimal out-of-tree MQT::CoreIR consumer compiled, linked, and ran against both installs
• QCEC: 20/20 focused optimizer and 573/573 full C++ tests
• QMAP: 9/9 focused fusion, 41/41 QMapDS, and 11/11 NASP tests
• QuSAT: 11/11 full C++ tests
• DDSIM: 28/28 affected and 116/116 non-stochastic tests
• Debugger: 149/149 full C++ tests
• full uvx nox -s lint and git diff --check

AI assistance

Codex materially assisted with the organization-wide consumer census, implementation, tests, cross-repository validation, independent review, 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 and downstream 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.

[codecov]

Codecov Report

❌ Patch coverage is 94.49541% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/ir/CircuitOptimization.cpp	94.4%	6 Missing ⚠️

📢 Thoughts on this report? Let us know!

[burgholzer]

Just out of interest: how many users are there of the methods that are still here?
Or, right to the point, how bad would it be if we completely removed this and copied the implementation of the relevant methods into the respective libraries?

[simon1hofmann]

🤖 AI text below 🤖

I reran the production-use census across the current companion PR heads plus DDSIM and the Debugger:

Method	Production repositories	Direct production calls
singleQubitGateFusion	QCEC, QMAP	5
removeFinalMeasurements	Core, QCEC, QMAP, DDSIM	11
flattenOperations	QMAP, DDSIM, Debugger	7

This covers MQT production consumers; it does not count unknown external consumers.

A complete removal would therefore turn the three shared implementations into nine repository-local method copies across five production repositories:

• gate fusion in QCEC and QMAP;
• final-measurement removal in Core, QCEC, QMAP, and DDSIM;
• flattening in QMAP, DDSIM, and Debugger.

QuSAT has no production use after munich-quantum-toolkit/qusat#512, but its tests still use flattening and would need adjustment. The retained implementation is a 303-line source file backed by 16 focused tests.

Based on that, my inclination would be to keep the reduced three-method target: every remaining method is genuinely shared, and duplicating removeFinalMeasurements four times in particular seems like a maintenance regression. singleQubitGateFusion is the closest borderline case, with two consuming repositories.

Would you still prefer us to remove the target completely and localize all three implementations?

[burgholzer]

Hm. I do not quite like the fact that this is another shared library that needs to be distributed and appropriately handled downstream. So I'd have a slight preference for trying to remove it.

How about the following proposal

• move the single-qubit gate fusion to QCEC and QMAP
• turn flattening and final-measurement removal into member methods of the QuantumComputation class so that they are directly part of the MQT::CoreIR library and do not need to be placed separately

Would that make sense?

[simon1hofmann]

🤖 AI text below 🤖

Yes, that split makes sense, and it is now implemented:

• flattenOperations and removeFinalMeasurements are QuantumComputation member methods in MQT::CoreIR;
• single-qubit gate fusion is owned and tested independently by QCEC and QMAP; and
• the CircuitOptimizer header, library, CMake target, installed export, tests, and wheel dependency are removed from Core.

I re-audited every MQT repository and found no additional production consumers. Core passes 298/298 IR tests and 51/51 QDMI-device tests, warning-clean static/shared builds and installs, and out-of-tree MQT::CoreIR consumers in both modes.

The coordinated downstream migrations are open as drafts and will remain pinned to Core 3.9 until Core v4 is released:

• QCEC: #1042
• QMAP: #1125
• QuSAT: #514
• DDSIM: #977
• Debugger: #438

[burgholzer]

Nice! Let's get this in as soon as CI is green here!