# How do I build a gate from a matrix on Qiskit?

I'm creating a gate for a project and need to test if it has the same results as the original circuit in a simulator, how do I build this gate on Qiskit? It's a 3 qubit gate, 8x8 matrix:

$$\frac{1}{2} \begin{bmatrix} 1 & 0 & 1 & 0 & 0 & 1 & 0 & -1 \\ 0 & 1 & 0 & 1 & 1 & 0 & -1 & 0 \\ 0 & 1 & 0 & -1 & 1 & 0 & 1 & 0 \\ 1 & 0 & -1 & 0 & 0 & 1 & 0 & 1 \\ 1 & 0 & 1 & 0 & 0 & -1 & 0 & 1 \\ 0 & 1 & 0 & 1 & -1 & 0 & 1 & 0 \\ 0 & 1 & 0 & -1 & -1 & 0 & -1 & 0 \\ 1 & 0 & -1 & 0 & 0 & -1 & 0 & -1 \end{bmatrix}$$

• Ideally you would do this by telling qiskit that you want the gate specified by this matrix. I'm not sure that feature exists yet, but I'm trying to find out. – James Wootton Dec 18 '18 at 10:55
• @Nillmer Your original circuit needs this gate or you need to check if the circuit corresponds to this unitary? – cnada Dec 19 '18 at 3:16
• @cnada I need to check if the circuit corresponds to this unitary. – Nillmer Dec 19 '18 at 11:45
• @Nillmer See my answer and tell me if that would do the job. – cnada Dec 19 '18 at 12:44

I don't think Qiskit has this simulation feature. You have to decompose it indeed.

However, there is another way to solve your problem. To check if a quantum circuit (that you can submit in Qiskit) corresponds to a unitary matrix, you can use the unitary_simulator backend.

# Run the quantum circuit on a unitary simulator backend
backend = Aer.get_backend('unitary_simulator')
job = execute(circ, backend)
result = job.result()
print(np.around(result.get_unitary(circ), 3))


This will print the unitary matrix that your circuit represents. And you can compare to yours.

You can build your gate with Operator and unitary function e.g:

from qiskit import QuantumCircuit, QuantumRegister
from qiskit.quantum_info.operators import Operator

controls = QuantumRegister(2)
circuit = QuantumCircuit(controls)

cx = Operator([
[1, 0, 0, 0],
[0, 0, 0, 1],
[0, 0, 1, 0],
[0, 1, 0, 0]
])
circuit.unitary(cx, [0, 1], label='cx')

Output:
┌──────────┐
q0_0: |0>┤0         ├
│  unitary │
q0_1: |0>┤1         ├
└──────────┘


This is identical to:

circuit.cx(controls[0], controls[1])

Output:

q0_0: |0>──■──
┌─┴─┐
q0_1: |0>┤ X ├
└───┘


• Thank you! This explanation cleared up much confusion. – user727041 Nov 29 '19 at 22:57

Here's the circuit for your specific case:

I made it manually, by entering the matrix into Quirk, diagonalizing the matrix by adding operations, then simplifying the operations. It's not too hard to do by hand when all the operations are Clifford as in this case.

• That last column looks weird. I guess since CNOT and Z commute, it puts them on the same column regardless of whether looks like a CZ. Would prefer a diagram overlap check before it draws the circuit. – AHusain Dec 18 '18 at 23:43
• @AHusain It's a CZ and a CNOT, not a Z and a CNOT. The overlap is intentional and means "each of those operations is controlled by the control". – Craig Gidney Dec 19 '18 at 1:22
• Ok. Would it overlap like that in the CNOT and Z case as well? Or would they separate? Ideally the diagram should not be ambiguous as to which lines connect where. – AHusain Dec 19 '18 at 2:20
• @AHusain If it was a Z gate it would have to be placed on a separate vertical column. Otherwise it would be ambiguous, as you note. – Craig Gidney Dec 19 '18 at 3:06
• I would be extremely grateful if you could elaborate on the logic you use to build the circuit on quirk. I am in the same situation i.e. I need to find the gate decomposition of a specific matrix. Instead of creating a redundant question, I figured if you could briefly explain what logical step to use to achieve that result in quirk it would be of help. – Enrico Jul 24 at 8:05

Qubiter uses a CSD compiler for a Unitary matrix to a sequence of elementary operations tranformation

One setback is that qubiter needs extra packages so installing could be troublesome.

You can't directly build a gate from arbitrary matrices because custom gates need to be implemented using the build-in gates.

You have to decompose your matrix to known gates.

For a random two-qubit gate, there is two_qubit_kak:

two_qubit_kak (unitary_matrix, verify_gate_sequence=False)

Decompose a two-qubit gate over CNOT + SU(2) using the KAK decomposition.

Based on MATLAB implementation by David Gosset.

Computes a sequence of 10 single and two qubit gates, including 3 CNOTs, which multiply to U, including global phase. Uses Vatan and Williams optimal two-qubit circuit (quant-ph/0308006v3). The decomposition algorithm which achieves this is explained well in Drury and Love, 0806.4015.