♻️ Refactor handling of gate matrices and inverses

[Joshy-R]

Description

These commits change how matrices are created from an OpType that reduces the number of switch statements necessary.
The downside of this approach is that some functions can be called with arguments that do not affect the returned value. As the user never calls these functions, I see this as acceptable.

I also removed the CX_MAT and CZ_MAT, as they are only used in tests and do not occur in any other repository.

Fixes #484

Checklist:

• The pull request only contains commits that are related to it.
• I have added appropriate tests and documentation.
• I have made sure that all CI jobs on GitHub pass.
• The pull request introduces no new warnings and follows the project's style guidelines.

I have not squashed the commits to make them easier to review, but I can squash them if desired.

[codecov]

Codecov Report

Attention: Patch coverage is 75.82090% with 81 lines in your changes missing coverage. Please review.

Project coverage is 91.8%. Comparing base (031f048) to head (c595265).
Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/ir/operations/OpType.cpp	30.9%	78 Missing ⚠️
include/mqt-core/dd/Operations.hpp	91.8%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##            main    #752     +/-   ##
=======================================
- Coverage   92.2%   91.8%   -0.5%     
=======================================
  Files        126     128      +2     
  Lines      13832   13857     +25     
  Branches    2153    2159      +6     
=======================================
- Hits       12762   12721     -41     
- Misses      1070    1136     +66     

Flag	Coverage Δ
cpp	91.5% <75.8%> (-0.5%)	⬇️
python	99.7% <ø> (ø)

Files with missing lines	Coverage Δ
include/mqt-core/ir/operations/OpType.hpp	83.3% <100.0%> (-8.2%)	⬇️
include/mqt-core/ir/operations/OpType.inc	100.0% <100.0%> (ø)
include/mqt-core/ir/operations/Operation.hpp	79.0% <100.0%> (-0.3%)	⬇️
src/circuit_optimizer/CircuitOptimizer.cpp	90.6% <100.0%> (-0.1%)	⬇️
src/dd/GateMatrixDefinitions.cpp	100.0% <100.0%> (ø)
src/dd/NoiseFunctionality.cpp	97.0% <100.0%> (-0.1%)	⬇️
src/dd/Simulation.cpp	93.4% <100.0%> (+<0.1%)	⬆️
src/ir/QuantumComputation.cpp	90.4% <ø> (ø)
src/ir/operations/AodOperation.cpp	98.7% <100.0%> (ø)
include/mqt-core/dd/Operations.hpp	82.9% <91.8%> (-4.5%)	⬇️
... and 1 more

... and 1 file with indirect coverage changes

[burgholzer]

Hey 👋

Many thanks for starting to work on this! Great to see someone taking this on!
I really like the solution with the flags for indicating the inverse type of a gate and indicating whether a gate is diagonal! Very elegant.

I added some inline comments that are mostlly minor except one bigger one that might trigger some further refactorings. However, I believe these might be worth it.

One thing on top of all of that: It would be great if you could address the clang-tidy complaints.
Typically these are posted as PR comments, but that feature does not work for PRs from forks. You can still see the warnings either in the check summary here: https://github.com/cda-tum/mqt-core/pull/752/checks or when looking through the "Files Changed" tab on GitHub.

Thanks again and let me know if anything is unclear!

[burgholzer]

Oops, clicked the wrong button 🙃

[burgholzer]

Many thanks for the iteration here. This is looking great already and I like where this is heading.
I went through everything in detail again and added my feedback inline. Hope that makes sense. Please let me know if it doesn't!

[Joshy-R]

I tried to implement your thoughts as good as possible. One change necessary to transition the test to retrieve the DD via the getDD and the StandardOperation class was to pass the standard operations as a const reference instead of a pointer. Also, this is closer to the semantics, as the code assumes the pointer is not null, and the code does not use the object's location information. This way, instead of writing dd::getDD(&(qc::StandardOperation){ 0, qc::RZ, {dd::PI_4}}, dd), we can write dd::getDD(qc::StandardOperation(0, qc::RZ, {dd::PI_4}), dd), which is a bit easier to read.

I hope this is a further improvement to the previous draft.

[Joshy-R]

I am also trying to understand why one CI build fails, but I don't see how my changes produced this error. Would you happen to have an idea, or would you be able to help me with that?

[burgholzer]

I am also trying to understand why one CI build fails, but I don't see how my changes produced this error. Would you happen to have an idea, or would you be able to help me with that?

That failure is unrelated to your changes and either due to an update in pandas or an update in uv. I very much suspect it's the latter as I remember reading something about the default resolution strategy changing.
I will have a look later.

[burgholzer]

I am also trying to understand why one CI build fails, but I don't see how my changes produced this error. Would you happen to have an idea, or would you be able to help me with that?

That failure is unrelated to your changes and either due to an update in pandas or an update in uv. I very much suspect it's the latter as I remember reading something about the default resolution strategy changing. I will have a look later.

Turns out it's something else entirely. It's due to ubuntu-latest switching from ubuntu-22.04 to ubuntu-24.04. That change comes with a new gcc version and that version doesn't seem to be particularly happy with building pandas from source. I'll quickly fix this up. pandas ships 3.13 wheels as of v2.2.3.

Edit: should be fixed with 34d57b2 in #769

[Joshy-R]

Okay, thanks. Then, I will rebase onto the new main so that the test passes again. Do you have any further change requests regarding my pull request?

[burgholzer]

Okay, thanks. Then, I will rebase onto the new main so that the test passes again. Do you have any further change requests regarding my pull request?

Sounds good.
I am on it ☝️ I might have one or two more requests.

[burgholzer]

Many thanks again for your work on this!
I really like the way this is going and how it simplifies certain aspects in the library.
I feel we are really close to the finish line here. There are a couple of errors that snuck their way into the last couple of commits and some further suggestions for getting the implementation even cleaner and more performant.
I am fairly optimistic that this will be the last round of iteration.

[burgholzer]

@Joshy-R gentle ping just in case this might have flown under the radar.

A couple of bits and pieces changed over the last couple of weeks that lead to merge conflicts here. However, these should be easy to resolve (hopefully).

[Joshy-R]

No worries, I will take a look at this over the weekend and implement the requested changes.

[Joshy-R]

I have implemented most of the requested changes (see comment above). macos-14 is failing due to some caches. Retriggering the pipeline will likely fix the issue.

Please let me know if you would like me to make any changes.

[burgholzer]

I have implemented most of the requested changes (see comment above). macos-14 is failing due to some caches. Retriggering the pipeline will likely fix the issue.

Please let me know if you would like me to make any changes.

Thanks for your work on this. I'll try to have a look at your changes later today or early tomorrow.
I also triggered a re-run of the workflow in question. Have not seen that error in the past 🙃

[burgholzer]

Many thanks for another round of changes.
I just went through the PR and made some final adjustments.
I also added the extensive-cpp-ci label, which kicks off a whole set of CI runs under different OSes and compilers, and checks whether everything still works.
Depending on how this goes, this is ready to go in 🚀

Many thanks again for your contribution. Great work. 🙌🏼

[burgholzer]

Just pushed another small commit (c595265), where the main aim was to get some coverage for the lines that were reported uncovered. This has led me to an intersting observation on this PR:
I just compared Python binary wheel sizes from before this PR, before c595265, and with c595265.

lib	v3.0.0b3	before c595265 (diff to v3.0.0b3)	after c595265 (diff to v3.0.0b3)
libmqt-core-algorithms.so	109464	80688 (-26%)	80688 (-26%)
libmqt-core-circuit-optimizer.so	150608	146536 (-2.7%)	134208 (-10.9%)
libmqt-core-dd.so	562592	525664 (-6.6%)	525664 (-6.6%)
libmqt-core-ds.so	64104	60024 (-6.4%)	59952 (-6.5%)
libmqt-core-ir.so	1212752	1139120 (-6.1%)	1130928 (-6.7%)
libmqt-core-na.so	64000	47616 (-25.6%)	39256 (-38.7%)
libmqt-core-zx.so	310912	306808 (-1.3%)	298568 (-4%)
ir.cpython	524528	499952 (-4.7%)	495856 (-5.5%)
Overall	2998960	2806408 (-6.4%)	2765120 (-7.8%)

which is quite impressive for such a considerably small change ⚡

[burgholzer]

Our coverage collection certainly does not like const static variables in functions.
I suspect that even at the lowest optimization level, which we use for coverage collection, this is optimized in some form where the coverage data cannot be mapped to the respective lines. I guess it is what it is and we are going to have to live with that.