Circuit Library

Circuit Library

qiskit.circuit.library

The circuit library is a collection of well-studied and valuable circuits, directives, and gates. We call them valuable for different reasons, for instance they can serve as building blocks for algorithms or they are circuits that we think are hard to simulate classically.

Each element can be plugged into a circuit using the QuantumCircuit.append() method and so the circuit library allows users to program at higher levels of abstraction. For example, to append a multi-controlled CNOT:

from qiskit.circuit.library import MCXGate
gate = MCXGate(4)
 
from qiskit import QuantumCircuit
circuit = QuantumCircuit(5)
circuit.append(gate, [0, 1, 4, 2, 3])
circuit.draw('mpl')

The library is organized in several sections.

Standard gates

These operations are reversible unitary gates and they all subclass Gate. As a consequence, they all have the methods to_matrix(), power(), and control(), which we can generally only apply to unitary operations.

For example:

from qiskit.circuit.library import XGate
gate = XGate()
print(gate.to_matrix())             # X gate
print(gate.power(1/2).to_matrix())  # √X gate
print(gate.control(1).to_matrix())  # CX (controlled X) gate

[[0.+0.j 1.+0.j]
 [1.+0.j 0.+0.j]]
[[0.5+0.5j 0.5-0.5j]
 [0.5-0.5j 0.5+0.5j]]
[[1.+0.j 0.+0.j 0.+0.j 0.+0.j]
 [0.+0.j 0.+0.j 0.+0.j 1.+0.j]
 [0.+0.j 0.+0.j 1.+0.j 0.+0.j]
 [0.+0.j 1.+0.j 0.+0.j 0.+0.j]]

Standard Directives

Directives are operations to the quantum stack that are meant to be interpreted by the backend or the transpiler. In general, the transpiler or backend might optionally ignore them if there is no implementation for them.

Standard Operations

Operations are non-reversible changes in the quantum state of the circuit.

Generalized Gates

These “gates” (many are QuantumCircuit subclasses) allow to set the amount of qubits involved at instantiation time.

from qiskit.circuit.library import Diagonal
 
diagonal = Diagonal([1, 1])
print(diagonal.num_qubits)
 
diagonal = Diagonal([1, 1, 1, 1])
print(diagonal.num_qubits)

1
2

Boolean Logic Circuits

These are QuantumCircuit subclasses that implement boolean logic operations, such as the logical or of a set of qubit states.

Basis Change Circuits

These circuits allow basis transformations of the qubit states. For example, in the case of the Quantum Fourier Transform (QFT), it transforms between the computational basis and the Fourier basis.

Arithmetic Circuits

These QuantumCircuits perform classical arithmetic, such as addition or multiplication.

Amplitude Functions

Functional Pauli Rotations

Adders

Multipliers

Comparators

Functions on binary variables

Other arithmetic functions

Particular Quantum Circuits

N-local circuits

These BlueprintCircuit subclasses are used as parameterized models (a.k.a. ansatzes or variational forms) in variational algorithms. They are heavily used in near-term algorithms in e.g. Chemistry, Physics or Optimization.

Data encoding circuits

These BlueprintCircuit encode classical data in quantum states and are used as feature maps for classification.

Template circuits

Templates are functions that return circuits that compute the identity. They are used at circuit optimization where matching part of the template allows the compiler to replace the match with the inverse of the remainder from the template.

In this example, the identity constant in a template is checked:

from qiskit.circuit.library.templates import template_nct_4b_1
from qiskit.quantum_info import Operator
import numpy as np
 
template = template_nct_4b_1()
 
identity = np.identity(2 ** len(template.qubits), dtype=complex)
data = Operator(template).data
np.allclose(data, identity)  # True, template_nct_4b_1 is the identity

NCT (Not-CNOT-Toffoli) template circuits

Template circuits for XGate, CXGate, and CCXGate (Toffoli) gates.

Reference: Maslov, D. and Dueck, G. W. and Miller, D. M., Techniques for the synthesis of reversible Toffoli networks, 2007 http://dx.doi.org/10.1145/1278349.1278355

Clifford template circuits

Template circuits over Clifford gates.

RZXGate template circuits

Template circuits with RZXGate.