template library organization

[ajavadia]

The template circuits used in the template optimization pass are currently stored in a directory under qiskit.circuit.library.templates. It would be better to store them in a proper library structure like the EquivalenceLibrary, where each entry in the library can be verified for correctness.

[born-2learn]

I would like to give this a try, @ajavadia.

[1ucian0]

hi @born-2learn ! Sorry this felt between the cracks. Are you still interested?

[ShellyGarion]

In addition, currently the picture of the circuit of the template appears as a comment in the code, but not in the documentation.
I would suggest to move it in a way that it will appear as part of the documentation.

[born-2learn]

I'll work on this, thanks!

[1ucian0]

Assigned! Thanks @born-2learn

[born-2learn]

Hi, I might have to delay working on this issue due to other engagements. Thanks!

[cometta]

Hello @ajavadia
can you explain more by giving an example how we should move clifford in temples/clifford folder into the root folder of qisikit.circuit please ?

[divshacker]

I can also give it a try, but I need some guidance regrading how to arrange and classify all the circuits at once.

[1ucian0]

The goal of this issue is to create a TemplateLibrary class, similar to EquivalenceLibrary, that can be extended with
TemplateLibrary.append.

[alexanderivrii]

fyi: @ShellyGarion

If I remember correctly, some of the clifford templates are only "up to the global phase", for instance the template S * H * S * H * S * H = Id.

I am wondering if this needs to be taken into account when reorganizing the templates.

We also have code that verifies templates; and again please note that self.assertTrue(target.equiv(value)) only checks equivalence up to the global phase.
`

[ajavadia]

Yes. The context for this is this review comment when the original templates were added to Qiskit
#4552 (comment)

A "template", by definition, is a circuit that is equivalent to the identity. So there must be some check somewhere that prohibits defining invalid templates. The ones that ship with Qiskit should be verified with CI. The user-defined ones must be verified when they are being defined as a template. So one way to do this is to make this a proper datastructure/library that contains various templates and additions to the library are checked. And then have methods for drawing the contents of the library. Also a method to reduce the library to some subset of the circuits would be useful. Then let the TemplateMatching transpiler pass accept a library or a subset of it.

And yes the equivalence to Identity should be exact including global phase.

[ShellyGarion]

Clifford group elements and templates are defined up to a global phase, e.g. the template S * H * S * H * S * H = Id is valid only up to a global phase.
Perhaps it's worth to add a filed to the templates indicating whether they are equal to id or equivalent up to a global phase?

[poig]

Is anyone working on this?

[1ucian0]

Hi @poig, it seems to me there were some attempts to approach the issues, but no PR open yet. This issue is part of the unitary hack initiative so I think it is fine if more than one person works on this. So feel free to jump in :)