Add more classes for 2q synthesis to qiskit synthesis docs

[ShellyGarion]

Summary

Following the discussions in #11460, #11635 and #11672, we properly add some more classes for 2q synthesis to qiskit synthesis docs.

Details and comments

[qiskit-bot]

One or more of the the following people are requested to review this:

• @Qiskit/terra-core
• @levbishop

[coveralls]

Pull Request Test Coverage Report for Build 7746292644

• 0 of 3 (100.0%) changed or added relevant lines in 3 files are covered.
• 10 unchanged lines in 2 files lost coverage.
• Overall coverage increased (+0.01%) to 89.381%

---

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	4	91.94%
crates/qasm2/src/parse.rs	6	97.62%

Totals
Change from base Build 7746232749:	0.01%
Covered Lines:	60155
Relevant Lines:	67302

---

💛 - Coveralls

[Cryoris]

A search through qiskit-community showed that only these two objects are used. I'd suggest we use this as criterion and only add those classes to the API docs that are really needed 🙂

[mtreinish]

I'm fine starting small, also looking at the code for all the specialized TwoQubitWeyl* variants it looks like they're all used internally by __new__ when you create a new TwoQubitWeylDecomposition object.

[jakelishman]

TwoQubitWeylDecomposer kind of implies that all the family classes are public in the sense of going to a lot of trouble to make a repr that you can eval back in (including pickling then b64'ing a Numpy array and making sure __new__ eats keywords that it throws in the repr just to be pretty) (it's a very busy constructor). That said, I don't really think it's necessary to make those public at all - they're largely not meant to be accessed directly, I think, because of the abstract factory class.

[mtreinish]

I did a quick search through the code, and confirmed that the only intended public interfaces are probably what @Cryoris pointed out in his review comments. The other classes were either added for internal features (such as QSD) or were magically dispatched for TwoQubitWeylDecomposition. So I restricted the changes in this PR to just the classes which seem to be intended for public use. If we do miss something here we can add the missing things to the public api in 1.1.0

[jakelishman]

This is already tagged for merge, but here's a review basically to say I agree.

[jakelishman]

I think this two_qubit_cnot_decompose is missing an .. autofunction:: in the docstring? If it's meant to be there, let's take a note to add it after rc1 - no need to hold up the PR over a documentation thing.

[mtreinish]

Ah, yeah good catch I missed that in the original review. I'll open an issue to track this. It actually will likely require a full docstring addition as it's doesn't have anything there now: https://github.com/Qiskit/qiskit/blob/main/qiskit/synthesis/two_qubit/two_qubit_decompose.py#L1553

it's a lazy loaded instance of TwoQubitBasisDecomposer using cx.

[jakelishman]

I actually already opened #11709 for it - forgot to comment here.

[ShellyGarion]

I also wasn't sure what to do with this function, since it has no docstring, and also due to the comment here:

qiskit/qiskit/synthesis/two_qubit/two_qubit_decompose.py

Line 1531 in a234ff2

# This weird duplicated lazy structure is for backwards compatibility; Qiskit has historically

[ShellyGarion]

Thanks for taking care of this PR

[jakelishman]

TwoQubitWeylDecomposer kind of implies that all the family classes are public in the sense of going to a lot of trouble to make a repr that you can eval back in (including pickling then b64'ing a Numpy array and making sure __new__ eats keywords that it throws in the repr just to be pretty) (it's a very busy constructor). That said, I don't really think it's necessary to make those public at all - they're largely not meant to be accessed directly, I think, because of the abstract factory class.