Oxidize TwoQubitWeylDecomposition (#11946)

* Oxidize TwoQubitWeylDecomposition

This commit is part 1 of migrating the default 2q unitary synthesis to leverage
parallel rust described in #8774, the eventual goal is to be able to
run unitary synthesis in parallel for all the unitary matrices in a
circuit in a single call from the `UnitarySynthesis` pass. This commit
lays the initial groundwork for doing this by starting with the largest
piece of the default 2q unitary synthesis code, the
TwoQubitWeylDecomposition class. It migrates the entire class
to be a pyclass in rust. There is still a Python subclass for it that
handles the actual QuantumCircuit generation and also the string
representations which are dependent on circuit generation. The goal of
this is to keep the same basic algorithm in place but re-implement
as-is in Rust as a common starting point for eventual improvements to
the underlying algorithm as well as parallelizing the synthesis of
multiple 2q unitary matrices.

* Fix typo in closest_partial_swap()

This commit fixes a typo the formula in the function.
This is the same fix from #11953.

Co-authored-by: Shelly Garion <46566946+ShellyGarion@users.noreply.github.com>

* Run black and lint

* Fix potential imaginary component sign flip in determinant

* Run cargo fmt

* Simplify using numpy eigh example comment

* Add missing checks to decompose_two_qubit_product_gate()

* Use rng first trial from Python implementation

To aid in debugging and rule out rng differences causing different
results this commit switches the first iteration of the randomized loop
to have hard coded values that are identical to what the rng in numpy
was returning. It is very unlikely that this will have any impact
because the specific random numbers used shouldn't matter, this is
mostly to just rule it out as a possibility in debugging the remaining
test failures.

* Fix whitespace in error message

* Fix assert check

* Fix missing multiplier on specialized weyl gate

* Fix various mistakes

This commit fixes two fundamental issues in the code. The first is the
rz and ry matrix were being incorrectly constructed for a given angle.
This caused the specializations that were computing the 1q matrices in
the decomposition based on a product with these gates' matrices to
return invalid results. The second issue is for the MirrorControlledEquiv
specialization had the angles backwards for computing the matrix of the
rz gates used in the products for the 1q matrices:

`K1l = K1l @ Rz(K1r)` and `K1r = K1r @ Rz(K1l)` not
`K1l = K1l @ Rz(K1l)` and `K1r = K1r @ Rz(K1r)`

This was a typo from the original transcription.

* Add pickle serialization support for TwoQubitWeylDecomposition

* Remove duplicate conjs increment

* Fix fSim abmb equivalent specialization

* Add specialized test class back

* Use QiskitError for backwards compatibility

* Add release note

* Make explicit specialization private

* Use explicit inheritance from general decomposition (#23)

* Apply suggestions from code review

* Use smallvec for circuit sequence params and qubits

* Use const 2x2 identity array where possible

* circuit() and weyl_gate don't need a mutable self

* Remove unnecessary inline annotations

* Rename Specializations enum Specialization

* Add back specialize() method and deprecate

* Reorganize Python/Rust split to wrap rust instead of subclass

This commit reworks the handoff between python and rust space for the
TwoQubitWeylDecomposition class. Previously the Python side
TwoQubitWeylDecomposition was a subclass of the Rust struct/pyclass of
the same name. This was originally done to deduplicate the the getters
for the attributes. However, because of the overhead associated with
some of the rust getters and needing to do some import normalization to
a numpy array the deduplication wasn't worth the cost.

* Remove unecessary allocations

* Rename DEFAULT_ATOL to ANGLE_ZERO_EPSILON

* Stop obsessing over -0

* Handle enum to int conversion as method

* Cleanup decompose_two_qubit_product_gate()

* Use a trait for trace_to_fid()

* Use an enum instead of string for euler basis

* Fix release note typo

* Improve magic basis transformation functions

Co-authored-by: Jake Lishman <jake.lishman@ibm.com>

* Remove eigh() util function

* Revert unecessary changes to callers of TwoQubitWeylDecomposition

* Restore debug logging and add test assertions for it

* Update qiskit/synthesis/two_qubit/two_qubit_decompose.py

Co-authored-by: Lev Bishop <18673315+levbishop@users.noreply.github.com>

* Add specialization to __str__

* Add previous specialized class docstrings as inline rust code comments

* Rename fSim variants and suprress rustc warning about camel case

* Update tests for correct specialization enum name

* Expose specialization enum via private class attr and use for __repr__

---------

Co-authored-by: Shelly Garion <46566946+ShellyGarion@users.noreply.github.com>
Co-authored-by: Jake Lishman <jake@binhbar.com>
Co-authored-by: Jake Lishman <jake.lishman@ibm.com>
Co-authored-by: Lev Bishop <18673315+levbishop@users.noreply.github.com>

crates/accelerate/Cargo.toml

@@ -33,11 +33,15 @@ features = ["union"]
 
 [dependencies.pyo3]
 workspace = true
-features = ["hashbrown", "indexmap", "num-complex", "num-bigint"]
+features = ["hashbrown", "indexmap", "num-complex", "num-bigint", "smallvec"]
 
 [dependencies.ndarray]
 version = "^0.15.6"
-features = ["rayon"]
+features = ["rayon", "approx-0_5"]
+
+[dependencies.approx]
+version = "0.5"
+features = ["num-complex"]
 
 [dependencies.hashbrown]
 workspace = true