Add library of gates with their equivalent circuit implementations.

[kdk]

Summary

Adds EquivalenceLibrary structure from Qiskit/RFCs#6 .

Details and comments

[ajavadia]

it looks good

[ajavadia]

Suggested change

	base - Base equivalence library to will be referenced if an entry is
	base - Base equivalence library to which will be referenced if an entry is

[1ucian0]

maybe compare sets?

Suggested change

	self.assertTrue(
	(entry[0] == first_equiv and entry[1] == second_equiv)
	or (entry[1] == first_equiv and entry[0] == second_equiv))
	self.assertEqual(set(entry), set([first_equiv, second_equiv])

Why not return them in order?

[kdk]

Was on the fence about what the ordering should be. Ideas? (Insertion order oldest to newest from self to base is what we'll get now, I think.)

[1ucian0]

my original comments was for being independent of the order. But I see value in keeping some deterministic order. That might be a proto-way to define priorities. I think entry[0] == newest... maybe a stack?

[kdk]

I would've preferred a set as well (for the return type and the assertion) but QuantumCircuits aren't hashable (as they're mutable). Agree deterministic order is good, but the caller should inspect the returned circuit to determine priority, so the exact order shouldn't be so important. I'll document the current order and remove the ors in the test.

[kdk]

Done in 7378cec .

[1ucian0]

I'm not fully sure if this works or should work...

        eq_lib = EquivalenceLibrary()

        theta = Parameter('theta')
        phi = Parameter('phi')

        gate = OneQubitTwoParamGate(theta, phi)  
        equiv1 = QuantumCircuit(1)
        equiv1.u2(theta, phi, 0)                             # theta,phi

        eq_lib.add_equivalence(gate, equiv1)

        equiv2 = QuantumCircuit(1)
        equiv2.u2(phi, theta, 0)                            # phi,theta
        eq_lib.add_equivalence(gate, equiv2)

[kdk]

I'm not fully sure if this works or should work...

...

This will work now, but maybe the behavior isn't obvious. What would you expect in this case?

>>> eq_lib = EquivalenceLibrary()
>>> theta = Parameter('theta')
>>> phi = Parameter('phi')
>>> gate = OneQubitTwoParamGate(theta, phi)
>>> equiv1 = QuantumCircuit(1)
>>> equiv1.u2(theta, phi, 0)
>>> eq_lib.add_equivalence(gate, equiv1)
>>> equiv2 = QuantumCircuit(1)
>>> equiv2.u2(phi, theta, 0)
>>> eq_lib.add_equivalence(gate, equiv2)
>>> alpha = Parameter('alpha')
>>> beta = Parameter('beta')
>>> gate_query = OneQubitTwoParamGate(alpha, beta)
>>> entry = eq_lib.get_entry(gate_query)
>>> for circ in entry:
...   print(circ)
...
        ┌────────────────┐
q_0: |0>┤ U2(alpha,beta) ├
        └────────────────┘
        ┌────────────────┐
q_0: |0>┤ U2(beta,alpha) ├
        └────────────────┘

The above is saying that the gate is arg symmetric (both U2(a,b) and U2(b,a) implement 1q2p(a,b)). I can make it clearer in the docs that the mapping between the parameters of the gate and the paramters in the circuit is what is preserved in the library (and what will be reflected between the query gate and the returned circuits.)

[ajavadia]

mapping between the parameters of the gate and the paramters in the circuit is what is preserved in the library (and what will be reflected between the query gate and the returned circuits.)

yes this sounds like a good behavior.